Coordinator và subagent trong hệ thống multi-agent Claude

Coordinator nắm kế hoạch. Nó chia nhỏ câu hỏi, chọn subagent, giao nhiệm vụ cho từng subagent, gom kết quả và quyết định bước tiếp theo. Các subagent không bao giờ nói chuyện trực tiếp với nhau. Exam guide gọi đây là hub-and-spoke: mọi giao tiếp, xử lý lỗi và định tuyến thông tin đều đi qua coordinator.

flowchart LR
    U[Câu hỏi của user] --> C((Coordinator))
    C -->|task prompt| W[Subagent tìm kiếm web]
    C -->|task prompt| D[Subagent phân tích tài liệu]
    W -->|kết quả có cấu trúc| C
    D -->|kết quả có cấu trúc| C
    C -->|toàn bộ kết quả trong prompt| S[Subagent tổng hợp]
    S -->|bản nháp có trích dẫn| C
    C --> R[Báo cáo cuối]

Mô hình hub cho bạn một chỗ duy nhất để ghi log, xử lý lỗi nhất quán và kiểm soát subagent nào được thấy thông tin gì. Thiết kế cho subagent tìm kiếm gửi thẳng kết quả sang subagent tổng hợp sẽ mất cả ba điều này, và đó là một đáp án sai hay gặp.

Coordinator cũng điều chỉnh mức đầu tư theo truy vấn: guide yêu cầu nó chọn subagent theo độ phức tạp của câu hỏi, thay vì lúc nào cũng chạy toàn bộ pipeline.

Không. Subagent bắt đầu với context trống. Nó không thấy lịch sử hội thoại, các tool result trước đó hay system prompt của coordinator, và không giữ bộ nhớ giữa các lần gọi. Task prompt mà coordinator viết là nội dung duy nhất được truyền vào, nên mọi kết quả, đường dẫn file và quyết định mà subagent cần đều phải nằm trong prompt đó.

Vì vậy câu "Dựa trên kết quả tìm kiếm ở trên, hãy viết bản tóm tắt" sẽ hỏng: subagent tổng hợp chưa từng thấy gì "ở trên". Dán nguyên transcript của coordinator là lỗi theo chiều ngược lại, vì nhiệm vụ chính bị chìm giữa các đoạn lên kế hoạch. Chỉ truyền những kết quả subagent cần, dưới dạng bản ghi có cấu trúc.

Cấu hình coordinator tối giản với Python Agent SDK:

from claude_agent_sdk import ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    system_prompt=(
        "Goal: a cited report that answers the user's question. "
        "Quality bar: every claim has a source; report conflicts and gaps. "
        "Launch independent research subagents in the same response."
    ),
    allowed_tools=["Agent"],  # exam guide gọi tool này là "Task"
    agents={
        "web-search": AgentDefinition(
            description="Researches ONE assigned subtopic on the web.",
            prompt="Return findings as JSON records with claim, source_url, excerpt, published_date.",
            tools=["WebSearch", "WebFetch"],
        ),
        "synthesis": AgentDefinition(
            description="Writes the report from findings supplied in its prompt.",
            prompt="Use only the records you are given. Keep every source_url.",
            tools=[],
        ),
    },
)

Nếu tool tạo subagent không có trong danh sách tool được phép, coordinator không giao việc được và sẽ tự làm hết phần research. Để ý rằng prompt của coordinator nêu mục tiêu và tiêu chí chất lượng chứ không liệt kê từng bước, đúng cách guide khuyến nghị.

⚠ Exam guide gọi tool tạo subagent là Task và yêu cầu allowedTools phải có "Task". Tài liệu Agent SDK hiện tại đặt tên là Agent, và các bản mới cho phép subagent tự tạo subagent con. Khi thi, cứ theo guide.

Chia câu hỏi thành các phần riêng biệt mà gộp lại phủ hết câu hỏi. Guide nêu rõ rủi ro của việc chia quá hẹp: nếu "chính sách tái chế nhựa ở Đông Nam Á" bị chia thành ba việc về Việt Nam, Thái Lan và luật bao bì của Việt Nam, thì subagent nào cũng làm tốt mà báo cáo vẫn thiếu gần hết khu vực.

Chia theo chủ đề con hoặc theo loại nguồn để các subagent không tìm trùng nhau. Sau đó chạy vòng lặp tinh chỉnh: coordinator kiểm tra bản tổng hợp xem còn thiếu gì, giao lại các truy vấn có mục tiêu, rồi gọi bước tổng hợp lần nữa cho đến khi đủ độ bao phủ.

