結論先說
- SDK 支持兩種定義子代理的方式:在代碼裏用
AgentDefinition內聯聲明(最推薦,方便動態傳參與版本管理),或者開啟項目配置加載直接複用倉庫.claude/agents/下的 Markdown 文件。 - 新手最常踩的坑:必須在頂層
allowed_tools(TS 為allowedTools)裏顯式加上"Agent",否則主代理沒有權限自動拉起子代理。 - 主代理靠
description字段決定什麼時候派活——描述越具體(寫清適用場景和輸入輸出),路由越準。 - 務必在
AgentDefinition裏單獨限制tools和model:不填tools預設繼承全部權限,不填model預設繼承主模型,拆好白名單與輕量模型才能既安全又省 API 帳單。 - 子代理不支持無限套娃:不要往子代理自己的
tools列表裏再塞"Agent",所有委派統一由頂層主代理單層調度。

圖:本站根據 Claude Agent SDK 官方 Subagents 文檔 整理的示意圖
本文根據 Claude Code 官方文檔《Subagents in the SDK》《Agent SDK overview》整理,核對日期 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Anthropic 官方網站。
適用於誰
- 搜「claude agent sdk 子代理怎麼寫」「AgentDefinition python 示例」的人;
- 已經跑通了單個 SDK 智能體(入門步驟見 /guides/claude-agent-sdk-quickstart),想在自動化腳本里拆出「只讀代碼審查員」「測試執行員」等專職角色的開發者;
- 寫了
agents配置但運行後發現主代理根本不調用子代理,正在排查權限配置坑的人。
如果你是想在交互式終端命令行裏配 .claude/agents/*.md,直接看 /guides/claude-code-subagents;如果你還在猶豫選這個 SDK 還是選通用編排框架,見 /guides/claude-agent-sdk-vs-langchain-how-to-choose。
一、AgentDefinition 核心字段一覽
無論用 Python 還是 TypeScript,每個子代理定義都圍繞四個核心屬性展開:
description(必填):寫給主代理看的調度說明,告訴主代理遇到哪類子問題時應該調用這個角色;prompt(必填):寫給該子代理自己看的系統提示詞,規定它的工作步驟、約束紅線和返回摘要格式;tools(強烈建議填寫):該子代理允許使用的工具名稱數組(如["Read", "Grep", "Glob"])。省略時會繼承父級開放的工具;model(可選):指定"haiku"、"sonnet"、"opus"或"inherit",用於做主強從輕的成本分級(降本邏輯見 /guides/multi-agent-token-cost-why-high-how-to-control)。

圖:本站根據 Claude Agent SDK 官方文檔 整理的示意圖
二、Python 完整示例:主代理統籌「輕量檢索員 + 只讀審查員」
先確保虛擬環境已安裝 claude-agent-sdk 並配置好 ANTHROPIC_API_KEY。下面的示例定義了兩個職責和模型檔位完全隔離的子代理:
python
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
async def main():
options = ClaudeAgentOptions(
model="opus",
# 關鍵:必須包含 "Agent" 工具,主代理才能自動委派子代理
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
"repo-locator": AgentDefinition(
description="快速檢索目錄結構與函數引用位置,需要大範圍搜文件時優先調用",
prompt="你只負責用 Glob 和 Grep 定位相關文件與行號,返回不超過 200 字的路徑清單,不要全文粘貼源碼。",
tools=["Glob", "Grep", "Read"],
model="haiku",
),
"security-auditor": AgentDefinition(
description="對鑑權、輸入校驗與敏感配置改動做獨立只讀安全審查",
prompt="你是隻讀安全審查員。檢查目標代碼的越權、注入與密鑰泄露風險,按嚴重度列出 文件路徑:行號 與修復建議。",
tools=["Read", "Grep", "Glob"],
model="sonnet",
),
},
)
async for message in query(
prompt="先定位認證中間件相關文件,再審查其中的權限校驗漏洞並給出彙總報告。",
options=options,
):
if hasattr(message, "result") and message.result:
print(message.result)
asyncio.run(main())
這段配置跑起來後,頂層 opus 主代理不會自己去翻幾十個無關目錄污染主上下文,而是先調 haiku 驅動的 repo-locator 拿到精確路徑,再調 sonnet 驅動的 security-auditor 在乾淨上下文裏深審,最後由主代理彙總輸出。
三、TypeScript 寫法對照
在 Node.js(18+)環境下,直接通過 @anthropic-ai/claude-agent-sdk 的 options.agents 傳入同名結構即可(注意頂層工具字段名為駝峰 allowedTools):
typescript
import { query } from "@anthropic-ai/claude-agent-sdk";
async function runReview() {
for await (const msg of query({
prompt: "運行測試套件分析失敗用例,並對關聯模組做只讀代碼審查",
options: {
allowedTools: ["Read", "Grep", "Glob", "Agent"],
agents: {
"test-runner": {
description: "執行單元測試命令並提煉報錯堆棧摘要",
prompt: "運行項目測試命令,只彙總失敗用例名、報錯行號與直接原因。",
tools: ["Bash", "Read", "Grep"],
model: "haiku"
},
"code-reviewer": {
description: "對業務代碼做只讀邏輯與邊界缺陷審查",
prompt: "嚴禁修改源碼,只輸出會導致故障的邏輯問題清單。",
tools: ["Read", "Grep", "Glob"],
model: "sonnet"
}
}
}
})) {
if ("result" in msg && msg.result) {
console.log(msg.result);
}
}
}
runReview();
四、怎麼直接複用倉庫現成的 .claude/agents/ 文件
如果團隊平時已經用終端版 Claude Code 在倉庫 .claude/agents/ 目錄裏沉澱好了成熟的 Markdown 子代理文件,不想在 Python 代碼裏重複抄一遍提示詞,可以在 ClaudeAgentOptions 裏配置 setting_sources=["project"](TS 為 settingSources: ["project"])加載項目級配置,同時依然保持在 allowed_tools 中放行 "Agent"。如果代碼內聯 agents 字典與磁盤文件重名,代碼內聯定義的優先級更高。
本地編寫和調試 SDK 腳本前,很多開發者也會先在交互式 Claude Code 終端裏用個人訂閱打磨好子代理提示詞再搬進代碼;關於終端側官方訂閱與 API 計費的區分說明,可參考 /chongzhi/claude-code。
常見問題
Q:為什麼我配好了 agents,運行後主代理還是自己把活幹完了、根本沒調子代理?
按順序排查三點:第一,核對 allowed_tools 裏有沒有漏寫 "Agent";第二,任務如果太簡單(比如只讀一個已知文件),主模型會判斷直接讀比派子代理更划算;第三,在主 prompt 裏可以直接點名(如「使用 security-auditor 子代理檢查…」)強制觸發驗證。
Q:能用程序同時並發跑三個不同的子代理嗎?
在同一個主會話裏,如果主模型判斷多個子任務互不依賴,可以在同一輪響應裏並發發出多個 Agent 工具調用,SDK 底層會並行執行這些隔離上下文並把各自摘要一起交回主代理。
Q:怎麼限制某個子代理單次跑太多輪導致超時?
除了在子代理系統提示詞裏明確要求「最多執行三次搜尋即彙總返回」之外,還可以在外層 ClaudeAgentOptions 設定總輪數上限(max_turns)和權限回調鉤子,防止後台無人值守腳本因某個工具報錯而無限重試。
相關教學
- /guides/claude-agent-sdk-quickstart:Claude Agent SDK 安裝、認證與快速上手
- /guides/claude-code-subagents:終端版 Claude Code 子代理配置詳解
- /guides/claude-agent-sdk-vs-langchain-how-to-choose:Claude Agent SDK 與 LangChain 選型對比
- /guides/multi-agent-token-cost-why-high-how-to-control:多 Agent 系統 Token 成本控制指南
參考資料
- Claude Code 官方文檔:Subagents in the SDK — https://code.claude.com/docs/en/agent-sdk/subagents
- Claude Code 官方文檔:Agent SDK overview — https://code.claude.com/docs/en/agent-sdk/overview
0 條評論
還沒有評論,來搶沙發~