Orchestrate nhiều subagents trong Claude Code: xây workflow phức tạp (2026)

- surface điều phối agent đổi nhanh (agent teams, giới hạn depth), số liệu đã đối chiếu với docs Claude Code và bài nghiên cứu của Anthropic tại thời điểm viết.

Orchestrate subagents là gì?

Khi bạn đã quen tạo và chạy một subagent lẻ, bước tiếp theo là orchestrate subagents trong Claude Code: để một agent chính điều phối nhiều subagent worker cùng lúc hoặc nối chúng thành chuỗi. Đây là mô hình kinh điển orchestrator-worker (còn gọi là lead agent điều phối các worker).

Định nghĩa ngắn để nắm nhanh: orchestrate subagents nghĩa là một agent điều phối (orchestrator) spawn nhiều subagent, mỗi subagent làm một phần việc trong context window riêng biệt của nó, rồi trả về một bản summary gọn cho agent chính tổng hợp.

Điểm mấu chốt nằm ở chữ "context riêng". Mỗi subagent có cửa sổ ngữ cảnh độc lập, nên nó có thể đọc hàng chục file, chạy nhiều lệnh, sinh ra output dài mà không làm phình context của phiên chính. Agent chính chỉ nhận lại phần chắt lọc. Nhờ vậy bạn xử lý được tác vụ lớn nhiều nhánh mà cửa sổ ngữ cảnh của phiên gốc vẫn "sạch".

Đây là năng lực nâng cao. Nếu bạn chưa nắm subagent là gì và cách khai báo một cái cơ bản, hãy đọc hướng dẫn subagents từ cơ bản trước rồi quay lại đây. Bài này giả định bạn đã tạo được ít nhất một subagent và giờ muốn chỉ huy nhiều subagent cùng lúc - thứ mà tài liệu tiếng Việt gần như chưa có ai hướng dẫn end-to-end.

Khi nào NÊN và KHÔNG NÊN orchestrate nhiều subagent

Điều phối nhiều agent không phải lúc nào cũng tốt. Nó đắt token và thêm độ trễ, nên chỉ đáng khi tác vụ thực sự chia được thành các nhánh. Đây là phần quyết định giá trị nhất mà docs và blog thường lướt qua.

Con số 15× token và cảnh báo về shared state đến từ bài Multi-Agent Research System của Anthropic (13/06/2025). Bài đó cũng nói phần lớn (khoảng 80%) độ biến thiên hiệu năng đến từ lượng token tiêu thụ - tức token vừa là chi phí, vừa là đòn bẩy. Quy tắc thực dụng: nếu bạn không diễn đạt được tác vụ thành các nhánh rõ ràng, đừng orchestrate - cứ dùng một phiên tuyến tính. Muốn hiểu subagent nằm ở đâu so với skills, hooks và MCP, xem bài phân biệt skills, subagents, hooks & MCP.

2 kiểu orchestration: song song (parallel) vs pipeline (nối tiếp)

Có đúng hai mô hình nền tảng. Nắm được khi nào dùng cái nào là bạn đã đi trước hầu hết dev.

Song song (fan-out / fan-in): agent chính spawn nhiều subagent cùng lúc, mỗi cái làm một nhánh độc lập, rồi agent chính gom (fan-in) các summary lại thành một kết quả.

 ┌─→ subagent: auth ────┐
main agent ├─→ subagent: database ─┤─→ tổng hợp
 └─→ subagent: API ─────┘
 (fan-out song song) (fan-in)

Pipeline (chain / nối tiếp): các subagent chạy theo thứ tự, đầu ra của bước trước là đầu vào của bước sau. Agent chính chuyền context giữa các mắt xích.

main → subagent: reviewer → subagent: optimizer → kết quả
 (tìm lỗi) (dựa trên lỗi để sửa)

Mẹo phân biệt trong một câu: nếu các nhánh KHÔNG cần biết kết quả của nhau → song song; nếu bước B cần kết quả bước A → pipeline. Nhiều workflow thực tế là lai: fan-out song song ở giai đoạn thu thập, rồi nối tiếp một bước tổng hợp cuối.

