Claude Agent SDK 实战教程：claude-cookbooks 中从零构建研究、多 Agent 编排到生产部署的九大 Notebook 指南

本文基于 claude-cookbooks 仓库中的 claude_agent_sdk/README.md，完整讲解 Claude Agent SDK 教程系列的安装配置、九大 Notebook 的技术脉络，并结合仓库内的研究 Agent、Chief of Staff Agent、可观测性 Agent 与站点可靠性 Agent 等真实实现，剖析 ClaudeAgentOptions、MCP 集成、Hooks 合规审计与多层级部署的源码级细节，帮助读者系统掌握用 Claude Agent SDK 构建通用 Agent 系统的全套方法。

一、为什么选择 Claude Agent SDK

Claude Agent SDK 教程系列的出发点，是把 Claude Code 中"裸金属"式的 Agent 能力从软件工程场景解放出来。README 的背景章节指出：Claude Code 的真正突破不仅在于编码能力，而在于 Claude 在 Agent 式工作上的突出表现——

• 自主地把复杂任务拆解为可管理的步骤；
• 有效使用工具，并智能决定何时使用哪个工具；
• 在长任务中维持上下文与记忆；
• 从错误中优雅恢复、调整策略；
• 知道何时该向用户澄清，何时基于合理假设继续推进。

这些能力使 Claude Code 成为"最接近裸金属的"Agent 执行框架。SDK 公开发布后，开发者开始将其用于编码之外的场景：跨多源信息聚合的研究 Agent、数据集探索与洞察生成的数据分析 Agent、处理重复业务流程的工作流自动化 Agent、监控并响应系统问题的可观测性 Agent，以及内容生成 Agent。这个教程系列正是展示如何用 Claude Agent SDK 为任意领域构建高效 Agent，从简单自动化到复杂企业级系统。

需要说明的前提：该教程假设读者已对 Claude Code 有一定熟悉度，适合希望把 Claude Code 的 Agent 能力用于软件工程之外任务的学习者。

二、环境准备与项目配置

README 给出了五步完整的环境搭建流程，以下按原样继承并结合仓库的 pyproject.toml 补充依赖细节。

2.1 安装基础工具链

首先安装 uv、Node.js 和 Claude Code CLI（若尚未安装）：

curl -LsSf https://astral.sh/uv/install.sh | sh

npm install -g @anthropic-ai/claude-code

2.2 克隆并初始化项目

git clone https://github.com/anthropics/anthropic-cookbook.git

cd anthropic-cookbook/claude_agent_sdk

uv sync

从 pyproject.toml 可以确认项目的真实依赖面：

• Python 版本要求为 >=3.11,<3.13；
• 核心依赖 claude-agent-sdk>=0.1.51，这是全部 Notebook 的运行时基础；
• mcp-server-git（Notebook 02 使用的 Git MCP 服务器）、openai-agents==0.9.3（Notebook 04 迁移示例需要同时运行 OpenAI Agents SDK 做对照）、pandas、httpx、python-dotenv、ipykernel、markdown；
• 另提供 slack 可选依赖组（slack-bolt、slack-sdk、aiohttp）。

2.3 注册 Jupyter Kernel

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

注册后，在 Notebook 界面切换到 "Python (cc-sdk-tutorial)" kernel，即可让 Notebook 直接复用 uv sync 建立的虚拟环境，避免依赖错配。

2.4 配置 API Key 与 GitHub Token

1. 访问 platform.claude.ai，注册或登录账号；
2. 点击 "Get API keys" 获取密钥；
3. 将其粘贴进 .env 文件：ANTHROPIC_API_KEY=。

如果计划完成 Notebook 02（可观测性 Agent），还需要：

1. 申请一个 GitHub 细粒度（Fine-grained）个人访问令牌，选择默认选项（公共仓库、无账户权限）；
2. 在 .env 中添加 GITHUB_TOKEN="<token>"；
3. 确保本机 Docker 正在运行——因为该 Notebook 通过 Docker 容器拉起 GitHub MCP Server。

三、教程系列总览：从单行研究 Agent 到动态工作流

