Claude Agent SDK 子代理怎麼寫:AgentDefinition 配置、權限收斂與 Python/TS 示例

在 Python 或 TypeScript 裏用 Claude Agent SDK 編排多角色協作,核心是配置 ClaudeAgentOptions 的 agents 字段與 AgentDefinition。本文講清必開的 Agent 委派權限、工具收斂、模型分級與完整代碼示例。

NNathaniel bigo··原創首發·AI 輔助撰寫
9 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 其他 帳號

結論先說

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

SDK 定義子代理兩種方式對比

圖:本站根據 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)。

用 AgentDefinition 編寫子代理四步

圖:本站根據 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)和權限回調鉤子,防止後台無人值守腳本因某個工具報錯而無限重試。

相關教學

參考資料

  • 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

Nathaniel 的更多內容

  1. 01

    LangGraph 流式輸出(Streaming)詳解:逐字 Token 流、節點進度與自定義事件寫法

    多步智能體如果等全部節點跑完才返回,網頁前端就會白屏乾等十幾秒。本文按 LangGraph 官方文檔講清 updates、messages、custom 與 values 四種 stream_mode 的區別,以及組合訂閱逐字打字機輸出加工具內部實時進度的完整代碼。

    其他 AI 工具0
  2. 02

    LangGraph 持久化與長期記憶怎麼配:Checkpointer、Store 與 PostgreSQL 實戰

    在生產環境跑 LangGraph,單靠 InMemorySaver 一重啟就會丟失全部對話。本文按官方文檔講清線程內短期檢查點(Checkpointer)與跨線程長期記憶(Store)的分工,以及用 langgraph-checkpoint-postgres 對接 PostgreSQL 的完整步驟。

    其他 AI 工具0
  3. 03

    LangGraph 多智能體怎麼寫:Supervisor 主管包與 Subgraph 隔離子圖實戰

    在 LangGraph 裏把單個圖擴展成多智能體協作有兩條官方路線:快速原型用預置包 langgraph-supervisor,大型生產系統用原生子圖(Subgraph)嵌套。本文講清兩種寫法的完整代碼、私有狀態隔離防 Token 膨脹技巧以及檢查點傳播規則。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入審批怎麼寫:interrupt 暫停圖運行與 Command 恢復實戰

    企業之所以選 LangGraph,很大程度看中它能安全掛起等待人工審批(Human-in-the-Loop)。本文按官方最新規範講清 interrupt() 動態暫停、Checkpointer 必備條件、Command(resume=...) 恢復執行,以及防止副作用重複運行的重入規則。

    其他 AI 工具0
  5. 05

    多 Agent 協作平台怎麼選:Dify、釦子(Coze)、n8n 與 LangGraph 多智能體機制對比

    搜「多agent協作平台」時,Dify、釦子、n8n 和 LangGraph 都宣稱支持多智能體,但底層的調度方式完全不同。本文跳過基礎安裝,專門從多 Agent 角色跳轉、子代理工具調用、上下文隔離與私有化部署四個維度幫你一次選準。

    其他 AI 工具0
  6. 06

    企業微信有官方 MCP 和 CLI 嗎:@wecom/cli 安裝初始化、長連接機器人與接入教學

    搜「企業 微信 有 mcp 嗎」不用再東拼西湊民間群機器人腳本了:企業微信官方已推出 @wecom/cli 命令行工具並內置 stdio 模式的 MCP Server。本文按官方開發者文檔講清安裝、智能機器人長連接初始化、業務命令與接入 Claude Code 步驟。

    Claude其他 AI 工具0

同產品的其他教學

  1. 01

    MCP 收費嗎:開源協議免費邊界、第三方 API 帳單與隱形 Token 開銷說明

    搜「mcp 收費 嗎」的人常擔心裝多了插件會被扣費。MCP(模型上下文協議)本身和官方 SDK 採用 MIT 協議完全免費;實際使用中可能產生費用的只有兩處:掛載過多工具佔用的大模型上下文 Token,以及部分外部商業數據源自帶的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 協議最新版本更新了什麼:無狀態架構、OAuth 2.1、結構化輸出與異步 Tasks 詳解

    搜「mcp 重大 更新」「mcp 協議 更新」想補齊規範演進脈絡?本文對照 modelcontextprotocol.io 官方規範更新日誌,梳理從 Streamable HTTP 到無狀態優先架構、OAuth 2.1 資源伺服器、Elicitation 交互補參與異步 Tasks 擴展的核心變化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什麼區別:工具連接協議與智能體通信協議的邊界和配合

    很多人問「有了 MCP 為什麼還要出 A2A,兩者是不是二選一的競爭關係」。兩份官方規範都明確寫明它們是上下互補關係:MCP 負責給單個智能體掛載工具與數據源,A2A 負責讓多個獨立黑盒智能體跨團隊、跨框架互相派單協作。

    Claude其他 AI 工具0
  4. 04

    LangGraph 怎麼使用 MCP:用 langchain-mcp-adapters 接入本地與遠程工具

    想讓自建的 LangGraph 狀態圖直接調用現成的 MCP 伺服器,官方標準方案是安裝 langchain-mcp-adapters 並使用 MultiServerMCPClient。本文講清 stdio 與 streamable_http 兩種配置寫法、異步圖運行及按節點分工具技巧。

    Claude其他 AI 工具0
  5. 05

    LangGraph 入門教學:Python 安裝、核心概念與跑通第一個狀態圖智能體

    面向搜「python 安裝 langgraph」和「langgraph 中文 文檔」的初學者:本文按 LangChain 官方最新 Graph API 規範,講清安裝步驟、State/Node/Edge 四大概念,並從零寫出第一個帶工具調用循環的 StateGraph。

    Claude其他 AI 工具0
  6. 06

    Claude Agent SDK 和 LangChain 怎麼選:定位差異、適用場景與混用方式

    搜「claude agent sdk 和 langchain」的人常把兩者當成非此即彼的同類庫。其實 Claude Agent SDK 是自帶文件讀寫、終端命令與壓縮機制的 Claude Code 原生運行時,而 LangChain(及 LangGraph)是跨模型通用的組件與狀態圖編排框架。

    Claude其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~