Claude Agent SDK 如何构建 Chief of Staff 多 Agent 助手:子 Agent、Hooks 与 Plan Mode

原创2026-09-09 12:28:541,965 阅读
文章标签:示例工程人工智能大模型

Claude Agent SDK 如何构建 Chief of Staff 多 Agent 助手:子 Agent、Hooks 与 Plan Mode

这篇文章的目标是:用 Claude Agent SDK(Python)从零搭出一个“Chief of Staff”多 Agent 助手——主 Agent 负责协调,把财务分析委派给 financial-analyst 子 Agent,用 PostToolUse Hooks 给文件写入留下审计记录,并用 Plan Mode 实现“先出方案、人工批准后再执行”。完整可运行的示例在 claude-cookbooks 的 claude_agent_sdk 目录中,主教程是 01_The_chief_of_staff_agent.ipynb,配套数据与配置文件都在 chief_of_staff_agent 子目录里。适用前提:Python 版本 >=3.11,<3.13(见 pyproject.toml),已安装 uv、Node.js 与 Claude Code CLI,并在 .env 中配置了 ANTHROPIC_API_KEY。

安装环境并启动 Notebook

按 claude_agent_sdk/README.md 的步骤准备:

curl -LsSf https://astral.sh/uv/install.sh | sh
npm install -g @anthropic-ai/claude-code

然后克隆仓库并初始化依赖。README 中给出的仓库地址是 anthropic-cookbook,对应本目录结构下的 claude_agent_sdk/:

cd claude_agent_sdk
uv sync
uv run python -m ipykernel install --user --name="cc-sdk-tutorial" --display-name "Python (cc-sdk-tutorial)"

uv sync 会安装 claude-agent-sdk>=0.1.51、python-dotenv 等依赖。API Key 的写入方式是:

ANTHROPIC_API_KEY=<你的key>

依赖就绪后,用 cc-sdk-tutorial 内核打开 01_The_chief_of_staff_agent.ipynb,第一个 cell 会加载 .env 并把模型设为 MODEL = "claude-opus-4-6"。

用 CLAUDE.md 给主 Agent 提供记忆

子 Agent、Hooks 和 Plan Mode 都建立在主 Agent 能理解公司业务的基础上,这一步是所有后续功能的公共前置。项目约定是在工作目录放置 CLAUDE.md:它包含 TechStart Inc 的公司概况、财务快照(约 $500K 月燃烧、20 个月 runway)、薪酬基准和 scripts/ 目录下各脚本的调用说明。

让 SDK 读到它的方式是把 ClaudeAgentOptions 的 cwd 指向 CLAUDE.md 所在目录,并加上 setting_sources=["project"]:

messages = []
async with ClaudeSDKClient(
    options=ClaudeAgentOptions(
        model=MODEL,
        cwd="chief_of_staff_agent",  # Points to subdirectory with our CLAUDE.md
        setting_sources=["project"],
    )
) as agent:
    await agent.query("What's our current runway?")
    async for msg in agent.receive_response():
        print_activity(msg)
        messages.append(msg)

验证方式:Notebook 注明,这个提问下 Agent 应使用 CLAUDE.md 中的高层数值(约 $500K 月燃烧、20 个月 runway)。教程同时给了一个重要行为说明:当 CLAUDE.md 和细粒度数据文件(如 financial_data/burn_rate.csv,其中是 $525K 毛燃烧、$235K 净燃烧)同时存在时,Agent 可能优先读 CSV 以求精确——这是预期行为,CLAUDE.md 提供的是上下文与指引,不是硬性数据源约束;需要高层数字时在 prompt 中明确说明即可。

另外,SDK 与交互式 Claude Code 不同:默认以隔离模式运行,不会加载任何文件系统配置。要加载 .claude/ 下的 slash commands、subagents、output styles、hooks 等,必须在 options 中显式设置 setting_sources:

  • "project" → 加载 .claude/settings.json、CLAUDE.md、slash commands、.claude/agents/ 等;
  • "local" → 加载 .claude/settings.local.json(本项目把 hooks 配置在这里);
  • "user" → 加载 ~/.claude/settings.json。

用 Task 工具定义并调用子 Agent

主 Agent 委派工作的机制是 Task 工具。子 Agent 用 markdown 文件定义,每个文件包含三段 frontmatter(name、description、tools)加系统提示词。仓库里现成的是 financial-analyst.md 和 recruiter.md。以 financial-analyst 为例,frontmatter 声明它的工具是 Read, Bash, WebSearch,正文中规定了:回答招聘影响问题时必须运行 python scripts/hiring_impact.py <num_engineers> [salary],并给出了 runway 需保持 12 个月以上的判断框架。

主 Agent 侧只需要两件事:把 "Task" 加进 allowed_tools,用 system prompt 指示它如何委派:

