Claude Code Agent Teams là gì? Cách phối hợp nhiều AI agent để làm việc song song

Claude Code đã có khá nhiều tính năng mạnh như Slash Commands, Agent Skills hay Channels. Nhưng đến Agent Teams thì cách dùng Claude Code thay đổi rõ hơn: thay vì một agent chính làm mọi việc, bạn có thể để nhiều phiên Claude Code phối hợp như một nhóm nhỏ, có người điều phối, có người nhận việc, có người phản biện.

Mình đã lab thử trực tiếp tính năng này trên máy trước khi viết. Claude Code bản cài trên máy là 2.1.92, đủ điều kiện để bật Agent Teams. Hai vòng lab nhỏ cho thấy feature này chạy được thật, có tạo trạng thái local trong ~/.claude/teams/ và ~/.claude/tasks/, đồng thời cho ra kết quả khá hợp lý khi chia việc theo nhiều giả thuyết song song.

ℹ️ Agent Teams hiện vẫn là tính năng experimental. Bạn cần bật cờ CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 trước khi dùng.

Agent Teams trong Claude Code là gì?

Hiểu nhanh thì Agent Teams là cơ chế để nhiều phiên Claude Code làm việc cùng lúc trên một bài toán chung. Một phiên đóng vai trò team lead, chịu trách nhiệm tạo team, chia task, theo dõi tiến độ và tổng hợp kết quả. Các phiên còn lại là teammates, mỗi phiên có context riêng, có thể làm việc độc lập và gửi thông điệp cho nhau.

Điểm khác biệt nằm ở chỗ các teammate không chỉ báo cáo ngược về lead. Chúng có thể cùng nhìn vào một task list dùng chung, nhận việc, hoàn thành việc, rồi phối hợp với nhau nếu cần. Với những bài toán có nhiều nhánh nghiên cứu hoặc nhiều phần việc tách biệt, cách làm này hợp lý hơn kiểu một agent chính phải ôm toàn bộ context.

Agent Teams khác gì với Subagents?

Nếu bạn đã đọc bài Subagents trong Claude, phần này sẽ dễ hình dung hơn.

Nôm na là vậy: Subagents giống như bạn giao việc cho trợ lý phụ rồi đợi báo cáo. Còn Agent Teams giống như bạn dựng một nhóm nhỏ, có người phụ trách từng phần và có trao đổi qua lại trong lúc làm.

💡 Nếu bạn chỉ cần một agent phụ đi tìm thông tin hoặc kiểm tra nhanh một phần của codebase, subagents thường hợp hơn. Agent Teams nên để dành cho task thật sự có thể song song hóa.

Khi nào nên dùng Agent Teams?

Theo docs chính thức và cả trải nghiệm lab thực tế, Agent Teams phát huy tác dụng tốt trong vài tình huống sau.

• Research và review song song: mỗi teammate phụ trách một góc nhìn, ví dụ bảo mật, hiệu năng, test coverage.
• Debug với nhiều giả thuyết: mỗi teammate theo một hướng điều tra khác nhau để tránh bị lệch theo giả thuyết đầu tiên.
• Feature chia thành nhiều phần tương đối độc lập: frontend, backend, tài liệu, test.
• Cross-layer coordination: một thay đổi đụng cả ứng dụng, API và lớp kiểm thử.

Trong lab của mình, vòng thử nghiệm thứ hai dùng 3 teammate để debug một lỗi giả định: trợ lý terminal xử lý xong một tin nhắn thì đôi khi tự thoát. Mỗi teammate theo một giả thuyết riêng, gồm lifecycle, connection và error-path. Kết quả khá hay, cả 3 nhánh đều hội tụ về nhóm nguyên nhân mạnh nhất là vòng lặp chính bị lỗi hoặc có race condition trong xử lý async. Với kiểu bài toán như vậy, Agent Teams cho cảm giác tự nhiên hơn một session đơn phải tuần tự đi từng giả thuyết.

Khi nào không nên dùng?

Agent Teams không phải chế độ mặc định cho mọi việc. Nếu dùng không đúng chỗ, bạn sẽ tốn token mà lợi ích tăng không tương xứng.

• Task ngắn, chỉ vài bước, không cần chia vai.
• Nhiều việc cùng chạm vào một file hoặc cùng phụ thuộc một kết quả trung gian.
• Task tuần tự, bắt buộc làm bước 1 rồi mới đến bước 2.
• Trường hợp cần tiết kiệm token và giảm độ phức tạp vận hành.

Lab round 2 cũng cho thấy một điểm khá thực tế: khi input còn mơ hồ, nhiều teammate có thể suy luận chồng lấn lên nhau. Kết quả vẫn hữu ích, nhưng không phải cứ tăng số lượng teammate là chất lượng tăng theo.

⚠️ Với task nhỏ hoặc ít khả năng tách nhánh, Agent Teams thường có thêm coordination overhead mà không mang lại lợi ích rõ ràng.

