合集

Claude Agent SDK 实战

已更新 27 章
阅读进度 4%

序言

为什么还要写一本 Claude Agent SDK 的书

“我已经有 Claude Code 了，为什么还要用 Claude Agent SDK 自己造一个更差的？”

这是决定写这本书之后，我被问得最多的问题。也是我一开始问自己的问题。

我第一次用 SDK 写 Agent，写了一个两百行的循环：读文件、改代码、跑测试。它能把测试改绿，但修不好 bug——因为它把测试改了。同一个模型，放进 Claude Code 里，它能修好；放进我的循环里，它走捷径。

我一开始以为是模型不够聪明，换模型、改提示词、加“绝对不要修改测试”的警告。结果只是从“改测试”变成“说这个测试本身有问题”。

后来我才明白：差别不在模型，在模型外面那套程序。

那套程序叫 Harness。

这本书，就是把这套东西拆开给你看。

1. Claude Code 和 Claude Agent SDK 是什么关系

先把最容易混淆的事说清楚。

Claude Code 是一个产品，Claude Agent SDK 是这套 Harness 的库接口。

它们不是替代关系：一个把同一套 Harness 做成产品，一个把它做成库。

text
你的代码 / 你的产品
        │
        ▼
Claude Agent SDK（库：配置、消息流、回调）
        │
        ▼
Claude Code CLI（Harness：循环、工具、权限、上下文、压缩、会话）
        │
        ▼
模型 API

这张图里最重要的一点是：SDK 不实现 Agent Loop。

循环、工具执行、权限判定、上下文组装、压缩、会话落盘，都在 Claude Code CLI 里。SDK 做两件事：

  1. 把你的配置翻译成 CLI 的启动参数和控制请求；
  2. 把 CLI 的消息流和回调翻译回你的 Python 代码。

所以你可以把 SDK 理解成“这台 Harness 的库接口”，而不是“一个从零搭 Agent 的框架”。

所以有个很常见的误解：用了 SDK，不等于自动拥有 Claude Code 的效果。 SDK 让你用上同一套 Harness，但系统提示、工具面、上下文、权限、压缩、评测仍然要你配。配错了，你只是把一台 Nginx 配成了 Hello World。

SDK 不能改循环。 这是它的边界，也是这本书第二部分存在的理由：如果你需要完全控制循环，就得自己造，或者用裸 Messages API。第二部分会带你造一遍；第三部分再回到 SDK，看哪些不用自己写、哪些必须自己配。

Claude CodeClaude Agent SDK
使用者人程序
形态终端里的 CLI 产品Python / TypeScript 库
循环内置同一套（在 CLI 里）
工具内置 + MCP内置 + MCP + 进程内工具
权限交互 UI + settings / hookscan_use_tool + 权限模式 + hooks
输出终端文本消息流、结构化输出
部署本地 / CI嵌入产品、多租户服务
定制设置、技能、子 Agent上述全部 + 程序化控制

说白了：Claude Code 是给人用的 Agent，Agent SDK 是给你造 Agent 的库。

2. 这本书讲什么

这不是一本 API 大全，也不是一本 Claude Code 源码解读。

它只做一件事：带你造一个 Agent，造两遍。

  • 第一遍，tiny：用 Anthropic Messages API 手写，从一个 while True 循环开始，逐步加工具、权限、上下文、压缩、会话、子 Agent，最后组装成一个能修测试、能加功能的 coding agent。
  • 第二遍，sdk：用 Claude Agent SDK 把同一个 Agent 重写一遍。你会发现，有些代码不用写了，有些配置反而更重要了。

全书分五部分：

部分内容你得到的
一、定位Harness 六问；Claude Code / SDK / 裸 API 的关系一张能诊断任何 Agent 的检查表
二、亲手造循环 → 工具 → 权限 → 上下文 → 压缩 → 会话 / 子 Agent → 组装一个能跑的 tiny coding agent
三、换引擎用 SDK 重写同一个 Agent；工具、权限、上下文、长任务、控制、边界一个能配、能扩、能上线的 SDK Agent
四、工程化评测、成本、时延、可靠性、安全一套证明“它变好了”的方法
五、实战coding / research / support 三个业务 Agent一张迁移到你自己的业务的设计清单

