@@ -741,12 +741,27 @@ Subagents方式（主管+多员工）：
741741** 使用Subagents的方式** ：
742742
743743``` python
744- # 允许Task工具，Agent会自动创建子代理
744+ from claude_agent_sdk import ClaudeAgentOptions, AgentDefinition
745+
746+ # 当前 SDK 通过 Agent 工具创建子代理
745747options = ClaudeAgentOptions(
746- allowed_tools = [' Task' ' TaskOutput' ' Read' ' Write' ' Edit'
748+ allowed_tools = [' Read' ' Grep' ' Glob' ' Edit' ' Write' ' Agent'
749+ agents = {
750+ ' api-refactorer'
751+ description = ' 负责 API 目录重构，适合处理 src/api 下的模块迁移任务。'
752+ prompt = ' 你是 API 重构专家。只处理分配给你的目录，返回修改摘要和风险点。'
753+ tools = [' Read' ' Grep' ' Glob' ' Edit' ' Write'
754+ model = ' sonnet'
755+ ),
756+ ' model-typist'
757+ description = ' 负责数据模型和 TypeScript 类型补全。'
758+ prompt = ' 你是 TypeScript 类型建模专家。优先保持兼容性，避免无关重构。'
759+ tools = [' Read' ' Grep' ' Glob' ' Edit' ' Write'
760+ ),
761+ },
747762 max_turns = 50 ,
748763 system_prompt = """ 你是一个项目重构专家。
749- 当遇到大型任务时，请使用Task工具创建子代理来并行处理 。
764+ 当遇到大型任务时，优先使用已定义的子代理并行处理 。
750765 每个子代理应该专注于一个独立的模块或目录。"""
751766)
752767
@@ -761,22 +776,23 @@ async for message in query(prompt=prompt, options=options):
761776 # 处理消息...
762777```
763778
764- ### 3.5 Task 工具与子代理编排（CLI 内置）
779+ > ** 版本校准（2026-04） ** ：官方 Agent SDK 文档当前要求在 ` allowed_tools ` / ` allowedTools ` 中包含 ` Agent ` ，因为子代理通过 ** Agent tool ** 调用。旧资料里可能会看到 ` Task ` ，官方文档说明该工具名在 Claude Code v2.1.63 从 ` Task ` 改为 ` Agent ` ；为兼容旧 SDK，观测 ` tool_use ` 事件时可以同时识别 ` Task ` 和 ` Agent ` ，但新教程示例应写 ` Agent ` 。
765780
766- > ** 补充说明 ** ：上面 3.4 节讲的是 SDK 中如何编程创建子代理。这里介绍 Claude Code CLI 中 ** 内置的 Task 工具 ** ——你在交互模式下就能直接使用的多 Agent 编排系统。
781+ ### 3.5 Agent 工具与子代理编排
767782
768- Claude Code CLI 内置了强大的 ** Task 工具 ** ，无需写代码就能让 Claude 自动创建子代理：
783+ 在 SDK 中，推荐用 ` agents ` 参数定义子代理，再把 ` Agent ` 加入主 Agent 的 ` allowed_tools ` 。在 Claude Code CLI 交互模式中，普通用户通常不直接手写底层工具调用，而是通过 ` /agents ` 管理 agent 配置，或在自然语言里明确要求“使用某个 agent”。
769784
770- ** 核心参数 ** ：
785+ ** AgentDefinition 核心字段 ** ：
771786
772787| 参数 | 说明 |
773788| ------| ------|
774- | ` subagent_type ` | 子代理类型（Explore、Bash、code-reviewer 等） |
775- | ` prompt ` | 分配给子代理的任务描述 |
776- | ` isolation ` | 设为 ` "worktree" ` 可在独立工作树中运行 |
777- | ` run_in_background ` | 设为 ` true ` 在后台运行 |
778- | ` resume ` | 传入之前的 agent ID 可恢复中断的子代理 |
779- | ` model ` | 可指定 sonnet/opus/haiku，不指定则继承父级 |
789+ | ` description ` | 告诉 Claude 什么时候应该使用这个子代理 |
790+ | ` prompt ` | 子代理自己的系统提示词 / 行为规范 |
791+ | ` tools ` | 子代理可用工具；省略时继承父级可用工具 |
792+ | ` model ` | 可用 ` sonnet ` / ` opus ` / ` haiku ` / ` inherit ` 或完整模型 ID |
793+ | ` background ` | 是否作为非阻塞后台任务运行 |
794+ | ` maxTurns ` | 子代理最大 agentic turn 数 |
795+ | ` skills ` | 明确注入给该子代理的技能列表 |
780796
781797** 常用子代理类型** ：
782798
@@ -788,9 +804,9 @@ Claude Code CLI 内置了强大的 **Task 工具**，无需写代码就能让 Cl
788804| ` general-purpose ` | 通用多步骤任务 | 全部工具 |
789805| ` Plan ` | 设计实现方案 | 全部（不含写入） |
790806
791- ** 任务依赖（DAG 系统） ** ：
807+ ** 并行编排方式 ** ：
792808
793- Task 工具支持有向无环图（DAG）依赖关系——任务 C 可以等待任务 A 和任务 B 完成后再执行：
809+ 主 Agent 可以一次启动多个适合的子代理。子代理各自拥有独立上下文，只把最终结果返回给父级；如果后续步骤依赖前置结论，把依赖关系写进父级 prompt，让父级在收到结果后再继续分配下一步。
794810
795811```
796812任务A: 构建API ──┐
@@ -804,7 +820,7 @@ Task 工具支持有向无环图（DAG）依赖关系——任务 C 可以等待
804820
8058211 . ** Skills 注入** ：在定义中指定 skills 字段，完整技能内容直接注入子代理
8068222 . ** Memory 持久化** ：子代理可拥有持久记忆目录，跨会话积累知识
807- 3 . ** 工具访问控制** ：通过 ` allowedTools ` / ` disallowedTools ` 精细控制子代理能力
823+ 3 . ** 工具访问控制** ：通过 ` tools ` / ` disallowedTools ` 精细控制子代理能力
808824
809825> 💡 ** 提示** ：子代理不能再创建子代理（只有一层嵌套），最多可同时运行 10 个并行子代理。
810826
@@ -1352,7 +1368,7 @@ review_options = ClaudeAgentOptions(
13521368
13531369# 完全权限Agent - 可以做任何事
13541370full_options = ClaudeAgentOptions(
1355- allowed_tools = [' Read' ' Write' ' Edit' ' Bash' ' Glob' ' Grep' ' Task '
1371+ allowed_tools = [' Read' ' Write' ' Edit' ' Bash' ' Glob' ' Grep' ' Agent '
13561372 permission_mode = ' acceptEdits'
13571373)
13581374```
@@ -1589,13 +1605,13 @@ options = ClaudeAgentOptions(
15891605
15901606### Q4: 子代理和主代理怎么通信？
15911607
1592- ** 答** ：通过Task和TaskOutput工具 ：
1608+ ** 答** ：通过 ` Agent ` 工具调用与最终结果回传 ：
15931609
1594- 1 . 主Agent用Task工具创建子代理 ，指定任务
1610+ 1 . 主 Agent 通过 ` Agent ` 工具创建/调用子代理 ，指定任务
159516112 . 子代理执行任务并返回结果
1596- 3 . 主Agent用TaskOutput工具获取结果
1612+ 3 . 主 Agent 收到子代理最终消息，作为后续汇总或下一步决策的输入
15971613
1598- 子代理完成后，结果会自动返回给主Agent 。
1614+ 子代理运行在独立上下文里，父级不会自动继承它读过的所有文件和中间工具结果；需要保留的信息应让子代理在最终回复里明确写出来 。
15991615
16001616---
16011617
@@ -1650,16 +1666,16 @@ async for message in query(prompt="...", options=options):
16501666
16511667** 答** ：
16521668
1653- 1 . ** 使用后台运行的子代理** ：Task工具支持 ` run_in_background `
1669+ 1 . ** 使用后台运行的子代理** ：在 ` AgentDefinition ` 中设置 ` background=True `
165416702 . ** 设置合理的超时**
165516713 . ** 使用异步并行**
16561672
16571673``` python
16581674prompt = """ 请使用子代理并行处理：
1659- - 子代理1：分析src目录（run_in_background: true）
1660- - 子代理2：分析tests目录（run_in_background: true）
1675+ - 子代理1：分析src目录
1676+ - 子代理2：分析tests目录
16611677
1662- 启动后等待所有子代理完成再汇总 。"""
1678+ 如果这些子代理被配置为 background=True，请持续跟踪它们的最终结果后再汇总 。"""
16631679```
16641680
16651681---
0 commit comments