Điều kiện để bật Agent Teams

Tại thời điểm viết bài, Agent Teams cần Claude Code phiên bản 2.1.32 trở lên. Ngoài ra, đây vẫn là tính năng thử nghiệm nên bạn phải bật bằng biến môi trường hoặc trong file cấu hình.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "in-process"
}

Nếu muốn kiểm tra bản Claude Code đang dùng, bạn có thể chạy lệnh sau:

# Kiểm tra phiên bản Claude Code
claude --version

Trong lab trên máy, lệnh này trả về 2.1.92, nên đủ điều kiện để bật và thử Agent Teams.

Cách bắt đầu một Agent Team đầu tiên

Nếu bạn cần một bài hướng dẫn step by step rõ ràng, đây là workflow ngắn nhất mình đã dùng để lab ngay trên máy.

Bước 1: tạo file settings để bật Agent Teams

# Tạo settings riêng cho lab Agent Teams
mkdir -p temp/agent-teams-lab
cat > temp/agent-teams-lab/settings.json <<'JSON'
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "in-process"
}
JSON

Mình tách riêng một file settings cho lab để dễ kiểm soát. Cách này tiện hơn việc sửa config global nếu bạn có ý định test thử trên một dự án mới.

Bước 2: chạy một prompt nhỏ để Claude Code tự tạo team

# Chạy Claude Code với Agent Teams đã bật
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude --print --permission-mode bypassPermissions \
  --settings temp/agent-teams-lab/settings.json \
  'Create a very small agent team with 2 teammates: one UX, one architecture. Work only in ~/workspace/temp/agent-teams-lab. Evaluate a tiny CLI TODO tracker idea. Write concise findings to ~/workspace/temp/agent-teams-lab/lab-report.md. Then summarize in your final response. Keep it small.'

Prompt trên cố tình rất hẹp: chỉ có 2 teammate, một teammate nhìn theo UX, một teammate nhìn theo architecture. Mục tiêu là kiểm tra xem Claude Code có tạo team thật, chạy song song thật và ghi kết quả ra file hay không.

Bước 3: đọc output thực tế trong file report

# Agent Team Lab Report: CLI TODO Tracker
## UX Evaluation
- Fuzzy matching for completion/deletion (`todo done milk` instead of IDs)
- Colorized summary mode with counts by priority
- Support piping (`todo list | grep shopping`)
## Architecture Evaluation
- Stack: Node.js + Commander.js, native fs, JSON file storage
- Concurrent writes can corrupt JSON, so atomic writes are needed
- Keep dependencies minimal
## Combined Takeaway
The CLI TODO tracker is a viable micro-tool for developer workflows.

Phần này là output thật rút gọn từ file lab trên máy. Nó cho thấy team lead đã nhận lại kết quả từ hai teammate và tổng hợp thành một kết luận chung. Với bài toán review ý tưởng hoặc đánh giá nhiều góc nhìn, Agent Teams làm phần này khá gọn.

Bước 4: kiểm tra artifact local Claude Code tạo ra

# Kiểm tra team config và task storage sau khi lab
cat ~/.claude/teams/idea-eval-lab/config.json
ls -la ~/.claude/teams/idea-eval-lab
ls -la ~/.claude/tasks/idea-eval-lab

Claude Code thực sự tạo trạng thái local trên máy. Ví dụ trong file config.json của team mình thấy rõ các member như team-lead, ux-reviewer, arch-reviewer, model đang dùng, prompt của từng teammate và working directory.

{
  "name": "idea-eval-lab",
  "leadAgentId": "team-lead@idea-eval-lab",
  "members": [
    {
      "name": "team-lead",
      "agentType": "team-lead"
    },
    {
      "name": "ux-reviewer",
      "agentType": "general-purpose",
      "backendType": "in-process"
    },
    {
      "name": "arch-reviewer",
      "agentType": "general-purpose",
      "backendType": "in-process"
    }
  ]
}

Bước 5: thử một use case debug nhiều giả thuyết

Use 3 teammates with these roles:
- lifecycle investigator
- connection investigator
- error-path investigator
Investigate why a terminal chat assistant sometimes exits after one message.
Have them produce concise findings and synthesize a final conclusion.

Đây là lab vòng hai mình dùng để kiểm tra một use case sát thực tế hơn. Điểm mình muốn xem là: khi có nhiều giả thuyết cạnh tranh, Agent Teams có giúp tách nhánh suy nghĩ tốt hơn không.

## Investigation Team
| Investigator | Hypothesis | Confidence |
|---|---|---|
| Lifecycle | Session lifecycle / shutdown bug | Medium |
| Connection | Transport or connection management issue | Medium |
| Error-Path | Error handling path that ends the main loop | Low-to-Medium |
## Most Likely Root Cause Candidates
1. Broken or missing main loop
2. Async race condition / task cancellation
3. Non-deterministic error swallowed silently