每一章都围绕同一个问题：Agent 这一章又强在哪？

不是“又一个机制”，是“同一个任务，这次它又做到了什么、又暴露了什么”。

代码都在这个仓库：https://github.com/kevinkelin/claude-agent-sdk-book。正文只贴关键片段；第 1 章会详细到 import，后面的章节会逐步精简，把完整文件交给 GitHub。

3. Harness 到底在做什么

“Harness”这个词，你可以在很多地方看到。这本书里，它只有一个意思：

Harness 是模型外面那套决定“看见什么、能做什么、允许做什么、什么时候算完、失败怎么办、做完留下什么”的程序。

拆成六个问题：

  1. 模型看见什么？ 系统提示、工具定义、历史、文件、记忆、技能。
  2. 模型能做什么？ 工具集合、参数、执行、结果回填。
  3. 模型允许做什么？ 权限、审批、沙箱、路径限制。
  4. 模型什么时候停？ 轮数、预算、完成条件、中断。
  5. 模型失败了怎么办？ 错误分类、重试、回填、恢复。
  6. 模型做完留下什么？ 会话、压缩、笔记、检查点、审计。

同一个模型，这六个问题的答案不同，表现可以差几倍。

Claude Code 的优势，很大程度上不是“它的模型更聪明”，而是它把这六个问题回答得很好：工具打磨过、上下文会挑、权限有闸门、压缩有策略、会话能恢复、子 Agent 能分工、错误能兜底。

你造的 Agent 不如 Claude Code，通常也是因为这六个问题里，有几个你没回答。

这就是 Harness 的作用：它不改变模型有多聪明，它决定模型能不能把事做完。

这本书的每一章，都是在回答其中一问，或者把一问接到 SDK 上。

4. 读完你会得到什么

不是“了解了 SDK”，是四样能拿出来的东西：

  1. 一个能修测试、能加功能的 coding agent。 不是玩具 demo，是能在一个真实小仓库里跑完“读—改—跑—验证”的 Agent。
  2. 一张 Harness 控制矩阵。 行为 × 机制 × 你手写的实现 × SDK 旋钮 × 不能控制的部分。拿着它，你能对自己的 Agent 做一次 30 分钟的诊断。
  3. 一套评测方法。 同一组任务、同一个模型，量成功率、轮数、成本、失败模式；不是凭感觉调提示词。
  4. 一张业务 Agent 的设计清单。 任务、工具、上下文、权限、状态、评测、上线，一页纸填完，知道第一周该做什么。

如果你只想查 API，官方文档比我写得好。这本书的价值在“为什么”和“怎么选”：为什么这个选项存在，什么时候该用它，不用它会怎样。

5. 有了 Claude Code、Codex、WorkBuddy，为什么还要自己开发 Agent

先说一句可能不讨喜的话：不是所有人都需要自己造 Agent。

Claude Code、Codex、WorkBuddy 本质上都是“模型 + Harness + 产品体验”的打包；差别在 Harness 和场景。

如果你的问题刚好是“在终端里让人和 Agent 一起改代码”，Claude Code 已经很好；如果是“在 IDE 里补全和改代码”，Codex、Cursor 这类产品已经很成熟；如果是“在办公/业务场景里跑固定流程”，WorkBuddy 这类产品可能已经覆盖了你的需求。

工具能解决的问题，不要用造轮子解决。

那什么时候值得自己造？通常是下面五种情况。

第一种：你要把它嵌进自己的产品

Claude Code 是给人用的终端产品；你的产品可能是一个客服后台、一个数据分析平台、一个 IDE 插件、一条 CI 流水线。你需要 Agent 作为服务的一部分，而不是一个人在终端里敲。

SDK 提供的消息流、控制请求、回调，就是为这种“嵌进去”设计的。

