结论先说
- 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 条评论
还没有评论,来抢沙发~