Output thật của round 2 cho thấy ba teammate đi theo ba nhánh khác nhau, rồi hội tụ về nhóm nguyên nhân mạnh nhất. Nếu bạn đang muốn dùng Agent Teams cho debugging, đây là một pattern rất đáng thử.

💡 Với debugging đa giả thuyết, nên brief mỗi teammate theo một hướng điều tra thật cụ thể. Nếu brief mơ hồ, các teammate dễ chồng lấn lên nhau và làm mất lợi thế song song.

Display mode, task list và cách điều khiển team

Agent Teams hiện hỗ trợ hai kiểu hiển thị chính:

• in-process: mọi teammate chạy trong terminal chính, bạn chuyển qua lại giữa các teammate.
• split panes: mỗi teammate có một pane riêng, phù hợp khi bạn muốn theo dõi nhiều nhánh cùng lúc. Cách này cần tmux hoặc iTerm2.

Theo docs, Claude Code sẽ tự dùng split-pane nếu môi trường phù hợp. Còn trong lab của mình, mình chủ động dùng in-process để scope gọn hơn và giảm yếu tố phát sinh từ tmux.

Một điểm hay của Agent Teams là có shared task list. Lead có thể giao task, teammates cũng có thể tự nhận task còn trống nếu không bị chặn bởi dependency. Hệ thống dùng file locking để tránh hai teammate cùng chộp một việc.

Agent Teams làm được gì trong lab thực tế?

Phần này là chỗ mình thấy đáng giá nhất khi viết về Agent Teams. Nếu chỉ đọc docs, bạn sẽ nắm được lý thuyết. Nhưng khi chạy lab thật, vài điểm thực tế lộ ra rất rõ.

• Team được tạo thật và có trạng thái local trong ~/.claude/teams/.
• Task list cũng tồn tại local trong ~/.claude/tasks/.
• Teammates có thể chạy song song và cho ra kết quả đủ khác nhau để tổng hợp.

Một vài trường hợp đáng thử nghiệm

Nếu bạn đang dùng Claude Code cho công việc hằng ngày, có thể bắt đầu với ba kiểu use case này.

• Review code theo nhiều tiêu chí: tách một teammate kiểm tra bảo mật, một teammate kiểm tra hiệu năng, một teammate rà test.
• Debug đa giả thuyết: mỗi teammate theo một hướng điều tra riêng, sau đó lead tổng hợp hướng nào đáng theo tiếp.
• Xây feature nhiều lớp: một teammate lo API, một teammate lo frontend, một teammate lo test hoặc tài liệu.

Với anh em làm WordPress hoặc quản trị máy chủ, mô hình này cũng có đất diễn. Ví dụ bạn muốn kiểm tra một plugin nội bộ: một agent đọc code để tìm chỗ dễ lỗi, một agent rà phần hiệu năng, một agent chuẩn bị checklist test. So với việc nhồi hết vào một prompt dài, cách này đỡ nặng context hơn.

Có nên dùng Agent Teams hằng ngày không?

Có, nhưng nên dùng như một công cụ chuyên biệt. Agent Teams hợp khi bài toán đủ lớn, đủ nhiều nhánh và đủ độc lập để tách ra. Còn với các việc thường ngày, một session Claude Code chuẩn hoặc subagents vẫn gọn và tiết kiệm hơn.

Nếu đang cần một môi trường ổn định để chạy CLI tools, AI workflows hoặc các lab kiểu này lâu dài, bạn có thể tham khảo các VPS. Với bài toán test công cụ dòng lệnh, chạy terminal multiplexing hay dựng môi trường riêng để thử nhiều workflow AI, một VPS gọn gàng vẫn dễ kiểm soát hơn việc dồn tất cả vào máy cá nhân.

Claude Code Agent Teams là gì?

Đây là tính năng cho phép nhiều phiên Claude Code phối hợp với nhau trên một task list dùng chung. Một phiên làm team lead, các phiên còn lại làm teammates với context riêng.

Agent Teams khác gì với Subagents?

Subagents chỉ báo cáo về agent chính, còn Agent Teams cho phép các teammate trao đổi trực tiếp với nhau và cùng phối hợp qua shared task list.

Khi nào nên dùng Agent Teams?

Nên dùng khi task có thể chia thành nhiều nhánh độc lập như research song song, review nhiều góc nhìn, debug theo nhiều giả thuyết hoặc triển khai feature nhiều lớp.

Agent Teams có tốn token hơn không?

Có. Mỗi teammate là một phiên riêng với context riêng nên token usage tăng theo số lượng agent hoạt động.

Có cần bật cấu hình riêng để dùng Agent Teams không?

Có. Ở thời điểm hiện tại, bạn cần bật biến cấu hình CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 và dùng Claude Code phiên bản hỗ trợ tính năng này.