Ví dụ 1 - Chạy subagents SONG SONG (from-scratch)

Tác vụ thật: bạn muốn audit nhanh một repo backend, kiểm ba mảng độc lập cùng lúc - auth, database, API. Ba mảng này không phụ thuộc nhau, đúng chuẩn để chạy song song.

1. Gõ prompt điều phối. Yêu cầu Claude fan-out rõ ràng, nêu đúng ba nhánh và bảo mỗi subagent chỉ trả về summary:

   Audit repo này song song bằng 3 subagent độc lập:
   1) auth: kiểm luồng đăng nhập, session, lỗ hổng quyền
   2) database: kiểm schema, query N+1, index thiếu
   3) API: kiểm validate input, rate limit, error handling
   Mỗi subagent chỉ trả về summary ngắn (tối đa ~10 gạch đầu dòng),
   KHÔNG dump toàn bộ log. Sau đó tổng hợp thành 1 báo cáo.

2. Xem Claude fan-out. Claude Code sẽ spawn ba subagent chạy song song, mỗi cái đọc code trong context riêng của nó. Bạn sẽ thấy ba luồng làm việc chạy đồng thời trong phiên.
3. Đọc summary hợp nhất. Khi cả ba xong (fan-in), agent chính gộp lại thành một báo cáo. Vì mỗi subagent chỉ trả bullet gọn, context phiên chính vẫn nhẹ.

Output rút gọn của bước tổng hợp trông đại loại như sau (minh hoạ định dạng, không phải số liệu thật của repo bạn):