messages = []
async with ClaudeSDKClient(
    options=ClaudeAgentOptions(
        model=MODEL,
        allowed_tools=["Task"],  # this enables our Chief agent to invoke subagents
        system_prompt="Delegate financial questions to the financial-analyst subagent. Do not try to answer these questions yourself.",
        cwd="chief_of_staff_agent",
        setting_sources=["project", "local"],
    )
) as agent:
    await agent.query("Should we hire 5 engineers? Analyze the financial impact.")
    async for msg in agent.receive_response():
        print_activity(msg)
        messages.append(msg)

display_agent_response(messages, title="Hiring Impact Analysis")

验证方式:教程提供的 print_activity() 会用 🚀 标记子 Agent 被委派(带子 Agent 名)、📎 标记子 Agent 内部使用的工具(缩进显示),运行中能看到委派开始与完成边界;底层机制是主 Agent 以 {"subagent_type": "financial-analyst", "prompt": "...", ...} 参数调用 Task 工具,子 Agent 在独立上下文中执行后把结果交回主 Agent。

用 PostToolUse Hooks 记录文件写入审计

Hooks 是确定性地执行的小脚本,本例用于合规审计:每当 Agent 调用 Write 或 Edit 工具写完文件后,把这次操作追加到审计日志。两个组成部分:

  1. Hook 脚本(做什么):放在 .claude/hooks/ 下。report-tracker.py 从 stdin 读取 tool_name、tool_input,取出 file_path,生成含时间戳、动作(created/modified)、词数的记录,追加到 audit/report_history.json(只保留最近 50 条);script-usage-logger.py 则用正则匹配 scripts/ 目录下的 Python 脚本执行命令,记录到 audit/script_usage_log.json(最近 100 条)。两个脚本无论内部是否报错都以 sys.exit(0) 结束,不会阻断 Agent 主流程。
  2. Hook 配置(何时触发):放在 .claude/settings.local.json 的 hooks 字段。Notebook 中给出的配置是监听 Write 与 Edit 的 PostToolUse 事件:
"hooks": {
  "PostToolUse": [
    {
      "matcher": "Write",
      "hooks": [
        {
          "type": "command",
          "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/report-tracker.py"
        }
      ]
    },
    {
      "matcher": "Edit",
      "hooks": [
        {
          "type": "command",
          "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/report-tracker.py"
        }
      ]
    }
  ]
}

注意一个容易踩的坑:仓库当前签入的 settings.local.json 中,Edit matcher 对应的 command 是 $CLAUDE_PROJECT_DIR/.claude/hooks/report-tracker.py123(比 Notebook 展示的少了校验、多了 123 后缀),且 Bash matcher 挂载的是 script-usage-logger.py。如果你的 Edit 触发没有产生审计记录,先核对这份文件里的命令路径是否真实存在。

因为 hooks 配置在 settings.local.json,setting_sources 必须同时包含 "project" 和 "local",否则 hooks 不会加载:

messages = []
async with ClaudeSDKClient(
    options=ClaudeAgentOptions(
        model=MODEL,
        cwd="chief_of_staff_agent",
        allowed_tools=["Bash", "Write", "Edit", "MultiEdit"],
        setting_sources=["project", "local"],
    )
) as agent:
    await agent.query(
        "Create a quick Q2 financial forecast report with our current burn rate and runway projections. Save it to our /output_reports folder."
    )
    async for msg in agent.receive_response():
        print_activity(msg)
        messages.append(msg)

验证方式:执行后查看 chief_of_staff_agent/audit/report_history.json,应新增一条记录,包含 timestamp、file、path、action(Write 对应 created)、word_count 和 tool 字段;仓库中带有的历史文件就长这样(示例条目):

{
  "reports": [
    {
      "timestamp": "2025-09-12T11:28:54.692744",
      "file": "hiring_decision.md",
      "path": ".../chief_of_staff_agent/output_reports/hiring_decision.md",
      "action": "created",
      "word_count": 720,
      "tool": "Write"
    }
  ]
}

生成的报告本身落在 chief_of_staff_agent/output_reports/,例如仓库中带有的 hiring_decision.md。

用 Plan Mode 实现“先规划、后批准执行”

Plan Mode 让 Agent 只产出执行计划而不执行任何动作:不改文件、不跑命令。开启方式只有一个参数 permission_mode="plan"。

教程在 SDK 场景下给了一个明确的适配提示:Agent 规划完会尝试调用 ExitPlanMode() 工具,该工具只在交互式模式有意义;在 headless SDK 里,规划结束后你发送一个带 continue_conversation=True 的后续 query(并去掉 plan mode),Agent 就会在当前上下文中执行计划。

