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 条评论

登录 后参与评论

还没有评论,来抢沙发~