整个系列循序渐进，每个 Notebook 建立在前一个之上，逐步引入新概念与能力，同时保持生产可用的实现水平。系列覆盖五大能力面：

• 核心 SDK 基础：Python SDK 中的 query() 函数与 ClaudeSDKClient、ClaudeAgentOptions 接口；
• 工具使用模式：从基础 WebSearch 到复杂 MCP 服务器集成；
• 多 Agent 编排：专业化子 Agent 与协调机制；
• 企业特性：用 Hooks 做合规跟踪与审计追踪；
• 外部系统集成：通过 Model Context Protocol（MCP）连接外部系统。

3.1 Notebook 00：单行研究 Agent

00_The_one_liner_research_agent.ipynb 用几行代码构建一个简洁而强大的研究 Agent，引入 SDK 核心概念，展示自主信息收集与综合。关键概念包括：基于 query() 与异步迭代的基础 Agent 循环、用于自主研究的 WebSearch 工具、基于 Read 工具的多模态能力、基于 ClaudeSDKClient 的会话上下文管理，以及用于 Agent 专业化的系统提示词。

仓库中对应的完整实现位于 research_agent/agent.py，其中的 send_query() 是该系列的"参考模板"：

options = ClaudeAgentOptions(
    model=model,
    allowed_tools=["WebSearch", "Read"],
    continue_conversation=continue_conversation,
    system_prompt=RESEARCH_SYSTEM_PROMPT,
    max_buffer_size=10 * 1024 * 1024,  # 10MB 缓冲，用于处理图片与大响应
)

async with ClaudeSDKClient(options=options) as agent:
    await agent.query(prompt=prompt)
    async for msg in agent.receive_response():
        messages.append(msg)
        ...
        if hasattr(msg, "result"):
            result = msg.result

从源码可以看到几个值得注意的设计点：continue_conversation 参数用于在多次调用间延续会话；max_buffer_size 显式放大到 10MB 以容纳多模态内容；activity_handler 回调同时支持同步与异步两种实现（源码注释说明同步版本用于控制台输出、异步版本用于 WebSocket 等网络 I/O），方便将同一模块嵌入不同形态的产品；get_activity_text() 则展示了如何从消息流中解析出"正在调用哪个工具"的活动文本，可复用于日志与监控。

3.2 Notebook 01：Chief of Staff Agent

01_The_chief_of_staff_agent.ipynb 为一家初创公司 CEO 构建综合 AI 幕僚长，展示生产环境的高级 SDK 特性，演示如何构建带治理、合规与专业领域知识的复杂 Agent 架构。

探索的关键特性：

• 记忆与上下文：通过 CLAUDE.md 文件持久化指令；
• 输出样式（Output Styles）：面向不同受众定制沟通方式；
• Plan Mode：对复杂任务只做战略规划、不执行；
• 自定义斜杠命令：为常用操作提供用户友好的快捷方式；
• Hooks：自动化合规跟踪与审计追踪；
• 子 Agent 编排：协调专业化 Agent 提供领域专长；
• Bash 工具集成：执行 Python 脚本承载程序性知识与复杂计算。

仓库提供了完整的 chief_of_staff_agent/ 实现目录，其结构与 Agent 能力一一对应：

目录/文件	作用
CLAUDE.md	持久化公司上下文：TechStart Inc 的财务快照、团队结构、关键指标、薪酬基准、董事会构成、竞争格局、近期与待决事项、风险因素，以及可用脚本的用法说明
.claude/agents/	子 Agent 定义：financial-analyst.md（财务分析师）与 recruiter.md（招聘官），通过 Task 工具委派
.claude/commands/	斜杠命令：/budget-impact、/strategic-brief、/talent-scan 等
.claude/output-styles/	输出样式：executive.md（高管视角）与 technical.md（技术视角）
.claude/hooks/	审计脚本：report-tracker.py 与 script-usage-logger.py
scripts/	供 Bash 调用的程序性知识脚本：financial_forecast.py、talent_scorer.py、decision_matrix.py、simple_calculation.py、hiring_impact.py
financial_data/	公司数据：burn_rate.csv、hiring_costs.csv、revenue_forecast.json
audit/	Hooks 产出的审计记录：report_history.json、script_usage_log.json

