把智能体当人用：Claude Agent SDK 的架构设计哲学

这篇不打算做 API 说明书——官方文档已经写得很清楚了。我想拆的是它背后的设计决策：每一个原语（primitive）在解决什么根本约束，做了哪些权衡。把这些串起来，你会发现 Claude Agent SDK 不是”一堆功能的集合”，而是一套围绕单一稀缺资源展开的自洽系统。

从一次改名说起

Claude Agent SDK 的前身叫 Claude Code SDK。2025 年这次改名不是市场部拍脑袋，而是一个技术承认：真正可复用、有价值的东西，不是”写代码的能力”，而是驱动 Claude Code 的那套 agent harness（智能体外壳）。

官方的原话是——这套 SDK 给你的是”the same tools, agent loop, and context management that power Claude Code”。也就是说,Claude Code 只是这套 harness 的一个应用实例;同一套外壳可以驱动邮件助手、研究智能体、运维机器人。

这里藏着全文第一个、也是最重要的观点:

模型能力是天花板,harness 才是你能施工的地方。

你改不了 Claude 的权重,但你能决定它看到什么上下文、能调什么工具、行动前后拦不拦、错了怎么自查。可靠性工程几乎全部发生在 harness 层。理解 Agent SDK,本质上是在理解”一个自主循环要可靠,外壳需要提供哪些结构”。

第一性原理:给智能体一台电脑

传统做法要让 AI 能干活,思路是”为每个能力做一个专用集成”:要查数据库就封一个 query 接口,要发邮件就封一个 send 接口……集成数量随需求线性膨胀,而且每一个都是脆的。

Agent SDK 的底层哲学反过来——官方原话是 “give your agents a computer, allowing them to work like humans do”(给智能体一台电脑,让它像人一样干活)。

人类程序员靠什么干几乎所有事?文件系统 + 终端 + 写代码。这三样是通用原语:

• 文件系统:读写任何东西,存放中间产物
• 终端(Bash):调用系统里一切已有的程序
• 代码生成:把一次性操作变成可组合、可复用的逻辑

一旦把这三样给了模型,能力就不再需要一个个专用集成去堆——绝大多数任务都能被”用电脑的人”的方式拆解出来。这就是为什么 SDK 内置的核心工具是 Read / Write / Edit / Bash / Glob / Grep 这种通用文件与命令操作,而不是一堆业务专用接口。

文档里那句话点得很透:“Code is precise, composable, and infinitely reusable.” 代码作为行动手段,精确、可组合、可无限复用——这是任何自然语言指令或专用 API 都比不了的杠杆。

引擎:agent loop 是控制循环,不是流水线

如果说”给它一台电脑”是世界观,那 agent loop 就是发动机。官方把智能体工作流概括成一个循环:

gather context  →  take action  →  verify work  →  repeat
   收集上下文        采取行动         验证结果        循环

初看平平无奇,但要抓住一个关键区别:这是控制循环(control loop),不是数据流水线(pipeline)。

流水线是”输入 → 固定步骤 A → B → C → 输出”,步骤和顺序你写死。控制循环是”每一轮由模型自己决定下一步做什么、循环到什么时候停”。决策权在模型手里,harness 只负责把这个循环转起来、并在关键节点插手。

这一点在 SDK 和 Anthropic Client SDK 的对比里体现得最狠。用 Client SDK,tool loop 是你自己写的:

# Client SDK:循环归你写,工具执行归你实现
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)   # 你来跑工具
    response = client.messages.create(tool_result=result, **params)

用 Agent SDK,这个循环被 SDK 收走了,工具执行也内建了:

# Agent SDK:Claude 自主跑完整个循环
async for message in query(prompt="Fix the bug in auth.py"):
    print(message)

这叫控制权反转(inversion of control)。你不再是”驱动者”,而是”配置者 + 监督者”:你规定它能用哪些工具、行动前后插什么钩子、什么时候要你批准。循环本身归框架。

顺带记住那个入口:一切都从 query() 开始,它返回一个消息流(async iterator)。为什么是流而不是一个最终结果?因为一个自主循环可能跑几十轮、几分钟,你需要实时看到它每一步在干嘛——流式是自主智能体的天然形态,不是锦上添花。

真正的稀缺资源:上下文窗口

这是全文我最想让你记住的一节。如果你只能带走一句话:Agent SDK 的一多半设计,都是在管理”上下文窗口”这一个稀缺资源。

