Claude Agent SDK 如何构建 Chief of Staff 多 Agent 助手:子 Agent、Hooks 与 Plan Mode
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 工具写完文件后,把这次操作追加到审计日志。两个组成部分:
- 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 主流程。 - 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 工具写入自定义路径。捕获优先级是:
- 消息流——在 prompt 中要求 Agent 把整个计划包在
<plan>...</plan>XML 标签里、且明确禁止使用 Write 工具(Notebook 的PLAN_PROMPT就是按这个要求写的),然后从流式消息里正则提取,要求内容超过 200 字符才算有效; - Write 工具捕获——监控
tool_use块中Write调用的content参数; - 检查
~/.claude/plans/目录里 5 分钟内新建的*.md文件作为兜底; - 都没有 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 必须与文件名严格一致,区分大小写)。
端到端的验证清单:
visualize_conversation(messages)能看到主 Agent 通过 Task 工具委派给financial-analyst的边界;output_reports/hiring_decision.md存在且内容包含燃烧、runway 影响数字;audit/report_history.json新增一条action: "created"的写入记录;- 若开启了
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 记入审计。