agent.py 中的关键配置揭示了这些特性如何接入 SDK：

settings = None
if output_style:
    settings = json.dumps({"outputStyle": output_style})

options = ClaudeAgentOptions(
    model="claude-opus-4-6",
    allowed_tools=["Task", "Read", "Write", "Edit", "Bash", "WebSearch"],
    continue_conversation=continue_conversation,
    system_prompt=system_prompt,
    permission_mode=permission_mode,   # "default" | "plan" | "acceptEdits"
    cwd=os.path.dirname(os.path.abspath(__file__)),
    settings=settings,                  # 以 JSON 覆盖输出样式
    setting_sources=["project", "local"],
)

其中源码注释特别强调：setting_sources 必须包含 "project"，SDK 才会从文件系统加载 .claude/commands/（斜杠命令）、CLAUDE.md（项目指令）、.claude/agents/（子 Agent 定义）与 .claude/settings.local.json（Hooks）；否则 SDK 处于隔离模式，不加载任何文件系统配置。permission_mode 三值参数则对应 Plan Mode 的开关——"plan" 只规划不执行。

Hooks 的实际接线在 settings.local.json 中：PostToolUse 阶段为 Bash 工具挂载 script-usage-logger.py（记录脚本使用日志到 audit/script_usage_log.json），为 Write 工具挂载 report-tracker.py（把产出报告写入 audit/report_history.json）。这正是 README 所说"Hooks 用于自动化合规跟踪与审计追踪"的落地方式。

3.3 Notebook 02：可观测性 Agent

02_The_observability_agent.ipynb 通过 Model Context Protocol 把 Agent 连接到外部系统，让 Agent 从被动观察者变为 DevOps 工作流的主动参与者。

高级能力：

• Git MCP Server：13+ 工具用于仓库分析与版本控制；
• GitHub MCP Server：100+ 工具实现完整 GitHub 平台集成；
• 实时监控：CI/CD 流水线分析与失败检测；
• 智能事件响应：自动化根因分析；
• 生产工作流自动化：从监控到可执行洞察。

observability_agent/agent.py 展示了 MCP 集成的标准写法。GitHub MCP Server 以 Docker 容器方式启动，令牌通过环境变量注入：

return {
    "github": {
        "command": "docker",
        "args": ["run", "-i", "--rm", "-e",
                "GITHUB_PERSONAL_ACCESS_TOKEN",
                "ghcr.io/github/github-mcp-server"],
        "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": token},
    }
}

一个值得学习的工程细节是对工具的"白名单 + 黑名单"双重约束：allowed_tools 只放行 mcp__github 前缀的工具，同时 disallowed_tools = ["Bash", "Task", "WebSearch", "WebFetch"]。源码注释解释得很直白——如果不禁用 Bash，Agent 可能绕过 MCP 直接用 gh CLI 完成任务，观测目标就失真了。另外当 .env 中没有 GITHUB_TOKEN 时，get_github_mcp_server() 会返回空字典优雅降级，而不是报错。

3.4 Notebook 03：站点可靠性 Agent

03_The_site_reliability_agent.ipynb 把能力从只读观测推进到读写修复：构建一个 SRE 事件响应 Agent，自主调查生产事故、诊断根因、应用修复并记录结果。

关键能力：

• MCP 工具服务器：12+ 工具覆盖指标、基础设施、诊断与文档，通过 JSON-RPC 子进程通信；
• Prometheus 集成：用 PromQL 查询错误率、延迟与数据库连接监控；
• 读写修复：编辑配置文件、重启 Docker 服务并验证修复；
• 安全 Hooks：PreToolUse 钩子校验写操作（连接池大小范围、配置合理性检查）；
• 端到端事件生命周期：从检测到修复再到事后文档；
• 生产扩展：通过条件式 MCP 工具注册可选接入 PagerDuty 与 Confluence。

