Gọi Subagent và Truyền Ngữ Cảnh

Những điều bạn cần biết

Task Statement 1.3 nói về cơ chế thực tế mà một coordinator dùng để gọi các subagent và truyền thông tin giữa chúng. Nếu 1.2 dạy bạn về kiến trúc, thì 1.3 dạy bạn về hệ thống dây nối (wiring).

Agent Tool

Agent tool (được đổi tên từ Task tool trong Claude Agent SDK v2.1.63) là cơ chế để sinh ra các subagent từ một coordinator. Đây không phải là một gợi ý hay một quy ước — đó là cơ chế API cụ thể giúp điều phối đa agent hoạt động trong Claude Agent SDK. Tên cũ "Task" vẫn hoạt động như một bí danh (alias) tương thích ngược, vì vậy mã nguồn hiện có không bị hỏng.

Có một yêu cầu cấu hình then chốt: allowedTools của coordinator phải bao gồm "Agent" (hoặc "Task" để tương thích ngược). Nếu không có điều này, coordinator sẽ hoàn toàn không thể sinh ra subagent. Đây là một cổng nhị phân, không phải một sở thích mềm dẻo. Nếu cả Agent lẫn Task đều không có trong allowedTools, coordinator không có cách nào để gọi subagent, chấm hết.

Mỗi subagent được định nghĩa bởi một AgentDefinition chỉ rõ ba điều:

1. Description — subagent làm gì (được coordinator dùng để quyết định khi nào gọi nó).
2. System prompt — các chỉ thị mà subagent tuân theo.
3. Tool restrictions — những tool nào subagent có thể truy cập (giới hạn theo vai trò của nó).

Truyền Ngữ Cảnh: Chi Tiết Quyết Định Thành Bại

Truyền ngữ cảnh là nơi mà hầu hết các hệ thống đa agent thất bại trong thực tế. Nguyên tắc từ 1.2 áp dụng trực tiếp ở đây: các subagent có ngữ cảnh cô lập. Chúng chỉ nhận những gì coordinator đưa vào một cách rõ ràng trong prompt của chúng.

Có ba quy tắc để truyền ngữ cảnh hiệu quả:

Quy tắc 1: Bao gồm đầy đủ các phát hiện từ các agent trước đó. Nếu subagent tổng hợp cần kết quả tìm kiếm web và đầu ra phân tích tài liệu, coordinator phải truyền cả hai — một cách đầy đủ — trong prompt của subagent tổng hợp. Đừng giả định rằng agent tổng hợp có thể "tra cứu" các kết quả trước đó. Nó không thể.

Quy tắc 2: Sử dụng các định dạng dữ liệu có cấu trúc tách biệt nội dung khỏi metadata. Khi truyền các phát hiện nghiên cứu giữa các agent, dữ liệu phải bao gồm cả nội dung (tuyên bố, sự việc, phân tích) và metadata (URL nguồn, tên tài liệu, số trang). Nếu bạn truyền nội dung mà không có metadata, agent hạ nguồn không thể quy kết các tuyên bố cho nguồn của chúng.

Đây là một mẫu kỳ thi cụ thể: một agent tổng hợp tạo ra một báo cáo với các tuyên bố không có nguồn. Các subagent tìm kiếm web và phân tích tài liệu đang hoạt động chính xác. Nguyên nhân gốc rễ là coordinator đã truyền nội dung mà không có metadata có cấu trúc — agent tổng hợp thực sự không có thông tin nguồn nào để đưa vào.

Quy tắc 3: Thiết kế prompt của coordinator chỉ rõ mục tiêu, không phải quy trình. Prompt của coordinator nên nói cho các subagent biết cần đạt được điều gì và tiêu chí chất lượng nào cần đáp ứng, chứ không phải hướng dẫn từng bước về cách thực hiện. Prompt hướng theo mục tiêu cho phép khả năng thích ứng của subagent. Các chỉ thị theo quy trình giới hạn subagent và ngăn chúng điều chỉnh cách tiếp cận khi gặp phải tình huống bất ngờ.

Định Dạng Metadata Có Cấu Trúc