第二种：你要用自己的工具和数据

你的 Agent 要查订单、读工单、调内部 API、访问数据库。Claude Code 通过 MCP 能接一部分，但你的工具可能就跑在自己的进程里，需要直接调 Python 函数；你的数据可能有自己的权限模型。

SDK 的进程内工具、MCP、权限回调，能把“你的系统”接进来。

第三种：你要用自己的策略和审批

“退款超过 500 要人工批”“改测试文件直接拒绝”“跨租户读写一律拒绝”——这些不是提示词能保证的，要落到代码里的权限管线。

Claude Code 有 settings 和 hooks；SDK 的 can_use_tool 能把每一次写操作接到你的风控引擎，返回结构化的 allow / deny。

第四种：你要程序化编排和结构化输出

多个 Agent 分工、上游结果进下游系统、运行中中断/切模型/查上下文、最后输出一个 JSON 而不是一段作文——这些需要 typed messages 和控制请求，不是终端文本能稳定支持的。

第五种：Harness 和领域层就是你的产品差异

模型是大家都能买的；Harness 和领域层是你自己能建的。

同样一个模型，工具怎么设计、上下文怎么挑、权限怎么设、失败怎么恢复，决定了它在你的业务里好不好用。你越懂 Harness，越能把“通用模型”变成“你的 Agent”。

而且，懂 Harness 还有一个附带好处：你能诊断。 当 Agent 变差时，你知道该看工具、看上下文、看权限、看终止条件，而不是只会改提示词。

什么时候不该自己造

  • 产品已经刚好解决你的问题：用产品。
  • 你只需要一次 LLM 调用：用 Messages API，别引入一个进程。
  • 你要自定义整个循环/编排：用裸 API 或别的框架，SDK 只会挡路。
  • 你只是想“拥有一个自己的 Agent”：先想清楚它要替谁做什么；否则造出来也只是个 demo。

这本书不劝你造，只教你在要造的时候，知道自己在造什么。

6. 这本书不做什么

  • 不做 API 大全。 官方文档更全、更新更快；本书只讲最常用、最容易配错的那部分。
  • 不读 Claude Code 源码。 CLI 是闭源的；本书不反编译、不猜内部实现。我们通过自己造一遍来理解机制，再对照 SDK 的公开行为。
  • 不教提示词玄学。 提示词是 Harness 的一部分，但不是全部；本书更关心工具、权限、上下文、终止、恢复。
  • 不承诺“读完你就能做出比 Claude Code 更好的 Agent”。 它给你的是方法：怎么量差距、怎么补、怎么判断值不值得补。
  • 不假设你必须用 Claude 模型。 书里的例子可以用 Anthropic 官方 API，也可以用兼容端点；差异会在代码里标出来。

7. 怎么读

有两种读法。

深入路径（推荐）：

text
序言 → 第 1–2 章 → 第二部分（3–9，亲手造）
     → 第三部分（10–16，换 SDK）
     → 第四部分（17–21，工程化）
     → 第五部分（22–25，实战）

快速路径（只想尽快用 SDK）：

text
序言 → 第 1–2 章 → 第三部分（10–16）
     → 遇到“这个选项为什么存在”时，回到第二部分对应章节
     → 第四部分按需读

第 16 章的控制矩阵是两条路径的汇合点。不管你从哪条路来，最后都应该能填出那张表。

前置知识：会 Python，见过 async/await。不需要写过 Agent，也不需要读过 Claude Code 源码。

版本基线：本书以 claude-agent-sdk 0.2.168、CLI 2.1.301 为基线；版本会变，但六问和控制矩阵不会。代码在 GitHub 上按章打 tag，正文里给链接。

最后

这本书想回答的，不是“SDK 有哪些 API”，而是两个更具体的问题：

  1. 为什么同一个模型，在 Claude Code 里能干活，在你的循环里却把测试改了？
  2. 你要怎么造出前者那样的 Agent？

下一篇，从一个具体的事故开始。