Notebook 的完整实现包含一层“计划捕获”逻辑,因为 Agent 可能通过三种方式输出计划:消息流直接文本、Write 工具写入 ~/.claude/plans/、Write 工具写入自定义路径。捕获优先级是:

  1. 消息流——在 prompt 中要求 Agent 把整个计划包在 <plan>...</plan> XML 标签里、且明确禁止使用 Write 工具(Notebook 的 PLAN_PROMPT 就是按这个要求写的),然后从流式消息里正则提取,要求内容超过 200 字符才算有效;
  2. Write 工具捕获——监控 tool_use 块中 Write 调用的 content 参数;
  3. 检查 ~/.claude/plans/ 目录里 5 分钟内新建的 *.md 文件作为兜底;
  4. 都没有 XML 标签但内容超过 500 字符时,把整段内容作为 fallback。

提取成功后,save_plan_to_file() 把计划连同模型名、prompt 摘要、来源写进时间戳命名的 chief_of_staff_agent/plans/plan_YYYYMMDD_HHMMSS.md,文件尾标注 “This plan was generated in plan mode and has not been executed.”;如果所有来源都提取失败,代码会抛出 RuntimeError 并列出检查过的来源,而不是静默生成空计划文件。

执行侧的配置与调用:

async with ClaudeSDKClient(
    options=ClaudeAgentOptions(
        model=MODEL,
        permission_mode="plan",
        cwd="chief_of_staff_agent",
    )
) as agent:
    await agent.query(PLAN_PROMPT)
    async for msg in agent.receive_response():
        print_activity(msg)
        messages.append(msg)

验证方式:运行结束后应打印 “Plan extracted from: {source}” 与计划字符数,并生成 chief_of_staff_agent/plans/plan_*.md。之后的人工流程是:审阅这份 plan 文件 → 批准后,用 continue_conversation=True 重新发 query 且移除 permission_mode="plan",Agent 即按已审计划执行。这就构成“plan → review → approve → execute”的循环。

把功能组合起来:agent.py 的最终调用

Notebook 最后把所有配置封装进 agent.py 的 send_query() 函数,它对调用方只暴露 4 个参数:prompt、continue_conversation、permission_mode("default" / "plan" / "acceptEdits")、output_style;其余固定项——model="claude-opus-4-6"、allowed_tools=["Task", "Read", "Write", "Edit", "Bash", "WebSearch"]、system prompt、cwd 指向 agent 目录、setting_sources=["project", "local"]——都已在文件内配好。

组合后的典型调用(Notebook 的最终示例):

from chief_of_staff_agent.agent import send_query

result, messages = await send_query(
    "/budget-impact hiring 3 senior engineers. Save your insights by updating the 'hiring_decision.md' file in /output_reports or creating a new file there",
    # permission_mode="plan", # Enable this to use planning mode
    output_style="executive",
)

这一条 query 依次走通了:/budget-impact slash command(定义在 .claude/commands/budget-impact.md,通过 $ARGUMENTS 展开成要求调用 financial-analyst 子 Agent 的完整 prompt)→ financial-analyst 子 Agent 通过 Bash 执行 scripts/hiring_impact.py → 主 Agent 把结论写入 output_reports/hiring_decision.md → Write 触发 report-tracker.py 钩子写入 audit/report_history.json。output_style 参数会转成 settings='{"outputStyle": "executive"}',对应 .claude/output-styles/ 下的风格文件(frontmatter 的 name 必须与文件名严格一致,区分大小写)。

端到端的验证清单:

  1. visualize_conversation(messages) 能看到主 Agent 通过 Task 工具委派给 financial-analyst 的边界;
  2. output_reports/hiring_decision.md 存在且内容包含燃烧、runway 影响数字;
  3. audit/report_history.json 新增一条 action: "created" 的写入记录;
  4. 若开启了 permission_mode="plan",则 chief_of_staff_agent/plans/ 下生成带时间戳的 plan 文件,且文件尾部注明尚未执行。

限制与已知边界

  • SDK 默认隔离模式不加载任何文件系统配置,漏写 setting_sources 是子 Agent、hooks、slash commands “全部失效”的最常见原因;hooks 还需要额外带上 "local"。
  • Plan Mode 在 headless SDK 下需要自己处理 ExitPlanMode() 的行为,按本文的方式(<plan> 标签 + 多来源捕获)落地,再靠 continue_conversation=True 执行已批准的计划。
  • ExitPlanMode 之外,Notebook 01 的下一个主题(MCP 服务器接入)见 02_The_observability_agent.ipynb,需要 GitHub Token 与 Docker,不属于本文任务范围。
  • 架构与调用时序可对照 flow_diagram.md 中的 mermaid 图:User → Chief of Staff → Task 工具 → financial-analyst / recruiter → Python 脚本,写报告后经 Post-Write Hook 记入审计。
登录后查看全文
claude-cookbooks