第 4 章 · 01 Agent 设计原则(agent-design)
第 4 章 · 01 Agent 设计原则(agent-design)
本节摘要:做出一个能干活的 Agent,核心不在代码量,而在三组设计决策:模型参数(adaptive thinking 与 effort 的取舍)、工具表面(tool surface)的设计(Bash vs 专用工具、何时该把一个动作提升为专用工具)、以及长程上下文管理(上下文编辑、压缩、记忆三件套)。本节讲清这些决策的启发式规则:从 Bash 起步广覆盖,在需要门控/渲染/审计/并行时提升为专用工具;用程序化工具调用(PTC)把多次往返压成一段脚本;用工具搜索与技能让固定上下文保持精简;用上下文编辑、压缩、记忆管理跑几小时的长程 agent。读完本节,你能设计出一个工具表面合理、上下文可控、成本可承受的 Claude agent。
内容来源:Anthropic 官方 Claude API 文档
shared/agent-design.md(随 Claude Code 分发,从泄露素材库提取),汉化并套用体系化模板。
学习目标
阅读完本节,你应当能够:
- 说清 adaptive thinking 与 effort 两个模型参数的作用与典型取值。
- 用「Bash 起步、需要时提升」的原则设计工具表面,判断一个动作何时该从 Bash 提升为专用工具。
- 列举 Anthropic 提供的六类官方工具(Bash/文本编辑器/computer use/代码执行/网页搜索/记忆)及其客户端侧 vs 服务端之分。
- 用程序化工具调用(PTC) 把多次顺序往返压成一段脚本。
- 在上下文编辑、压缩、记忆三种长程上下文模式中选对工具。
一、模型参数:思考深度与努力程度
设计 Agent 的第一组决策是模型参数。两个关键旋钮:
| 参数 | 何时用 | 效果 |
|---|---|---|
adaptive thinking(thinking: {type: "adaptive"}) |
想让 Claude 自己决定何时思考、思考多深 | 模型按请求难度决定思考深度,在工具调用间自动穿插思考,无需调预算 |
effort(output_config: {effort: ...}) |
调「彻底 vs 省 token」的权衡 | effort 越低,工具调用越少越合并、前导越短、确认越简;medium 常是好的平衡;正确性重于成本时用 max |
💡 经验法则:
mediumeffort 常是速度与彻底的有利平衡。只在正确性比成本更重要时(如安全审查、关键决策)才上max。adaptive thinking 则基本可以默认开——它让模型自己判断,不会在简单请求上浪费思考。
二、工具表面设计:Bash vs 专用工具
这是 Agent 设计最重要的决策。Claude 不知道你应用的安全边界、审批策略、UX 表面——它只发工具调用,你的外壳(harness)执行。工具调用的形状决定了外壳能做什么。
一个 Bash 工具给 Claude 极广的程序化能力——几乎能干任何事。但它给外壳的只是一个不透明的命令字符串,每个动作形状都一样。把一个动作提升为专用工具,外壳就获得了一个带类型参数的动作专属钩子,可以拦截、门控、渲染、审计。
何时该把一个动作提升为专用工具:
- 安全边界。需要门控的动作是天然候选。可逆性是有用判据:难以撤销的动作(外部 API 调用、发消息、删数据)应门控在用户确认之后。
send_email工具容易门控;bash -c "curl -X POST ..."则不行。 - 新鲜度检查。专用
edit工具能在文件自 Claude 上次读后已变时拒绝写入。Bash 无法强制这个不变量。 - 渲染。有些动作受益于自定义 UI。Claude Code 把「提问」提升为工具,这样能渲染成模态框、给出选项、阻塞 agent 循环直到回答。
- 调度。只读工具如
glob、grep可标记为并行安全。同样的动作走 Bash 时,外壳无法区分并行安全的grep与并行不安全的git push,只能串行化。
💡 经验法则:从 Bash 起步获取广度。在需要门控、渲染、审计、并行该动作时,提升为专用工具。
三、Anthropic 提供的六类官方工具
除了自定义工具,Anthropic 提供一组官方工具,分为客户端侧(你执行)与服务端(Anthropic 执行)两类:
| 工具 | 侧 | 何时用 | 效果 |
|---|---|---|---|
| Bash | 客户端 | 执行 shell 命令 | Claude 发命令,你的外壳执行;提供参考实现 |
| 文本编辑器 | 客户端 | 读写编辑文件 | Claude 经你的实现查看、创建、编辑文件 |
| computer use | 客户端或服务端 | 与 GUI、网页、可视界面交互 | Claude 截图并发鼠标键盘命令;可自托管或 Anthropic 托管 |
| 代码执行 | 服务端 | 在你不想管的沙箱里跑代码 | Anthropic 托管容器,内置文件与 bash 子工具,无需客户端执行 |
| 网页搜索/抓取 | 服务端 | 需要训练截止后的信息或某 URL 内容 | Claude 发查询/URL,Anthropic 执行并返回带引用的结果 |
| 记忆 | 客户端 | 跨会话保存上下文 | Claude 读写 /memories 目录,你实现存储后端 |
客户端侧工具由 Anthropic 定义(名字、schema、Claude 的使用模式)但由你的外壳执行,Anthropic 提供参考实现。服务端工具完全在 Anthropic 基础设施上运行——在 tools 里声明,Claude 处理其余。
四、程序化工具调用(PTC):压缩往返
标准工具调用下,每次工具调用都是一次往返:Claude 调工具 → 结果进上下文 → Claude 推理 → 调下一个工具。三个顺序动作(读档案 → 查订单 → 查库存)就是三次往返,每次都加延迟与 token,而中间数据大多再也不用。
程序化工具调用(Programmatic Tool Calling, PTC) 让 Claude 把这些调用组合成一段脚本。脚本在代码执行容器里跑——脚本调工具时,容器暂停、调用执行(客户端或服务端)、结果返回给运行中的代码(而非 Claude 的上下文)。脚本用正常控制流(循环、过滤、分支)处理结果,只有脚本最终输出返回 Claude。
| 何时用 PTC | 效果 |
|---|---|
| 多次顺序工具调用,或大中间结果想过滤后再进上下文 | Claude 写代码把工具当函数调;在代码执行容器跑;token 成本随最终输出而非中间结果缩放 |
💡 PTC 的价值:把「N 次往返 + N 份中间结果进上下文」压成「1 段脚本 + 1 份最终结果」。中间结果留在容器里不污染上下文窗口,既省 token 又降延迟。
五、扩展工具与指令集
当工具或指令多到放不进固定上下文时,有两个模式让细节按需加载:
| 特性 | 何时用 | 效果 |
|---|---|---|
| 工具搜索(tool search) | 工具很多但每次只有几个相关;不想把所有 schema 都放进上下文 | Claude 搜索工具集,只加载相关 schema;工具定义是追加而非替换,保留缓存 |
| 技能(skills) | 任务专属指令应只在相关时加载 | 每个 skill 是带 SKILL.md 的文件夹;skill 的描述默认在上下文,任务需要时才读完整文件 |
两者都让固定上下文保持精简,按需加载细节。技能在第 5 章会深入讲。
六、长程 Agent:管理上下文
跑几小时的长程 agent,上下文会膨胀到不可持续。三种模式各有用途:
| 模式 | 何时用 | 效果 |
|---|---|---|
| 上下文编辑(context editing) | 上下文跨多轮变陈旧(旧工具结果、已完成思考) | 按可配阈值清除工具结果与思考块;保持转录精简而不做摘要 |
| 压缩(compaction) | 对话可能达到或超过上下文窗口 | 早期上下文在服务端摘要成 compaction 块;关键是要回传整个 response.content |
| 记忆(memory) | 状态需跨会话持久(不只在一次对话内) | Claude 读写记忆目录里的文件;挺过进程重启 |
三者如何选:上下文编辑与压缩在会话内运作——编辑修剪陈旧回合,压缩在接近上限时摘要。记忆用于跨会话持久。许多长程 agent 三者并用。
七、缓存与 Agent:三个变通
提示缓存(第 2 章 03 节)的铁律对 agent 有特殊影响,有三个变通:
| 约束 | Agent 专属变通 |
|---|---|
| 会话中途改 system prompt 会失效缓存 | 改为追加 {"role": "system", ...} 消息到 messages(支持模型上,无需 beta 头);前缀保持不变 |
| 会话中途换模型会失效缓存 | 为子任务派生子代理(subagent) 用更便宜模型;主循环保持一个模型 |
| 会话中途增删工具会失效缓存 | 用工具搜索动态发现——它追加工具 schema 而非替换,保留前缀 |
本节要点回顾
- 模型参数:adaptive thinking 让模型自定思考深度(默认开);effort 调「彻底 vs 省 token」,
medium常是好平衡,正确性优先时用max。 - 工具表面核心决策:Bash 给广度,专用工具给门控/渲染/审计/并行能力;从 Bash 起步,需要这四者时提升。
- 提升专用工具的四信号:安全边界(难撤销动作门控)、新鲜度检查(改了拒绝)、渲染(自定义 UI)、调度(只读并行安全)。
- 六类官方工具:Bash/文本编辑器(computer use 客户端侧,你执行)、代码执行/网页搜索/记忆(部分服务端 Anthropic 执行)。
- PTC 压缩往返:多次顺序调用压成一段脚本,中间结果留容器不污染上下文,token 随最终输出缩放。
- 按需加载:工具搜索(追加不替换,保留缓存)、技能(描述默认在上下文,需要时读全文件)。
- 长程上下文三件套:上下文编辑(清陈旧)、压缩(接近上限摘要,回传整个 content)、记忆(跨会话持久);三者常并用。
- 缓存变通:中途改指令用
role:system消息、换模型用子代理、增删工具用工具搜索。
下一节讲托管代理(managed agents)——把这些 agent 设计原则交给 Anthropic 平台托管:agent 是版本化配置、session 是每次运行、平台替你跑有状态的 agent 循环。