《Building Effective Agents》精读

它替你干掉什么：把「要不要上 agent」从口水仗变成事实之争

原文（Erik Schluntz / Barry Zhang，2024-12-19）：

Workflows are systems where LLMs and tools are orchestrated
through predefined code paths.

Agents are systems where LLMs dynamically direct their own
processes and tool usage, maintaining control over how they
accomplish tasks.

分界线落在一个当场就能回答的问题上：下一步调哪个工具，是你的代码决定的，还是模型决定的。代码决定 → workflow，无论它套了多少层；模型决定 → agent，哪怕它只有二十行。画得再花的流程图也可能是 workflow，一个 while 循环也可能是 agent。

配套代码：官方那五个 notebook

光读会以为自己懂了。参考实现在官方 cookbook 里——注意仓库已从 anthropic-cookbook 改名为 claude-cookbooks（老链接会跳转，目录路径没变）：

git clone https://github.com/anthropics/claude-cookbooks
cd claude-cookbooks/patterns/agents

basic_workflows.ipynb               # 链式 / 路由 / 并行三件套
evaluator_optimizer.ipynb           # 评估-优化循环
orchestrator_workers.ipynb          # 编排者-工人
async_multi_agent_orchestration.ipynb
latency_multi_agent.ipynb           # 有延迟与预算约束的多 agent
util.py  prompts/                   # 共用工具与提示词

每个 notebook 都是不依赖任何框架的裸实现，这正是文章的态度：many patterns can be implemented in a few lines of code。什么时候别看：你要的是生产级重试、观测、持久化——这些一样都没有，它们是教具不是底座。（据 GitHub 仓库页 53.1k★，2026-09）

第一条立刻能跑的：把最后那一档跑起来

五种模式里只有末档需要真正的 agent 循环，而这一档现在有官方现成的：

npm install @anthropic-ai/claude-agent-sdk   # Node 18+
pip install claude-agent-sdk                 # 或 Python 3.10+
export ANTHROPIC_API_KEY=your-api-key

from claude_agent_sdk import query, ClaudeAgentOptions

async for m in query(
    prompt="Review utils.py for bugs that would crash. Fix them.",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Glob"],
        permission_mode="acceptEdits")):
    print(m)

这段抄自官方 quickstart。它替你干掉的是自己写 agent 循环：工具调用、上下文管理、重试、权限门都在库里。什么时候别装：任务是固定三步、每步都能预测——按文章的判据你要的是链式调用，直接调 API 写三次就行，别拖进一整个 harness。另注意 v0.1.0 起默认不再带 Claude Code 的系统提示词，要老行为得显式写 {"type":"preset","preset":"claude_code"}。

机制：五种模式不是并列的菜单，是一根梯子

梯子的地基叫 augmented LLM：an LLM enhanced with augmentations such as retrieval, tools, and memory。五种模式全建在它上面，区别只在谁来编排它。

上面那几档在 claude-cookbooks/patterns/agents/ 里一一对得上：①②③ 全在 basic_workflows.ipynb，④ 在 orchestrator_workers.ipynb，⑤ 在 evaluator_optimizer.ipynb，⑥ 没有单独的 notebook——因为它就是 claude-agent-sdk 那个 query() 循环本身。文章给每一档的适用条件都是一句能直接拿去开会的话：

• ① 链式 — the task can be easily and cleanly decomposed into fixed subtasks。关键词是 fixed：能画出流程图就用它。
• ② 路由 — distinct categories that are better handled separately。客服分流、难易分模型都在这。
• ③ 并行 — 两个变体别混：sectioning 拆成互不依赖的子任务同时跑，买的是速度；voting 同一任务跑多次取共识，买的是置信度。
• ④ 编排者-工人 — complex tasks where you can't predict the subtasks needed。和 ③ 的分界就在这句：子任务清单是预先写死还是当场生成。
• ⑤ 评估-优化 — when we have clear evaluation criteria, and when iterative refinement provides measurable value。没有清晰评判标准别上，否则只是两个模型互相恭维。
• ⑥ agents — open-ended problems where it's difficult or impossible to predict the required number of steps。代价文章也直说：higher costs, and the potential for compounding errors。