Báo cáo audit (hợp nhất từ 3 subagent):
[auth] - Session không set flag HttpOnly/Secure
 - Thiếu kiểm tra quyền ở endpoint /admin/*
[database] - Query danh sách order có N+1 (loop findOne)
 - Bảng users thiếu index trên cột email
[API] - 4 endpoint chưa validate body
 - Chưa có rate limit ở route đăng nhập

Vì sao song song hợp ở đây: ba nhánh không cần dữ liệu của nhau, nên chạy đồng thời rút ngắn thời gian và mỗi báo cáo dài được cô lập trong context riêng. Nếu bạn ép làm tuần tự thì chỉ chậm hơn chứ không đúng hơn.

Ví dụ 2 - Pipeline nối tiếp (chain) reviewer → optimizer

Tác vụ thật: bạn nghi một module có vấn đề hiệu năng. Bước 1, một subagent code-reviewer tìm ra các điểm nghẽn. Bước 2, một subagent optimizer dựa trên danh sách đó để sửa. Đây là phụ thuộc rõ ràng - optimizer cần biết reviewer tìm thấy gì - nên phải nối tiếp, không thể song song.

1. Chạy reviewer trước. Prompt điều phối:

   Dùng subagent code-reviewer để tìm các điểm nghẽn hiệu năng
   trong thư mục src/services/ và trả về danh sách có mức độ ưu tiên.

2. Chuyền kết quả sang optimizer. Agent chính lấy danh sách của reviewer làm đầu vào cho bước sau:

   Chuyển danh sách trên cho subagent optimizer:
   sửa theo thứ tự ưu tiên, mỗi thay đổi kèm 1 dòng giải thích lý do,
   KHÔNG đổi hành vi public API.

3. Nhận kết quả cuối. Optimizer làm việc trên đúng những gì reviewer đã chỉ ra. Claude đóng vai trò chuyền context giữa hai mắt xích.

[reviewer] Tìm thấy 3 điểm nghẽn:
 P1 - parseAll() đọc lại file trong vòng lặp
 P2 - gọi API tuần tự, có thể batch
 P3 - JSON.parse lặp trên cùng payload
[optimizer] Đã sửa:
 P1 → cache nội dung file ngoài vòng lặp
 P2 → gộp thành 1 request batch
 P3 → parse 1 lần, tái dùng object

Điểm cốt lõi: pipeline dùng khi bước sau cần đầu ra bước trước. Nếu bạn cố song song hai bước phụ thuộc này, optimizer sẽ sửa mù vì chưa có danh sách của reviewer. Orchestration không tồn tại đơn lẻ - nó là một mảnh trong quy trình brainstorm → plan → cook → ship; thường bạn plan xong rồi mới bung subagent để cook các nhánh.

Nâng cao - Orchestrator agent, nested subagents & giới hạn depth

Thay vì gõ prompt điều phối mỗi lần, bạn có thể khai báo hẳn một orchestrator agent chỉ làm nhiệm vụ điều phối. Tạo file .claude/agents/coordinator.md:

---
name: coordinator
description: Điều phối các subagent worker cho tác vụ lớn nhiều nhánh.
 Chỉ chia việc, spawn worker và tổng hợp summary - KHÔNG tự viết code.
---

Bạn là agent điều phối. Nhiệm vụ:
1. Phân rã yêu cầu thành các nhánh độc lập (nếu có).
2. Nhánh độc lập → giao song song; nhánh phụ thuộc → nối tiếp.
3. Yêu cầu mỗi worker CHỈ trả summary gọn.
4. Tổng hợp thành một kết quả duy nhất cho người dùng.
Không tự thực thi việc chi tiết; luôn ủy thác cho worker.

Frontmatter name và description giúp Claude biết khi nào gọi agent này. Ràng buộc "chỉ điều phối" giữ cho nó không nhảy vào tự làm và phình context.

Nested subagents: một subagent có thể tự spawn subagent con. Rất mạnh nhưng dễ mất kiểm soát, nên Claude Code giới hạn độ sâu. Theo docs Claude Code về sub-agents (đối chiếu 2026-08), độ sâu spawn mặc định là 3 tầng và điều chỉnh được qua biến môi trường CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. Đặt quá cao dễ dẫn tới bùng nổ số agent và cháy token; hầu hết workflow thực tế không cần vượt mặc định.

Với các tác vụ song song bền hoặc vượt một context window, docs cũng đề cập tính năng agent teams - cho phép nhiều agent phối hợp ở quy mô lớn hơn. Đây là surface mới và đổi nhanh, nên trước khi dựa vào nó cho production, hãy kiểm tra lại docs live.

Tối ưu token & chi phí khi orchestrate

Vì multi-agent tốn khoảng 15× token so với một phiên chat thường (theo Anthropic), tối ưu token không phải tuỳ chọn - nó là điều kiện để orchestration đáng đồng tiền. Vài đòn thực dụng:

• Giới hạn số subagent ở mức 3-5 cho mỗi lượt fan-out. Thêm agent hiếm khi tăng chất lượng tương xứng nhưng tăng token tuyến tính.
• Route worker sang model rẻ hơn. Các nhánh đơn giản (đọc file, liệt kê) có thể giao cho model rẻ như Haiku, để dành model mạnh cho bước tổng hợp.
• Bắt subagent chỉ trả summary, không dump toàn bộ log/diff về agent chính. Đây là nguồn lãng phí token lớn nhất mà ai cũng dính.
• Tránh nhiều subagent cùng trả kết quả dài về main - fan-in nhiều output dài sẽ nhồi context chính, phản tác dụng của việc cô lập.

Muốn đào sâu về ngân sách token cho phiên nhiều agent, xem bài tối ưu token khi chạy nhiều agent.

Không muốn tự viết? Bộ orchestrator agent dựng sẵn (AgentKit)

Viết coordinator và một dàn worker tử tế mất thời gian. Nếu bạn muốn có sẵn để dùng ngay, có bộ kit đóng gói phần này. Một dòng phân biệt để khỏi nhầm: AgentKit ở đây là bộ kit cho Claude Code (agentkit.best, CLI ak) - KHÔNG phải OpenAI AgentKit (Agent Builder/ChatKit, ra mắt 06/10/2025).

Engineer Kit của AgentKit đóng gói sẵn 17 engineer agents (trong tổng 45 agents của nền tảng = 17 engineer + 28 marketing) cùng các workflow điều phối - chẳng hạn skill ak-orchestrate - nên bạn khỏi phải tự viết coordinator từ đầu. Giá niêm yết Engineer Kit là $99, trang không nêu phí định kỳ. Nói thẳng: bạn hoàn toàn tự dựng được orchestrator như phần trên đã hướng dẫn; bộ kit chỉ đáng khi bạn muốn tiết kiệm thời gian setup và dùng agent đã được tinh chỉnh. Muốn xem chi tiết những gì có bên trong, đọc review Engineer Kit, hoặc xem thẳng bộ orchestrator agent dựng sẵn của AgentKit.

Lỗi thường gặp khi orchestrate nhiều subagent

• Spawn quá nhiều subagent. Khi tất cả trả kết quả về cùng lúc, context chính cháy. Cách né: giữ 3-5 agent/lượt, bắt trả summary.
• Dùng song song cho việc phụ thuộc nhau. Kết quả sai hoặc đua dữ liệu. Cách né: hỏi "bước sau có cần đầu ra bước trước không?" - có thì dùng pipeline.
• Subagent trả log dài thay vì summary. Đốt token vô ích và nhồi context. Cách né: ghi rõ giới hạn output trong prompt/định nghĩa agent.
• Quên giới hạn depth. Nested subagents tràn tầng, số agent bùng nổ. Cách né: giữ CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH ở mặc định trừ khi có lý do rõ.
• Tốn token không tương xứng. Dùng multi-agent cho thay đổi nhỏ. Cách né: tác vụ nhỏ/nhanh thì chạy một phiên tuyến tính, đừng orchestrate.

Câu hỏi thường gặp (FAQ)

Chạy được bao nhiêu subagent song song?

Thực tế nên giữ 3-5 subagent mỗi lượt fan-out. Không phải giới hạn cứng, nhưng nhiều hơn thường không tăng chất lượng tương xứng mà token tăng nhanh và context tổng hợp dễ quá tải. Chia thành nhiều đợt fan-out nhỏ tốt hơn một đợt khổng lồ.

Song song hay pipeline tốn token hơn?

Song song thường tốn token dồn dập hơn vì nhiều agent chạy đồng thời, mỗi cái có context riêng. Pipeline tiêu token vừa phải hơn tại một thời điểm nhưng cộng dồn qua các bước và chậm hơn. Chọn theo tính chất phụ thuộc của tác vụ, không chỉ theo token.

Subagent có tự spawn subagent con không (nested)?

Có. Một subagent có thể spawn subagent con (nested subagents). Claude Code giới hạn độ sâu - mặc định 3 tầng - và điều chỉnh qua biến CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. Hầu hết workflow không cần vượt mặc định.

Orchestrate có cần agent teams không?

Không bắt buộc. Bạn orchestrate được chỉ bằng prompt điều phối hoặc một orchestrator agent tự khai báo. Agent teams là surface dành cho song song bền/quy mô lớn vượt một context window; kiểm tra docs live vì tính năng này còn mới và đổi nhanh.

Điều phối nhiều agent có đáng với dự án nhỏ không?

Thường là không. Với thay đổi nhỏ hoặc nhanh, chi phí điều phối và token (multi-agent tốn ~15× token theo Anthropic) vượt lợi ích. Chỉ orchestrate khi tác vụ chia được thành các nhánh thực sự độc lập hoặc nhiều mảng.

Có bộ agent điều phối dựng sẵn không?

Có. Engineer Kit của AgentKit (agentkit.best, CLI ak - khác OpenAI AgentKit) đóng gói 17 engineer agents cùng workflow điều phối để khỏi tự viết coordinator. Bạn vẫn hoàn toàn tự dựng được như hướng dẫn ở trên; kit chỉ giúp tiết kiệm thời gian setup.

Kết luận + bước tiếp theo

Đừng bắt đầu bằng một dàn nhạc mười agent. Hãy dựng một pipeline 2 bước (như reviewer → optimizer), đo token nó tiêu, rồi mới mở rộng sang fan-out song song khi tác vụ thực sự chia được thành nhánh độc lập. Nắm vững nền tảng ở hướng dẫn subagents từ cơ bản và đặt orchestration đúng chỗ trong quy trình brainstorm → plan → cook → ship. Nếu không muốn tự viết coordinator, tham khảo review Engineer Kit.