仓库中的 sre_mcp_server.py 印证了这些描述：文件头注释说明该服务器作为独立进程运行、通过 stdio 使用 MCP JSON-RPC 协议通信，"以避免 SDK 的 MCP 竞态条件缺陷"；内置 query_metrics（PromQL 查询，描述中直接给出按服务错误率、延迟 P99、数据库连接、CPU/内存等常用调查查询模板与调查工作流）、list_metrics、get_service_health 等工具；配置段通过环境变量条件加载 PagerDuty 与 Confluence 凭据，与 README 中"条件式 MCP 工具注册"的说法一致。配套的 infra_setup.py 用于搭建模拟生产环境，examples/sre_bot_slack.py 则展示了 Slack 机器人形态的集成。

3.5 Notebook 04：从 OpenAI Agents SDK 迁移

04_migrating_from_openai_agents_sdk.ipynb 以一个费用审批 Agent 为例，在两个 SDK 同时运行的情况下把现有 OpenAI Agents SDK 应用移植到 Claude Agent SDK，逐个映射各原语。关键概念包括：

• 原语映射：@function_tool、guardrails、Runner.run 到 Claude 对应物的对照；
• 单 Agent 移植：自定义工具、输入/输出 guardrails、多轮会话与持久化恢复；
• Client 与 query() 的选择：何时使用有状态的 ClaudeSDKClient、何时使用无状态的 query()；
• 可观测性：把 SDK 的 OpenTelemetry 导出接入现有技术栈。

这也解释了 pyproject.toml 中为何精确锁定 openai-agents==0.9.3——迁移示例需要两套 SDK 并行运行做真实对照。

3.6 Notebook 05：构建会话浏览器

05_Building_a_session_browser.ipynb 构建 Agent 产品用户预期的会话历史侧边栏，直接读取 SDK 落盘的会话转录，而不是自己写解析器。关键概念：

• 会话列表：带分支、标题、最后修改时间等元数据的分页列表；
• 读取转录：不启动 Agent 即重放已存会话的消息；
• 历史管理：重命名、打标签、过滤会话；
• 分叉（Forking）：在任意点分叉会话，并把分叉作为实时的 query() 调用恢复。

配套的 session_browser_demo/ 目录承载该 Notebook 的演示代码。

3.7 Notebook 06：漏洞检测 Agent

06_The_vulnerability_detection_agent.ipynb 构建漏洞发现 Agent：对一个 C 目标做威胁建模，用内置文件工具猎捕内存安全缺陷，并把发现分诊成评审者可以直接行动的报告。关键概念：

• 威胁建模：采用"先引导后访谈"的 ClaudeSDKClient 会话，产出 THREAT_MODEL.md；
• Agentic 查找循环：使用内置 Read/Grep/Glob 工具而非手写文件访问；
• 链式阶段：分离的 find、triage、report 三次 query() 调用，各自输出符合 schema 的 JSON。

目标 C 程序位于 vulnerability_detection_agent/canary/canary.c，作为埋有内存安全缺陷的被测对象。

3.8 Notebook 07：托管你的 Agent

07_Hosting_the_agent.ipynb 用同一个容器镜像与 HTTP 接口，把 Notebook 00 的研究 Agent 部署到三个运维成熟度层级。关键概念：

• Docker：本地与单机 VM 托管，服务开发循环与内部工具；
• Modal：带 URL 的托管 Serverless，支持缩容到零；
• Kubernetes：在自己的集群中做多租户部署；
• 可移植接口：三层之间 Agent 代码、镜像与 HTTP 面完全一致。

hosting/ 目录提供了三层部署的完整配套：docker/（Dockerfile 与 compose）、modal/（modal_app.py）、kubernetes/（含 namespace、gateway、egress-proxy、redis、network-policy 等 manifests 与 kind 快速上手脚本），以及统一的 server.py 与 entrypoint.sh。

从 server.py 的源码可以看到部署侧几个关键设计决策：