文章自己的收口是三条原则，值得当 checklist 贴墙上：simplicity（设计保持简单）、transparency（显式展示 agent 的规划步骤）、ACI（像打磨 API 文档一样打磨工具文档与测试）。第三条是它最被低估的一条，下一节就是它的操作手册。

真实用法与边界：拿这篇 2024 年的文章去对三份后续材料的账

① 多 agent 到底贵多少

官方 2025-06-13 的 How we built our multi-agent research system 把 ⑥ 这一档的账摊开算了：Opus 4 当 lead、Sonnet 4 当 subagent 的多 agent 系统，在其内部研究评测上比单个 Opus 4 高出 90.2%；代价是 agent 约烧掉聊天的 4 倍 token，多 agent 系统约 15 倍；并行工具调用把复杂查询耗时砍掉最多 90%。同一篇也划了边界：需要所有 agent 共享同一份上下文、或子任务之间强依赖的领域不适合，原文点名 most coding tasks involve fewer truly parallelizable tasks than research。什么时候别上：任务价值撑不起那 15 倍 token 的时候。

② 附录二的现代版

原文附录二叫「Prompt Engineering your Tools」，2025-09-11 的 Writing effective tools for AI agents 是它长大后的样子，也是 ACI 那条原则唯一的操作手册：合并工具（别给 list_users/list_events/create_event 三个，给一个 schedule_event）、命名空间（asana_search / jira_search 划清边界）、省 token 的返回（Claude Code 默认把工具返回卡在 25,000 token，自己做分页/过滤/截断）、只返高信号字段（给 name 和 file_type，别给 uuid 和 mime_type）、先写 eval 再调描述。

③ 2024 年那篇基本没讲的那一半

2025-09-29 的 Effective context engineering for AI agents 补上了盲区——上下文不是无限的。四个手法：compaction（接近上限时压缩历史）、结构化笔记（进度写进 NOTES.md 这类外部记忆）、子 agent 架构（在干净上下文里干活，只回摘要）、即时检索（存轻量标识符，用到再取）。一句总纲：找到 the smallest possible set of high-signal tokens。

④ 框架名单：这是一篇活文档

今天打开原文，「When and how to use frameworks」那节点名的是 Claude Agent SDK、Strands Agents SDK by AWS、Rivet、Vellum——而 Claude Agent SDK 这个名字是从 claude-code-sdk 改来的，2024-12 发表当天并不存在。别把旧笔记当现状。两个可装的：

pip install strands-harness      # 或 npm i @strands-agents/harness
pip install -U langgraph

strands-agents/harness-sdk 主打「any model, any cloud」的 harness 自控（据 GitHub 仓库页 8.5k★，2026-09）；langchain-ai/langgraph 是有状态 agent 的低层编排框架（据 GitHub 仓库页 42.5k★，2026-09）。什么时候两个都别装：文章原话是先直接用 LLM API，因为框架会 create extra layers of abstraction that can obscure the underlying prompts and responses, making them harder to debug——你连自己发出去的 prompt 长什么样都看不见时，任何调优都是玄学。

代价与替代品：这篇文章最大的代价，是被当成地图

1. 术语漂移。cookbook 仓库改了名、SDK 改了名、框架名单换了人。凡是你从这篇文章里抄走的专有名词都得去一手源核一遍；抄走的判据可以直接用。
2. 它不谈上下文。2024 年那会儿 context window 还不是设计约束的主角。只读这篇就去做 ⑥，你会在第三十轮工具调用上撞墙。
3. 「90.2%」最容易被当成通用结论。那是研究类任务上的内部评测，同一篇紧接着就说编码任务可并行的部分远比研究少。
4. 它的简单主义容易被念反。「保持简单」不等于「别上 agent」，而是「别在没量到收益前上」。

不上 agent，你还能怎么办：四个台阶

1. 一条好 prompt。文章的第一条建议就是先把单次调用优化到位，必要时配上检索和样例。
2. 链式三次调用。二十行代码，可调试、可断点、成本可预测。
3. 一个 skill 或一份 CLAUDE.md。要的只是「每次都按这套方法做」——那是 Skill 6 的活，不需要 agent 循环。
4. 一条 hook。要的是「每次都一定发生」——那是上期的活，连模型判断都不需要。