1.3 Subagent Invocation and Context Passing

Những gì cần nắm

Task Statement 1.3 nói về phần cơ khí: coordinator thực sự gọi subagent bằng cách nào và truyền thông tin giữa chúng ra sao. Nếu 1.2 dạy bạn kiến trúc thì 1.3 dạy bạn phần đi dây.

Task tool

Task tool là cách coordinator spawn subagent (exam guide v0.2 dùng tên này). Đây là cơ chế API thật khiến multi-agent orchestration chạy được trong Claude Agent SDK, không phải một quy ước đặt tên có thể lướt qua. Claude Code hiện tại (v2.1.63, tháng 2/2026) đổi tên nó thành Agent; tên Task vẫn dùng được như alias, và Agent SDK phát ra Agent trong các tool-use block. Đi thi thì trả lời “Task tool”, còn đọc code hiện tại thì thấy “Agent”.

Có một yêu cầu cấu hình sống còn: allowedTools của coordinator phải chứa "Task" (hoặc "Agent", tên hiện tại trong Claude Code). Không có nó, coordinator vật lý không spawn nổi subagent. Đây là cổng nhị phân, không phải một ưu tiên mềm. Nếu allowedTools không có Task lẫn Agent, coordinator không còn cách nào gọi subagent.

Mỗi subagent được định nghĩa bằng một AgentDefinition gồm ba phần:

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

Truyền context: chỗ quyết định sống chết

Truyền context là chỗ phần lớn hệ multi-agent gãy. Nguyên tắc từ 1.2 áp nguyên vào đây: context của subagent bị cô lập. Nó chỉ nhận đúng thứ coordinator viết vào prompt của nó. Không gì khác.

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

Quy tắc 1: đưa đầy đủ kết quả của các agent trước. Nếu subagent synthesis cần kết quả web search và output phân tích tài liệu, coordinator phải truyền cả hai — đầy đủ — trong prompt của subagent synthesis. Đừng giả định agent synthesis có thể “tra lại” kết quả trước đó. Nó không tra được.

Quy tắc 2: dùng định dạng dữ liệu có cấu trúc, tách content khỏi metadata. Khi chuyển kết quả nghiên cứu giữa các agent, dữ liệu phải gồm cả content (luận điểm, dữ kiện, phân tích) lẫn metadata (source URL, tên tài liệu, số trang). Nếu bạn truyền content mà không kèm metadata, agent phía sau không thể quy luận điểm về nguồn.

Đây là một dạng đề cụ thể: agent synthesis cho ra báo cáo có luận điểm không dẫn nguồn. Subagent web search và phân tích tài liệu đều chạy đúng. Nguyên nhân gốc là coordinator truyền content mà không kèm structured metadata — agent synthesis đơn giản là không có thông tin nguồn nào để đưa vào.

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

Định dạng structured metadata

Định dạng dữ liệu truyền context giữa các agent nên tách content khỏi metadata cho sạch. Một dạng dùng được trong thực tế:

{
  "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 finding mang theo thông tin nguồn của chính nó dưới dạng metadata. Khi agent synthesis nhận được dữ liệu có cấu trúc như vậy, nó có đủ mọi thứ để viết một báo cáo trích dẫn đàng hoàng.

Spawn song song

Khi coordinator cần gọi nhiều subagent cho các tác vụ độc lập, nó nên phát nhiều Task tool call trong cùng một response thay vì gọi lần lượt qua nhiều lượt khác nhau.

Spawn tuần tự — mỗi lượt coordinator một subagent — chỉ thêm latency mà không đổi lại gì. Nếu agent web search và agent phân tích tài liệu làm việc độc lập thì không có lý do gì bắt con này chờ con kia.

Đề thi kiểm tra ý thức về latency. Khi tình huống có các tác vụ subagent độc lập, đáp án đúng luôn dính tới spawn song song. Để ý các phương án có cụm “in a single response” hay “simultaneously” — đó là tín hiệu của mô hình song song.

fork_session

fork_session tạo ra các nhánh độc lập từ một nền phân tích chung. Sau khi coordinator đã làm xong phần phân tích ban đầu (đọc codebase, hiểu bài toán), nó có thể fork session ra để thử các hướng khác nhau.

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

Cả hai đều là cơ chế điều khiển session của Claude Code. --resume là cờ CLI, với tùy chọn resume tương ứng trong Agent SDK; fork_session là tùy chọn của SDK (forkSession trong TypeScript) và cũng có trên CLI dưới dạng --fork-session, nằm cạnh --resume.

fork_session không giống –resume. Resume tiếp tục một session cụ thể đã đặt tên. Fork tạo một nhánh mới độc lập. Đề thi hỏi đúng sự phân biệt này. Dùng fork khi cần khám phá các hướng phân kỳ từ một điểm xuất phát chung. Dùng resume khi muốn đi tiếp cùng một mạch.

Exam guide v1.0 liệt --resume và fork_session như hai cơ chế điều khiển session, và đề thi khung nó như vậy. Trong Agent SDK (sessions guide, kiểm tra tháng 9/2026), fork là một modifier của resume chứ không phải lựa chọn thay thế. Bạn truyền cả hai: ClaudeAgentOptions(resume=session_id, fork_session=True). resume chỉ ra session xuất phát, còn fork_session nói rằng hãy rẽ nhánh khỏi nó thay vì nối thêm vào nó. Bỏ fork_session đi thì cùng lời gọi đó nối thêm vào session gốc. CLI ghép cặp y hệt: --fork-session chỉ có tác dụng khi đi kèm --resume hoặc --continue. Vậy thứ đề thi hỏi thực chất là nối tiếp so với rẽ nhánh, không phải cờ này so với cờ kia. Khi thi, trả lời theo cách guide khung nó: resume để tiếp tục một session, fork để rẽ nhánh từ nó.

Ví dụ thực tế: mất dẫn nguồn

Một hệ nghiên cứu multi-agent có ba agent: web search, phân tích tài liệu, và synthesis. Agent web search trả về kết quả dẫn nguồn tốt kèm URL và tiêu đề. Agent phân tích tài liệu trả về phân tích chi tiết kèm số trang tham chiếu.

Coordinator chuyển content từ cả hai agent sang agent synthesis nhưng cắt mất metadata — nó gửi luận điểm và đoạn phân tích mà không kèm source URL, tên tài liệu hay số trang. Agent synthesis cho ra một bản tóm tắt xuất sắc nhưng không dẫn nguồn.

Cách sửa không phải là chỉnh prompt của agent synthesis (nó không trích được nguồn mà nó không có). Cách sửa là bắt coordinator truyền structured metadata kèm content, giữ lại source URL, tên tài liệu và số trang cho từng finding.

Bẫy thi

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

Một agent synthesis cho ra báo cáo mà nhiều luận điểm không có dẫn nguồn. Subagent web search trả về đúng kết quả kèm URL, tiêu đề và snippet. Subagent phân tích tài liệu trả về đúng phân tích kèm số trang. Cả hai subagent đã được xác nhận là chạy đúng. Nguyên nhân gốc khả dĩ nhất là gì?

A. System prompt của agent synthesis thiếu chỉ thị tường minh về việc trích nguồn, nên nó tóm tắt phần nghiên cứu mà không mang theo dẫn nguồn nào vào báo cáo
B. Coordinator chuyển content sang agent synthesis mà không kèm structured metadata — source URL, tên tài liệu và số trang không được đưa vào
C. Subagent web search trả kết quả ở định dạng mà agent synthesis không parse được, nên source URL và tiêu đề tài liệu bị rơi trong lúc tổng hợp
D. Nên cấp cho agent synthesis quyền dùng trực tiếp tool web search để nó tự chạy lại truy vấn và tự xác minh nguồn

Đáp án & giải thích

Đúng: B

A — Kể cả có chỉ thị trích nguồn, agent synthesis vẫn không trích được nguồn mà nó chưa từng nhận. Nếu coordinator cắt metadata trước khi chuyển content thì không chỉ thị nào trong prompt cứu lại được thông tin đã mất.
B — Truyền context phải dùng dữ liệu có cấu trúc, tách content khỏi metadata. Không có source URL và tên tài liệu trong dữ liệu chuyển cho agent synthesis thì nó không có thông tin dẫn nguồn nào để đưa vào, bất kể chỉ thị ra sao.
C — Subagent web search đang trả kết quả có cấu trúc tốt. Vấn đề không nằm ở định dạng nguồn — mà ở chỗ coordinator không chuyển metadata xuống agent synthesis.
D — Cấp tool web search cho agent synthesis vi phạm nguyên tắc giới hạn tool theo vai trò và phá vỡ kiến trúc hub-and-spoke. Cách sửa là truyền context cho đúng, không phải phát tool nằm ngoài vai trò của agent.

Nguồn

Claude Agent SDK Overview — Anthropic
Agent SDK: Work with sessions — Anthropic
MCP Specification — Anthropic / MCP
Building with Claude API (Skilljar) — Anthropic

Exam Simulator

Năm câu trắc nghiệm theo format đề thi về Subagent Invocation and Context Passing. Chọn đáp án trước, rồi mở phần giải thích.

Câu 1

Một agent synthesis cho ra báo cáo mà nhiều luận điểm không có dẫn nguồn. Subagent web search trả về đúng kết quả kèm URL, tiêu đề và snippet. Subagent phân tích tài liệu trả về đúng phân tích kèm số trang. Cả hai subagent đã được xác nhận chạy đúng. Nguyên nhân gốc khả dĩ nhất là gì?

A. System prompt của agent synthesis không có chỉ thị trích nguồn
B. Nên cấp cho agent synthesis quyền dùng trực tiếp tool web search để nó tự xác minh nguồn
C. Subagent web search cần trả kết quả ở định dạng khác để agent synthesis parse được
D. Coordinator chuyển tiếp content đã bị lột mất structured metadata về nguồn

Đáp án & giải thích

Đúng: D

D đúng vì truyền context phải dùng dữ liệu có cấu trúc, tách content khỏi metadata. Không có source URL và tên tài liệu trong dữ liệu chuyển cho agent synthesis thì nó không có thông tin dẫn nguồn nào để đưa vào, bất kể chỉ thị ra sao.
A sai vì kể cả có chỉ thị trích nguồn, agent synthesis vẫn không trích được nguồn nó chưa từng nhận. Coordinator đã cắt metadata thì không prompt nào cứu lại được.
B sai vì cấp tool web search cho agent synthesis vi phạm nguyên tắc giới hạn tool theo vai trò và phá vỡ hub-and-spoke. Cách sửa là truyền context cho đúng, không phải phát tool ngoài vai trò.
C sai vì subagent web search đang trả kết quả có cấu trúc tốt. Vấn đề không nằm ở định dạng nguồn mà ở chỗ coordinator không chuyển metadata xuống.

Câu 2

Coordinator cần spawn một subagent web search và một subagent phân tích tài liệu cho hai tác vụ nghiên cứu độc lập. Cách spawn hiệu quả nhất là gì?

A. Gọi subagent web search trước, chờ kết quả, rồi mới gọi subagent phân tích tài liệu
B. Phát nhiều Task tool call trong cùng một response của coordinator để spawn cả hai subagent song song
C. Tạo một message queue dùng chung để hai subagent cùng đọc
D. Gọi cả hai subagent với prompt giống hệt nhau để chúng kiểm chứng chéo kết quả của nhau

Đáp án & giải thích

Đúng: B

B đúng vì phát nhiều Task tool call trong cùng một response của coordinator sẽ spawn các subagent độc lập cùng lúc, giảm latency so với gọi tuần tự qua nhiều lượt.
A sai vì gọi tuần tự thêm latency vô ích khi các tác vụ vốn độc lập. Không con nào cần kết quả của con kia để bắt đầu.
C sai vì message queue dùng chung phá vỡ kiến trúc hub-and-spoke. Mọi giao tiếp phải đi qua coordinator, không qua hạ tầng dùng chung.
D sai vì prompt giống hệt nhau vừa phí tài nguyên vừa không giải quyết vấn đề latency. Mỗi subagent nên nhận prompt riêng, hợp với vai trò và chủ đề con của nó.

Câu 3

Danh sách allowedTools của coordinator chứa [“WebSearch”, “Read”] nhưng KHÔNG có “Task” (hay “Agent”, tên hiện tại). Chuyện gì xảy ra khi coordinator thử spawn subagent?

A. Coordinator vẫn spawn được subagent nhưng với năng lực bị giảm
B. Coordinator tự động chuyển sang gọi thẳng các tool của subagent
C. Coordinator không spawn được subagent nào — Task phải nằm trong allowedTools
D. Coordinator spawn được subagent nhưng subagent kế thừa tool của coordinator thay vì tool của chính nó

Đáp án & giải thích

Đúng: C

C đúng vì Task là cổng cứng để spawn subagent. Không có Task trong allowedTools, coordinator vật lý không gọi nổi subagent nào. Không có phương án dự phòng hay lách nào.
A sai vì thiếu Task thì không subagent nào được spawn — đây không phải chế độ suy giảm, mà là mất hoàn toàn khả năng gọi subagent.
B sai vì không có fallback tự động. Coordinator chỉ dùng được các tool trong allowedTools của nó. Thiếu Task thì nó không còn cơ chế nào để gọi subagent.
D sai vì không có subagent nào được tạo ra. Task là bắt buộc để spawn; chuyện kế thừa tool trở nên vô nghĩa khi bản thân việc spawn đã bất khả.

Câu 4

Một developer dùng fork_session sau khi phân tích codebase để thử hai chiến lược refactor khác nhau. Phát biểu nào mô tả đúng hành vi của các fork?

A. Sau điểm rẽ nhánh, mỗi fork chạy độc lập — thay đổi ở nhánh này không ảnh hưởng nhánh kia
B. Hai fork dùng chung memory và thấy kết quả của nhau theo thời gian thực
C. Fork thứ hai tự động nhận bản tóm tắt mọi thứ fork thứ nhất tìm được sau điểm rẽ nhánh
D. Fork giống hệt session –resume và dùng thay cho nhau được

Đáp án & giải thích

Đúng: A

A đúng vì fork_session tạo các nhánh độc lập từ một nền phân tích chung. Sau điểm fork, mỗi nhánh chạy độc lập. Chúng không thấy kết quả của nhau và thay đổi ở nhánh này không ảnh hưởng nhánh kia.
B sai vì fork bị cô lập rõ ràng. Chúng dùng chung context tới điểm rẽ nhánh nhưng hoàn toàn độc lập sau đó. Không tồn tại memory dùng chung.
C sai vì các fork độc lập. Fork thứ hai không biết gì về hoạt động của fork thứ nhất sau điểm rẽ nhánh.
D sai vì fork_session và –resume phục vụ hai mục đích khác hẳn. Fork tạo nhánh phân kỳ để thử phương án thay thế. Resume đi tiếp cùng một hội thoại.

Câu 5

Khi viết prompt của coordinator cho subagent, cách nào cho kết quả tốt hơn?

A. Đưa chỉ thị quy trình chi tiết từng bước về cách subagent phải hoàn thành tác vụ
B. Đưa toàn bộ lịch sử hội thoại của coordinator vào để subagent có context tối đa
C. Nêu mục tiêu nghiên cứu và tiêu chí chất lượng, để subagent tự điều chỉnh cách làm
D. Giữ prompt tối giản để subagent không bị ngợp thông tin

Đáp án & giải thích

Đúng: C

C đúng vì prompt hướng mục tiêu cho subagent khả năng thích ứng. Nêu rõ cần đạt gì và tiêu chí chất lượng nào giúp subagent điều chỉnh cách làm khi gặp tình huống ngoài dự tính.
A sai vì chỉ thị theo quy trình trói subagent, khiến nó không đổi được cách tiếp cận. Gặp tình huống bất ngờ, quy trình cứng dễ dẫn tới kết quả tệ.
B sai vì context của subagent vốn được thiết kế cô lập. Nhét cả lịch sử hội thoại vào vừa phí vừa có thể làm subagent rối vì thông tin không liên quan. Chỉ truyền đúng context cần cho tác vụ.
D sai vì prompt quá sơ sài có thể thiếu context cần thiết để subagent cho ra kết quả chất lượng. Prompt nên có mục tiêu cụ thể, tiêu chí chất lượng, các finding liên quan từ agent trước, và định dạng output mong đợi.