Định dạng dữ liệu có cấu trúc để truyền ngữ cảnh giữa các agent nên tách biệt nội dung khỏi metadata một cách rõ ràng. Một định dạng thực tế trông như thế này:

jsonCopy

{
  "findings": [
    {
      "claim": "Solar panel efficiency has increased 25% in the last decade",
      "source_url": "https://example.com/solar-report",
      "document_name": "Annual Solar Industry Report 2024",
      "page_number": 14,
      "confidence": "high",
      "retrieved_by": "web_search_agent"
    }
  ]
}

Mỗi phát hiện mang theo sự quy kết nguồn của nó dưới dạng metadata. Khi agent tổng hợp nhận được dữ liệu có cấu trúc này, nó có mọi thứ cần thiết để tạo ra một báo cáo được trích dẫn đúng cách.

Sinh Song Song

Khi một coordinator cần gọi nhiều subagent cho các nhiệm vụ độc lập, nó nên phát ra nhiều lệnh gọi Agent tool trong một phản hồi duy nhất thay vì gọi chúng lần lượt qua các lượt riêng biệt.

Sinh tuần tự (một subagent cho mỗi lượt của coordinator) tạo ra độ trễ không cần thiết. Nếu agent tìm kiếm web và agent phân tích tài liệu có thể hoạt động độc lập, không có lý do gì để chờ một cái hoàn thành trước khi bắt đầu cái kia.

Kỳ thi kiểm tra nhận thức về độ trễ. Khi được trình bày với các nhiệm vụ subagent độc lập, đáp án đúng liên quan đến việc sinh song song. Hãy tìm các lựa chọn đáp án đề cập đến "trong một phản hồi duy nhất" hoặc "đồng thời" — đây là những tín hiệu cho mẫu song song.

fork_session

fork_session tạo ra các nhánh độc lập từ một baseline phân tích dùng chung. Sau khi coordinator đã hoàn thành một phân tích ban đầu (đọc một codebase, hiểu một vấn đề), nó có thể fork phiên làm việc để khám phá các cách tiếp cận phân kỳ.

Ví dụ: sau khi phân tích một codebase, coordinator fork để so sánh hai chiến lược kiểm thử. Mỗi fork hoạt động độc lập sau điểm phân nhánh — chúng không thấy kết quả của nhau, và thay đổi ở một fork không ảnh hưởng đến fork kia.

fork_session không giống với --resume. Resume tiếp tục một phiên làm việc cụ thể đã được đặt tên. Fork tạo ra một nhánh độc lập mới. Kỳ thi kiểm tra sự phân biệt này. Hãy dùng fork khi bạn cần khám phá phân kỳ từ một điểm khởi đầu dùng chung. Hãy dùng resume khi bạn muốn tiếp tục cùng một hướng điều tra.

Ví Dụ Thực Tế: Lỗi Quy Kết

Một hệ thống nghiên cứu đa agent có ba agent: tìm kiếm web, phân tích tài liệu, và tổng hợp. Agent tìm kiếm web trả về kết quả có nguồn rõ ràng với URL và tiêu đề. Agent phân tích tài liệu trả về phân tích chi tiết với tham chiếu số trang.

Coordinator truyền nội dung từ cả hai agent đến agent tổng hợp nhưng loại bỏ metadata — nó gửi các tuyên bố và văn bản phân tích mà không có URL nguồn, tên tài liệu, hay số trang. Agent tổng hợp tạo ra một bản tóm tắt xuất sắc nhưng không có quy kết nguồn.

Cách khắc phục không phải là chỉnh sửa prompt của agent tổng hợp (nó không thể trích dẫn các nguồn mà nó không có). Cách khắc phục là yêu cầu coordinator truyền metadata có cấu trúc cùng với nội dung, bảo toàn URL nguồn, tên tài liệu, và số trang cho mỗi phát hiện.

Bẫy thi

Tình huống luyện tập

Không tìm thấy câu hỏi luyện tập "q-1-3-001".

Bài tập thực hành

Nguồn tham khảo

• Claude Agent SDK Overview — Anthropic
• MCP Specification — Anthropic / MCP
• Building with Claude API (Skilljar) — Anthropic