模型的注意力和上下文长度是有限且昂贵的。一个跑长任务的智能体,天然会往上下文里灌越来越多东西(读过的文件、跑过的命令、中间结论),迟早撑爆或被噪音淹没。所以”往上下文里放什么、什么时候清、怎么隔离”就是上下文工程(context engineering),是智能体可靠性的命脉。

把 SDK 里那些看似独立的特性用这条主线一串,全通了:

① 文件系统即外部记忆。 文档说文件系统里放的是”could be pulled into the model’s context”的信息——文件夹和文件结构本身就是一种上下文工程。不需要时,信息躺在磁盘上不占上下文;需要时才被拉进来。这等于给模型配了一块可寻址的外部内存,而不是把什么都塞进那块昂贵的”工作内存”。

② agentic search vs semantic search 的取舍。 语义检索(向量库)快,但文档明说它”less accurate, more difficult to maintain, and less transparent”(更不准、更难维护、更不透明)。官方建议先用 agentic search(让模型自己用 grep/glob 一层层找),因为它透明、零维护。这不是”技术不够先进”,而是一个刻意的权衡:优先要可解释和低维护,别一上来就上重基建。

③ subagent = 上下文隔离与防火墙。 子智能体最被低估的价值不是并行,而是上下文隔离——它们”use their own isolated context windows, and only send relevant information back to the orchestrator”(用自己独立的上下文窗口,只把相关结论回传给主控)。

翻译成人话:让一个子智能体去啃一个 5000 行的日志,它在自己的上下文里翻江倒海,最后只回你一句”第 3200 行有个空指针”。主控的上下文完全没被那 5000 行污染。这就是为什么复杂任务要拆子智能体——省的不只是时间,更是主控那块金贵的上下文预算。(SDK 里子智能体经由 Agent 工具调用,回传消息带 parent_tool_use_id 让你追溯归属。)

④ compaction:上下文的垃圾回收。 当对话逼近上下文上限,SDK 会自动把前面的历史压缩成摘要(compaction),腾出空间让循环继续跑下去。你可以把它理解成智能体版的 GC——长时任务能不能撑住,全看这一手。

看懂了吗?外部记忆、检索策略、子智能体、压缩,四个特性,一条主线。 它们全是在回答同一个问题:在有限的上下文预算里,如何让模型始终只看到”此刻最该看的东西”。

工具:模型与世界之间的接口

行动这一环,SDK 给了几种手段:内置工具、Bash/脚本、写代码、以及 MCP(Model Context Protocol)。

设计上有个容易被忽视的点:文档说工具是”prominent in Claude’s context window——design them for context efficiency”(工具会显眼地占用上下文,要为上下文效率而设计)。

也就是说,每个工具的名字、描述、参数 schema,都是要吃 token 的,而且模型是靠这些描述来决定调不调、怎么调。所以工具设计本身就是一种 prompt engineering:描述要精准,返回要克制(别把 5000 行原始输出直接砸回上下文,回摘要)。工具太多、描述太啰嗦,会直接稀释模型的注意力。工具不是越多越好,是越”配得上上下文成本”越好。

MCP 则是把”接外部系统”这件事标准化了:数据库、浏览器、第三方 API,通过统一协议接进来,认证和 API 调用由协议层处理。它和”给它一台电脑”是同一套哲学的延伸——与其为每个外部系统写死一个集成,不如提供一个标准插口。(这也正是我上一篇折腾 scrapling / browser-use MCP 的意义:给这台”电脑”插上新外设。)

验证:把 demo 变成生产的那一步

Demo 和生产系统的差距,常常就差在验证。文档的判断很直接:能自我评估的智能体”fundamentally more reliable”(在根本上更可靠)。

因为 agent loop 的闭环恰恰闭在”verify”这一环——如果智能体做完不检查,它就只是在开环地瞎跑,错误会一轮轮累积、放大。三种验证手段,可靠性从高到低:

1. 定义规则(defined rules) — 最好的反馈。比如代码 lint、类型检查、测试通过与否。规则是确定的、廉价的、不会撒谎的。能上规则就上规则。
2. 视觉反馈(visual feedback) — 截图/渲染结果,让模型自己看布局、样式、层级、响应式对不对。适合规则难以描述的视觉任务。
3. LLM as a judge — 用另一个模型按”模糊标准”打分。最灵活,但文档也点明它”less robust”且有延迟成本。是兜底,不是首选。

