Claude Code SDK #7：子 Agent 编排全解——上下文隔离 × 工具沙盒 × 并行加速，让主 Agent 不再被子任务撑爆

为什么需要子 Agent？

1. 上下文隔离：子 Agent 的中间步骤不会累积进主 Agent 的 context
2. 工具权限沙盒：每个子 Agent 只有它需要的工具，doc-reviewer 永远不会意外调用 Bash 删东西
3. 并行加速：多个子 Agent 可以同时跑，三件事不用排队

三种创建方式，推荐哪种？

AgentDefinition 参数全解

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async for message in query(
    prompt="Review the authentication module for security issues",
    options=ClaudeAgentOptions(
        # 主 Agent 的 allowed_tools 里必须包含 "Agent"
        # 否则子 Agent 调用会被阻拦或弹出权限提示
        allowed_tools=["Read", "Grep", "Glob", "Agent"],
        agents={
            "code-reviewer": AgentDefinition(
                description="专职代码审查。用于安全性、可维护性和编码规范检查。",
                prompt="""你是代码审查专家，专注于安全漏洞、性能问题和最佳实践。
审查时：
- 识别安全漏洞
- 检查性能问题
- 验证编码规范
- 给出具体改进建议""",
                tools=["Read", "Grep", "Glob"],  # 只读，无法修改文件
                model="sonnet",                   # 可以给子 Agent 指定不同模型
            ),
        },
    ),
):
    if hasattr(message, "result"):
        print(message.result)

重要：description 是主 Agent 判断「该不该调用这个子 Agent」的唯一依据。写得越具体，触发准确率越高。含糊的 description 会导致主 Agent 不知道什么情况下该把任务交出去。

子 Agent 继承了什么，没继承什么？

• 它自己的 prompt（system prompt）
• Agent 工具调用时传入的 prompt 字符串
• 项目的 CLAUDE.md（如果 settingSources 包含 project）
• 工具定义（来自父 Agent，或 tools 里指定的子集）

• 父 Agent 的对话历史
• 父 Agent 的工具调用结果
• 父 Agent 的 system prompt
• skills 里没有显式列出的 skill 内容

三个实用场景代码示例

场景一：并行代码审查

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="同时对这个代码库做风格检查、安全扫描和测试覆盖率分析",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob", "Bash", "Agent"],
            agents={
                "style-checker": AgentDefinition(
                    description="代码风格和可维护性检查。检查命名、注释、代码组织。",
                    prompt="你是代码风格专家。检查命名规范、注释质量和代码可读性。",
                    tools=["Read", "Grep", "Glob"],
                ),
                "security-scanner": AgentDefinition(
                    description="安全漏洞扫描。检查 SQL 注入、XSS、认证缺陷等问题。",
                    prompt="你是安全专家。重点识别 OWASP Top 10 漏洞和常见安全缺陷。",
                    tools=["Read", "Grep", "Glob"],
                ),
                "test-runner": AgentDefinition(
                    description="运行测试套件并分析覆盖率。",
                    prompt="你是测试专家。运行测试、分析失败原因、报告覆盖率。",
                    tools=["Bash", "Read", "Grep"],
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

场景二：动态生成 Agent 定义

from claude_agent_sdk import AgentDefinition

def create_security_agent(level: str) -> AgentDefinition:
    is_strict = level == "strict"
    return AgentDefinition(
        description="安全代码审查",
        prompt=f"你是{'严格' if is_strict else '标准'}安全审查员...",
        tools=["Read", "Grep", "Glob"],
        # 严格模式用 Opus，普通模式用 Sonnet 省成本
        model="opus" if is_strict else "sonnet",
    )

# 根据运行时条件决定用哪个级别
agent_def = create_security_agent("strict")

场景三：检测子 Agent 调用

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ToolUseBlock

async for message in query(
    prompt="...",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep", "Agent"],
        agents={"code-reviewer": AgentDefinition(...)},
    ),
):
    if hasattr(message, "content") and message.content:
        for block in message.content:
            # 注意：旧版本 SDK 工具名是 "Task"，新版是 "Agent"
            # 两个都要兼容
            if isinstance(block, ToolUseBlock) and block.name in ("Task", "Agent"):
                print(f"子 Agent 被调用：{block.input.get('subagent_type')}")

# 检查是否来自子 Agent 内部的消息
    if hasattr(message, "parent_tool_use_id") and message.parent_tool_use_id:
        print("  （此消息来自子 Agent 内部）")

工具组合最佳实践

子 Agent 的恢复机制

1. 第一次 query() 时从消息流里捕获 session_id
2. 解析 Agent 工具结果里的 agentId
3. 下次 query() 传 resume: sessionId，prompt 里指定 agent ${agentId}，让子 Agent 继续上次的工作

两个反常识的注意点

与内置 Agent 工具的关系

• 内置 Agent 工具：让 Claude 能派发子任务给通用子 Agent
• AgentDefinition：你定义的专用子 Agent，Claude 根据 description 决定何时调用

实践建议

1. description 要写触发条件，不要写能力描述。 "当用户提到安全问题时使用" 比 "安全代码审查专家" 更能帮助 Claude 做出准确的路由决策。
2. 先在主 Agent 里跑通，再拆子 Agent。 调试单 Agent 容易，调试多 Agent 时追问题要费更多精力。
3. 子 Agent 的 prompt 里明确说明「你会收到什么，你要输出什么」。 因为父 Agent 的上下文不会传过来，子 Agent 需要从 prompt 和工具调用里自行推断任务背景。
4. 用 model 字段路由成本。 简单的文档检查用 haiku，安全审计用 opus——同一套代码，根据任务风险等级分配不同算力。