Gọi subagent và truyền context cho đủ

Bài 1.2 nói về cách chia việc giữa agent điều phối và các subagent. Bài này đi vào phần cụ thể hơn: trong Claude Agent SDK, agent điều phối gọi subagent bằng cách nào, khai báo subagent ra sao, và phải đưa gì vào prompt để subagent làm đúng việc?

Điều quan trọng nhất cần nhớ: subagent bắt đầu với một ngữ cảnh gần như trống. Nó chỉ biết những gì bạn viết vào prompt giao việc.

Ví dụ xuyên suốt: rà soát hợp đồng thuê văn phòng

Một công ty luật nhỏ dựng hệ thống rà soát hợp đồng gồm agent điều phối và ba subagent:

• contract-reader: đọc hợp đồng, trích các điều khoản quan trọng.
• law-researcher: tra văn bản pháp luật liên quan.
• memo-writer: viết bản ghi nhớ gửi khách, dựa trên kết quả của hai subagent trên.

Khách gửi một hợp đồng thuê văn phòng 40 trang và hỏi: "Điều khoản phạt khi chấm dứt sớm có hợp lệ không?"

Task tool và allowedTools

Trong Agent SDK, agent điều phối gọi subagent bằng một tool có sẵn. Đề thi và các câu luyện thi gọi tool này là Task. Các bản Agent SDK mới đã đổi tên nó thành Agent, và tài liệu SDK ghi rằng trong log, tên tool có thể hiện là Agent hoặc Task tuỳ phiên bản. Hai tên là một thứ. Bài này dùng chữ Task cho khớp với đề.

Mỗi lần gọi Task là một lần giao việc: agent điều phối chọn subagent nào, và viết prompt cho nó.

Vì Task cũng là một tool, agent điều phối chỉ gọi được khi nó nằm trong danh sách tool được phép, tức allowedTools. Quên khai báo thì agent điều phối không giao việc được cho ai. Dấu hiệu dễ nhận: agent điều phối viết "mình sẽ nhờ subagent tìm kiếm" nhưng không có subagent nào chạy, vì nó biết có subagent mà không có tool để gọi.

Khi viết code với SDK bản mới, bạn khai báo tên Agent như trong tài liệu:

for await (const message of query({
  prompt: "Rà soát điều khoản phạt chấm dứt sớm trong hợp đồng đính kèm",
  options: {
    allowedTools: ["Read", "Grep", "Agent"], // đề thi gọi tool này là Task
    agents: {
      "contract-reader": {
        description: "Đọc hợp đồng và trích nguyên văn các điều khoản về phạt, chấm dứt, gia hạn",
        prompt: "Bạn là trợ lý pháp lý. Chỉ trích dẫn nguyên văn, ghi rõ số điều và số trang.",
        tools: ["Read", "Grep"],
      },
      // law-researcher, memo-writer khai báo tương tự
    },
  },
})) { /* ... */ }

Khai báo subagent bằng AgentDefinition

Mỗi subagent trong agents là một AgentDefinition. Ba trường đề thi hay hỏi:

Ngoài ra còn trường model để chọn model riêng cho subagent.

Giới hạn tool là cách giữ an toàn. contract-reader chỉ cần đọc file, nên chỉ cho Read và Grep. Nó không thể vô tình sửa hay xoá file hợp đồng.

Subagent chỉ biết những gì bạn viết vào prompt

Theo tài liệu Agent SDK, subagent bắt đầu với ngữ cảnh mới: không có cuộc hội thoại của agent điều phối, không có kết quả tool mà agent điều phối đã nhận. Thứ đi từ agent điều phối sang subagent là đoạn prompt trong lần gọi Task. Hai lần gọi cùng một subagent cũng không nhớ gì của nhau.

Vì vậy, khi gọi memo-writer, agent điều phối phải đưa toàn bộ kết quả của hai subagent trước vào prompt. Viết "hãy viết bản ghi nhớ dựa trên kết quả ở trên" là sai: với memo-writer, không có gì "ở trên" cả.

Giữ nguồn gốc khi chuyển dữ liệu

Bản ghi nhớ gửi khách phải ghi rõ "theo Điều 12, trang 18 của hợp đồng" hay "theo Bộ luật Dân sự, phần đơn phương chấm dứt hợp đồng". Nếu contract-reader trả về một đoạn văn trơn, thông tin số điều, số trang sẽ dễ rơi mất khi đi qua thêm một agent nữa.

Cách làm là chuyển dữ liệu theo cấu trúc, tách riêng nội dung và thông tin nguồn (tiếng Anh: tách content khỏi metadata):

[
  {
    "content": "Bên thuê chấm dứt trước hạn phải bồi thường 6 tháng tiền thuê.",
    "source": { "document": "hop-dong-thue.pdf", "clause": "Điều 12", "page": 18 }
  }
]

Khi nội dung và nguồn nằm ở hai trường riêng, memo-writer luôn biết câu nào lấy từ đâu, và ít có khả năng trộn nguồn của câu này sang câu khác.

Gọi nhiều subagent cùng lúc

contract-reader và law-researcher không cần chờ nhau. Muốn chúng chạy song song, agent điều phối phải gọi Task hai lần trong cùng một phản hồi, chứ không gọi một cái, chờ xong, sang lượt sau mới gọi cái thứ hai.

Chỉ memo-writer mới phải chờ, vì nó cần kết quả của cả hai.

Prompt giao việc: nói mục tiêu, đừng liệt kê từng bước

Khi viết prompt cho agent điều phối (và prompt agent điều phối viết cho subagent), hãy nói rõ mục tiêu và tiêu chí thế nào là đạt, thay vì liệt kê từng bước phải làm.

Kiểu thứ hai để subagent tự xoay xở khi hợp đồng viết khác dự kiến, ví dụ điều khoản phạt được gọi là "bồi thường" hay nằm trong phụ lục. Bài viết của Anthropic về hệ thống nghiên cứu nhiều agent cũng nói mỗi subagent cần một mục tiêu, định dạng kết quả, hướng dẫn về tool và nguồn nên dùng, và ranh giới công việc rõ ràng.

Cuối cùng, đề thi còn nhắc tới việc fork một phiên làm việc: tách một phiên đang có thành hai nhánh độc lập để thử hai hướng khác nhau từ cùng một kết quả phân tích ban đầu. Phần này nằm ở bài 1.7.