这个排序本身就是设计哲学:能用确定性手段验证,就绝不用概率性手段。 一个智能体系统的可靠性上限,往往由”它能不能廉价地验证自己”决定。

治理一个自主循环:权限、hooks 与会话

一旦你接受”循环归模型”,马上冒出一个问题:那我怎么信得过它? 它可能 rm -rf、可能改不该改的文件、可能调不该调的接口。Agent SDK 的答案是一套控制平面。

权限(permissions)与权限模式。 你通过 allowed_tools 精确规定它能碰哪些工具——一个只读分析智能体,给它 Read / Glob / Grep 就够,它连改文件的能力都没有。还有 permission_mode(如 acceptEdits 自动批准编辑),在”每步都问”和”完全放手”之间给出档位。最小权限原则在这里是一等公民。

hooks:生命周期拦截点。 PreToolUse / PostToolUse / Stop / SessionStart / UserPromptSubmit 等钩子,让你在循环的关键节点插入自己的代码去校验、记录、阻断、改写智能体的行为。比如用 PostToolUse 匹配 Edit|Write,把每次文件改动写进审计日志。注意 hooks 是回调函数——不是让模型自觉,而是 harness 强制执行的确定性逻辑。这跟前面”能确定就别概率”的哲学一脉相承:治理必须是硬约束,不能靠模型自律。

会话(sessions):把状态外化。 模型本身是无状态的,但智能体需要跨多轮记住”读过哪些文件、做过哪些分析”。SDK 把会话状态以 JSONL 落在你的文件系统上,支持 resume(带完整上下文续接)和 fork(分叉去探索不同方案)。状态外化到磁盘,而不是憋在进程内存里——这既是持久化,也呼应了”文件系统即记忆”那条主线。

一条控制权谱系:你到底交出了什么

把 Agent SDK 放到 Claude 的工具矩阵里看,会更清楚它的定位。我把它理解成一条”控制权交出程度”的谱系:

	你拥有什么	你交出什么
Client SDK	自己写 tool loop、自己执行工具	只借用模型的单次推理
Agent SDK	循环归框架、工具内建;但跑在你自己的进程和基础设施上	交出了”循环控制权”,保留了”运行环境”
Managed Agents	一个托管 REST API	连进程和 sandbox 都交给 Anthropic 托管

从左到右,你交出的控制越来越多,换来的省心也越来越多:

• Client SDK:最大控制,最大工作量。tool loop、上下文管理全你自己扛。
• Agent SDK:一个库,agent loop 跑在你的进程里,直接操作你机器上的文件和服务。适合本地原型、CI/CD、需要贴着自己基础设施跑的自定义应用。
• Managed Agents:Anthropic 帮你把进程和沙箱都运维了,你的应用只管发事件、收流式结果。适合不想自己运维 sandbox 和会话基础设施的生产场景。

官方推荐的常见路径是:先用 Agent SDK 本地原型,成熟后迁到 Managed Agents 上生产。 选型的本质就是一句话:你愿意为了省心,交出多少控制权。

收尾:几条给工程师的启示

把这套设计哲学收拢一下,我拿走的是这么几条:

1. 可靠性工程发生在 harness,不在模型。 模型是给定的天花板,你能施工的是它的外壳——上下文、工具、权限、验证。别老想着”换个更强的模型”,先问”我的 harness 给够结构了吗”。
2. 上下文窗口是预算,不是无限资源。 外部记忆、检索策略、子智能体隔离、压缩,都是在管这个预算。设计智能体前先问:这一步,模型真的需要看到这些东西吗?
3. 先 agentic,再优化。 别一上来就上向量库、上重基建。先让模型用通用工具(grep/glob/bash)把事情跑通,透明、可调试;确有性能瓶颈再谈语义检索。
4. 能自检才能自主。 一个不能验证自己的智能体不配放手。上线前先问:它做完这件事,有没有一个廉价、确定的方式判断做对了?
5. 治理靠硬约束,不靠自律。 权限和 hooks 是 harness 强制执行的确定性逻辑,不是指望模型”懂事”。自主的前提是可控。

Agent SDK 表面是个”让 Claude 帮你干活的库”,内核其实是一份关于如何把不确定的模型,套进一个可控、可验证、上下文预算清晰的循环里的工程答卷。看懂这份答卷,比会调它的 API 值钱得多。

---

参考:Claude Agent SDK 官方文档(code.claude.com/docs)、Anthropic 工程博客《Building agents with the Claude Agent SDK》。文中英文原句均引自官方材料。