• 服务器刻意保持"薄"：不管理生命周期（由编排器回收空闲容器）、不管理认证（交给网关）、不转换 SDK 消息（客户端拿原始类型），职责只是运行 Agent、流式输出消息、让会话可恢复；
• 由于 SDK 自己生成会话 ID 不可指定，服务器维护一份持久化的"外部 session_id → SDK 内部 ID"映射，在后续轮次通过 resume= 传入，映射文件与转录一起存放在 CLAUDE_CONFIG_DIR 下，重启后依然有效；
• 安全裁剪明确写在注释里：宿主机版本故意去掉 Read 工具，只保留 WebSearch——因为容器里没有上传路径，Read 能触及的只有容器自身（包括 /data 下其他会话的转录与含 API Key 的环境变量），被注入的网页结果可能诱导 Agent 外泄这些内容；
• 默认无认证（必须置于先做认证、再按调用者过滤 session_id 的网关之后）；无网关的层级可设置 AGENT_AUTH_TOKEN 启用 Bearer 令牌校验，源码使用 secrets.compare_digest 避免时序侧信道；
• 请求体在到达 JSON 解析器之前先做 256KB 上限检查，超限直接返回 413。

3.9 Notebook 08：用动态工作流编排大规模子 Agent

08_Dynamic_workflows.ipynb 突破单一上下文窗口的协调上限：从 Agent SDK 触发动态工作流——Claude 为你的任务编写一个 JavaScript 编排脚本，运行时在后台跨一组并行子 Agent 执行它。关键概念：

• 子 Agent vs 工作流：计划归谁持有——模型上下文，还是确定性脚本；
• 从 SDK 触发工作流：Workflow 工具、allowed_tools 与流式运行进度；
• 扇出 + 对抗式校验：每个断言配一个并行校验者，每个校验者的结论在被采信前还要经受一个"怀疑者" Agent 的挑战；
• 阅读生成脚本：agent()、parallel()、pipeline()、阶段（phases）与结构化输出 schema。

四、Agent 实现的通用结构与复用方式

四个完整 Agent 实现遵循同一套工程模式，读任意一个即可迁移到其他：

<agent_name>/
├── agent.py          # send_query() 封装 ClaudeAgentOptions + ClaudeSDKClient
├── CLAUDE.md         # 持久化上下文（需要时）
├── .claude/          # agents / commands / hooks / output-styles（需要时）
└── 领域数据与脚本目录

• 所有 Agent 的 send_query() 都遵循 async with ClaudeSDKClient(options=...) → await agent.query() → async for msg in agent.receive_response() 的异步流式模式；
• 共享的可视化逻辑集中在 utils/agent_visualizer.py（display_agent_response、print_activity、reset_activity_context）与 utils/html_renderer.py，Notebook 内直接复用，保证显示一致；
• 各 Agent 通过 .env + python-dotenv 加载凭据（research_agent/agent.py 第 27 行的 load_dotenv() 即典型写法）。

README 还说明了一个独立运行入口：每个 Notebook 的实现都在对应目录下，若在 Notebook 之外导入 Agent 模块，要么从 claude_agent_sdk/ 目录运行，要么以可编辑模式安装本包：

uv pip install -e .

五、系列能力进阶路线小结

把九大 Notebook 串起来，可以看到一条清晰的能力进阶线：

1. 00 建立 query() / ClaudeSDKClient / ClaudeAgentOptions 的心智模型；
2. 01 叠加企业特性：CLAUDE.md 记忆、输出样式、Plan Mode、斜杠命令、Hooks 审计、子 Agent 与 Bash 脚本化程序知识；
3. 02/03 通过 MCP 打通外部世界——从只读的 GitHub 观测到 Prometheus + Docker 的读写修复，并用 PreToolUse Hooks 给写操作加安全阀；
4. 04/05 面向工程存量与产品形态：SDK 迁移映射、会话转录的读取与分叉；
5. 06 验证 Agent 在安全审查这类高门槛领域的可行性（链式阶段 + schema 化输出）；
6. 07/08 走向生产：三层托管与多租户安全设计、面向大规模并行任务的工作流编排。

配套文件索引：系列入口 claude_agent_sdk/README.md，依赖定义 claude_agent_sdk/pyproject.toml，各 Agent 实现与部署资产均位于 claude_agent_sdk/ 下的对应子目录中。按照 README 的环境准备步骤完成 uv、Claude Code CLI、.env 凭据配置后，即可从 Notebook 00 开始逐篇动手实践。