Việc độc lập thì chạy song song: cách guide mô tả là phát nhiều lệnh gọi Task trong cùng một response của coordinator, không phải mỗi lượt một lệnh. Bốn lượt tìm kiếm theo bốn nước khi đó chỉ mất khoảng bằng lượt chậm nhất. Chỉ chạy tuần tự khi bước sau cần output của bước trước, như bước tổng hợp cần kết quả research.

Bằng error context có cấu trúc: loại lỗi, đã thử những gì, kết quả từng phần và các hướng thay thế. Trạng thái chung chung kiểu "search unavailable" giấu mất thứ coordinator cần để quyết định. Trả về danh sách rỗng kèm trạng thái thành công còn tệ hơn, vì coordinator sẽ biến một lần tra cứu thất bại thành khẳng định chắc chắn rằng "không có".

Guide tách lỗi truy cập (timeout, cần quyết định có retry hay không) khỏi kết quả rỗng hợp lệ (truy vấn chạy xong và không khớp gì). Hãy cho chúng hai trạng thái khác nhau:

{
  "status": "partial",
  "query": "Indonesia plastic recycling target 2025 site:go.id",
  "findings": [{"claim": "...", "source_url": "...", "published_date": "2024-06-12"}],
  "failure": {"type": "timeout", "attempts": 3, "detail": "Government portal did not respond"},
  "alternatives": ["UNEP country profile", "national news archive"]
}

Subagent nên tự retry lỗi tạm thời ngay tại chỗ với số lần cố định và nhỏ, rồi báo lên. Subagent retry mãi thì không bao giờ trả kết quả, và coordinator không thể chuyển hướng. Dừng cả workflow chỉ vì một lỗi cũng là anti-pattern, vì nó vứt bỏ mọi kết quả đã thành công. Báo cáo cuối nên ghi chú độ bao phủ: kết luận nào có nguồn vững, mảng nào còn thiếu vì nguồn không truy cập được.

Biến provenance (nguồn gốc thông tin) thành một phần của dữ liệu. Mỗi kết quả đi kèm bản ghi gồm nhận định, URL hoặc tên tài liệu, đoạn trích làm bằng chứng và ngày tháng, và subagent tổng hợp phải giữ lại rồi gộp các liên kết này. Mỗi bước tóm tắt bằng văn bản tự do là một chỗ trích dẫn có thể rơi mất.

Khi hai nguồn đáng tin mâu thuẫn, hãy báo cả hai giá trị kèm nguồn thay vì chọn một. Ngày tháng giúp tránh mâu thuẫn giả: 31% năm 2022 và 45% năm 2025 là một xu hướng. Guide cũng yêu cầu tách riêng phần kết luận đã vững và phần còn tranh cãi.

Subagent phân tích tài liệu tìm được hai báo cáo đáng tin cho cùng một năm: một báo cáo nói 38% doanh nghiệp nhỏ dùng hóa đơn điện tử, báo cáo kia nói 44%, do dùng mẫu khảo sát khác nhau. Subagent nên làm gì?

A) Trả về con số của báo cáo mới hơn. B) Trả về giá trị trung bình 41% và trích cả hai báo cáo. C) Trả về cả hai giá trị, mỗi giá trị kèm nguồn, ngày và phương pháp, đánh dấu là mâu thuẫn để coordinator xử lý. D) Dừng lại và báo lỗi cho coordinator vì dữ liệu không đáng tin.

Đáp án: C. Guide yêu cầu hoàn thành phân tích với các giá trị mâu thuẫn được ghi chú kèm nguồn, và để coordinator quyết định cách hòa giải trước bước tổng hợp.

• A chọn bừa một giá trị; cả hai cùng nói về một năm.
• B bịa ra một con số mà không nguồn nào đưa ra, và che mất sự bất đồng.
• D coi một kết quả research bình thường là lỗi và vứt bỏ phần việc đã xong.

• Coordinator nắm việc chia nhỏ, định tuyến, xử lý lỗi và tổng hợp; subagent không nhắn tin trực tiếp cho nhau.
• Subagent bắt đầu với context trống. Đưa kết quả nó cần vào task prompt, phần còn lại của transcript thì để ngoài.
• Chia phạm vi phủ hết câu hỏi, spawn các subagent độc lập trong cùng một response, và lặp lại khi còn chỗ thiếu.
• Báo lỗi kèm loại lỗi, truy vấn đã chạy, kết quả từng phần và hướng thay thế. Tách bạch "thất bại" với "không có kết quả".
• Giữ claim, nguồn, đoạn trích và ngày qua mọi bước, và báo cáo mâu thuẫn thay vì âm thầm chọn một bên.