目标：以官方文章 Building Effective Agents 为骨架，建立本仓库最核心的架构判断力之一——什么时候用工作流 (Workflow)、什么时候必须上智能体 (Agent)，并逐个掌握编排模式。前置：模块 04 的工具回路——agent 的全部「行动」都走那条回路，本模块只是把回路的控制权交给模型。
📘 重要英语词汇表
🎯 学习重点：必考的是区分「稳定的模式分类法」与「会随产品演进的具体工具」，引用时必须带来源日期。
本模块的骨架来自 Anthropic 工程博客 Building Effective Agents（2024-12 发表，Erik Schluntz & Barry Zhang）。截至 2026-08-30 核验：该文仍在官方现行参考位置，但页首已新增编者注——「文中描述的工具生态自 2024 年 12 月以来已发生很大变化，现行做法见 Managed Agents 工程文与其文档」（来源: https://www.anthropic.com/engineering/building-effective-agents（访问于 2026-08-30））。
这意味着两件事：
另一条必须记住的现行口径：Anthropic 后来的官方文章给过更简洁的 agent 定义——「LLMs autonomously using tools in a loop」（在循环中自主使用工具的 LLM）（来源: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents（访问于 2026-08-30）；同一定义也出现在多智能体系统一文中：https://www.anthropic.com/engineering/multi-agent-research-system（访问于 2026-08-30））。Agent SDK 文档则从产品角度定义：「agent 是通过规划自己的步骤并调用读写文件、执行命令、编辑代码的工具来完成任务的应用」（来源: https://code.claude.com/docs/en/agent-sdk/overview（访问于 2026-08-30））。
🎯 学习重点：高频判断只看控制流归属——预定义代码路径是 workflow，模型运行时决定路径才是 agent。
官方把两者统称为智能体系统，但给出一条清晰的架构分界（来源: Building Effective Agents，访问于 2026-08-30）：
- 工作流：LLM 和工具通过预定义的代码路径被编排的系统。 - 智能体：LLM 动态指挥自己的流程和工具使用、对「如何完成任务」保持控制的系统。
一句话抓住本质：「下一步做什么」由谁决定。Workflow 里，控制流是你写的代码（if/else、for 循环、DAG）；agent 里，控制流是模型在运行时自己生成的。这也解释了官方的另一句提醒：agentic 系统常用延迟和成本换取更好的任务表现，所以「值不值得换」永远是架构问题，不是技术炫技问题。
| 维度 | Workflow | Agent |
|---|---|---|
| 控制流 | 预定义代码路径 | 模型动态指挥 |
| 可预测性 | 高（路径可枚举、可测试） | 低（路径开放，同一输入可走不同路） |
| 延迟/成本 | 可预算（调用次数已知） | 开放式（多轮循环，成本上限靠停止条件兜底） |
| 适用 | 步骤可预先分解的明确任务 | 开放式问题，步数无法预测、无法硬编码路径 |
| 失败模式 | 单步失败，局部重试 | 错误复合：小错在多轮中滚雪球 |
| 测试 | 单元测试每步 | 需要 sandbox 环境中大量试跑 + guardrails |
（来源: Building Effective Agents「When (and when not) to use agents」，访问于 2026-08-30）
🧨 犀利细节｜成本上界必须由代码给出：固定工作流有N次模型调用时，单请求调用数上界就是N（不计显式重试）；agent 若只写「直到完成」则没有可计算上界。正解是同时设置最大迭代数、预算上限、超时和人工检查点，并以最先触发者终止；只在 prompt 里要求模型「节省调用」不是控制面。
🎯 学习重点：必背五要素 Goal–Reasoning–Planning–Action–Observation，并能说明停止条件为何属于应用层。
官方对 agent 运行方式的描述（来源: Building Effective Agents，访问于 2026-08-30）：agent 以人类指令或交互讨论开场；任务明确后独立规划并执行，必要时回到人类处索取信息或判断；执行中每一步都要从环境获取 ground truth（工具调用结果、代码执行结果）来评估进展；可以在检查点或遇到阻塞时暂停等待人类反馈；任务完成即终止，但通常还要配置停止条件（如最大迭代次数）来保持控制。
拆成五要素（考试友好版）：
| 要素 | 英文 | 干什么 |
|---|---|---|
| 目标 | Goal | 用户给的任务与成功标准 |
| 推理 | Reasoning | 理解输入、消化观察、评估当前状态（thinking 的用武之地） |
| 规划 | Planning | 把目标分解为下一步行动（选哪个工具、传什么参数） |
| 行动 | Action | 发出 tool_use，由应用执行（模块 04 的完整回路） |
| 观察 | Observation | 拿回 tool_result——环境的 ground truth，喂给下一轮推理 |
停止条件 至少要有：① 任务完成（模型判断 + 可验证的成功标准）；② 最大迭代次数/轮数上限（官方点名的例子）；③ 预算/成本上限；④ 人工检查点（不可逆操作前暂停）；⑤ 阻塞升级（连续失败 N 次转人工）。没有 ②③ 的 agent loop 是生产事故预备役。
与模块 04 的精确衔接：模块 04 的工具回路是「User → Claude → tool_use → 应用执行 → tool_result → Claude → 回答」。那是一个单圈回路，圈数由你的应用代码写死（while 循环几轮、每轮干什么，都是开发者定的）。Agent = 工具回路 + 控制权转移：还是那个回路，但「要不要再转一圈、下一圈调哪个工具、什么时候停」由模型在运行时决定。你的代码退到外层，只保留三样确定性职责：执行工具、权限门、停止条件——这三样永远不能交给模型（呼应模块 04 的判断：什么由 Claude 决定、什么由确定性代码决定）。
🧨 犀利细节｜重试也消耗迭代预算：工具超时、参数校验失败、权限拒绝都应作为 observation 回传，但不能因此绕过计数器。反模式是「成功调用才算一轮」，它会让持续失败的工具形成无限重试侧门；正解是每次模型决策/工具尝试均记账，连续同类失败达到阈值就升级人工。
🎯 学习重点：考试不只背模式名，更要用「步骤是否固定、子任务是否独立、评估标准是否清晰」完成选型。
官方的递进顺序：先给基础积木，再从简单组合式 workflow 走到自主 agent（来源: Building Effective Agents「Building blocks, workflows, and agents」，访问于 2026-08-30）。
🎯 学习重点：易错点是 augmented LLM 不等于 agent；接了检索、工具或记忆仍可能只是单次调用。
一切 agentic 系统的积木：LLM + 检索、工具、记忆等增强。现役模型能主动使用这些能力——自己生成搜索查询、自己选工具、自己决定保留什么信息。实现上关注两点：把增强能力裁剪到你的用例，并给模型易于使用、文档清晰的接口（BEA 提到 MCP 是集成第三方工具生态的一种方式——模块 06 主题）。
🎯 学习重点：类别边界清晰且可可靠分类时选 routing，并记住可按难度路由到不同成本模型。
定义：对输入分类，导向专门的后续任务（专用 prompt、工具集、甚至更便宜的模型）。价值：关注点分离——不为迁就一类输入而牺牲另一类。官方例：客服查询分类（普通咨询 / 退款 / 技术支持）走不同下游；简单常见问题路由给低成本模型、困难罕见问题路由给更强模型。适用信号：存在清晰类别、且分类可被准确执行（LLM 或传统分类器都行）。
🎯 学习重点：prompt chaining 的标准考法是固定顺序分解，并明确「用串行延迟换准确率」。
定义：任务分解为固定步骤序列，每次 LLM 调用处理上一步的输出；可在任意中间步加程序化检查——文中所谓 gate。核心交易：用延迟换准确率，每步都变成更简单的任务。官方例：生成营销文案→翻译成另一语言；先写文档大纲→校验大纲满足标准→按大纲写全文。
🧨 犀利细节｜链路尾延迟会累加：串行 k 步的端到端耗时近似为各步模型耗时、工具耗时与排队耗时之和；任一步重试都会继续放大尾延迟。正解是在 gate 处尽早失败、缓存可复用中间结果，并只把确有依赖的步骤串起来。
🎯 学习重点：必分清 sectioning（独立子任务）与 voting（同题多次尝试），聚合规则必须由代码定义。
定义：多个 LLM 同时工作，输出由程序聚合。两个变体：
官方例：guardrails 与主回答分两个实例并行（比同一调用又答又审更稳）；自动化 evals 每个调用评估一个维度；代码漏洞审查用多个不同 prompt 各审一遍再聚合投票。适用信号：子任务可并行提速，或需要多视角/多次尝试提高置信度。
🧨 犀利细节｜并行不等于免费提速：理想延迟受最慢分支约束，但 token 与请求数按分支数增加，还可能撞上速率限制；若分支之间共享可变状态或存在先后依赖，硬并行会制造竞态。先证明任务独立，再设并发上限、单分支超时和部分失败的聚合策略。
🎯 学习重点：高频适用条件是「清晰 rubric + 反馈确实能改进输出」，缺一不可。
定义：一个 LLM 调用生成回答，另一个在循环中评估并给反馈。适用信号：有清晰的评估标准，且迭代精修有可度量价值；两个好迹象——人类 articulated 的反馈能显著改进输出、且 LLM 自己能给出这种反馈（类比人类作者的反复修改）。官方例：文学翻译（评估器抓细微语感）；需要多轮搜索-分析的复杂检索任务（评估器判断是否还需要再搜）。
🎯 学习重点：易错点是该名称并非 BEA 官方五模式；用「计划是否中途动态改写」与 orchestrator-workers 区分。
BEA 的五种模式清单里没有单列这个术语——它是编排器-工人（3.6）的「先规划、后执行」显式化变体，也是业界通用叫法：一个 Planner 先产出任务分解/计划（往往一次性），Executor（可以是自己、另一 LLM 或确定性代码）照单执行，计划本身通常不再随观察动态改写。官方叙事里的对应物：Agent SDK 把「planning its own steps」直接写进 agent 定义（来源: https://code.claude.com/docs/en/agent-sdk/overview（访问于 2026-08-30））；Claude Code 的 plan-first 工作方式（模块 09 展开）。与 3.6 的关键差别：计划是静态契约还是随环境反馈动态再规划——考试用「计划是否可被中途修改」来区分。
🎯 学习重点：必考区分点是子任务集合由编排器按输入动态产生，而不是开发者预先枚举。
定义：中央 LLM（编排器）动态分解任务、委托给工人 LLM（workers）、再综合结果。与并行化的本质区别：子任务不是预定义的，由编排器按具体输入现场决定——灵活性与不可预测性同时上升。管理者-工人是同族叫法，BEA 官方词汇是 Orchestrator-Workers。官方例：需要改多个文件的编码产品（改哪些文件取决于任务）；跨多信源收集分析信息的搜索任务。Anthropic 自己的多智能体研究系统就自述采用 orchestrator-worker pattern：主 agent 分析查询、制定策略、生成并行 subagent 检索，再由主 agent 汇总（来源: https://www.anthropic.com/engineering/multi-agent-research-system（访问于 2026-08-30））。
🎯 学习重点：牢记官方量化结论 90.2%、4×/15× 与最多 90%，并能说明高收益来自规模化 token 与并行搜索。
多个 agent（各自「在循环中自主使用工具」）协同工作。官方实测结论（均来源: multi-agent research system 一文，访问于 2026-08-30）：
🧨 犀利细节｜先算单位价值再扩 agent 数：官方数据给出的约 15× chat token 是架构级成本信号，不是「多 agent 一定更聪明」的保证。反模式是为每个请求固定启动同样多的 subagent；正解是按问题复杂度动态分配投入，并让编排器在边际信息增益不足时停止扩展。
🎯 学习重点：必背 compaction、structured notes、subagents 三件套，以及 memory tool 的 client-side 与路径边界。
长时程任务超过上下文窗口时，官方工程文给出三件套（来源: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents（访问于 2026-08-30））：
产品化落点是平台 memory tool：{"type": "memory_20250818", "name": "memory"} 一行即可启用；Claude 在 /memories 目录下创建/读取/更新/删除文件，跨会话积累知识；client-side 执行——Claude 只发起请求，存储由你的应用控制（可映射到数据库/对象存储），必须做路径穿越防护（拒绝 /memories 之外的路径）；Claude 4 及以后模型可用（来源: https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool（访问于 2026-08-30））。设计哲学是及时上下文：平时只维护轻量标识符（文件路径、查询、链接），运行时按需加载，而不是预先把一切塞进窗口。
🎯 学习重点：掌握 Messages API 与 Managed Agents 的控制权取舍，并记住 session 不等于 context window。
较新源（双源并记）：官方托管服务 Claude Managed Agents（beta，header managed-agents-2026-04-01）——你不自建 agent loop / 工具执行 / 运行时，官方提供 harness 与基础设施（内置 bash、文件操作、web search/fetch、MCP），适合长时程异步任务；核心概念 Agent / Environment / Session / Events（来源: https://platform.claude.com/docs/en/managed-agents/overview（访问于 2026-08-30））。其工程文展示了 2026 年官方对 agent 系统的架构观：把 agent 虚拟化为 session（只追加事件日志——明确说「session 不是 Claude 的上下文窗口」）、harness（调 Claude 并路由工具调用的循环）、sandbox（执行环境）三个可独立替换的接口；「大脑」与「手」解耦后，容器从 pet 变 cattle，TTFT p50 降约 60%、p95 降超 90%；安全上凭证永远不可从 sandbox 触达（git token 在沙箱初始化时注入 remote；MCP 凭证存 vault、经代理调用）（来源: https://www.anthropic.com/engineering/managed-agents（访问于 2026-08-30））。官方选型口径：Messages API = 自定义 agent loop、细粒度控制；Managed Agents = 长时程/异步、不想自建基础设施。
🎯 学习重点：场景题先走「单次调用 → workflow → agent → multi-agent」复杂度阶梯，只有可度量收益才升级。
官方决策阶梯（来源: Building Effective Agents「When (and when not) to use agents」，访问于 2026-08-30）：
一张速查表（综合 BEA 各模式「When to use」）：
| 你的情况 | 选 |
|---|---|
| 单步任务，一次调用+检索/示例即可 | 单次调用（augmented LLM），不编排 |
| 输入有清晰类别，各类处理方式不同 | Routing |
| 任务能干净地分解成固定顺序的子任务 | Prompt chaining |
| 子任务独立可并行 / 需要多视角投票 | Parallelization |
| 有清晰评估标准 + 迭代精修有可测收益 | Evaluator-optimizer |
| 子任务不可预知，需现场分解再综合 | Orchestrator-workers（步骤仍可枚举时偏 workflow 侧） |
| 开放式问题、步数不可预测、路径无法硬编码 | Agent |
| 开放式 + 可高度并行 + 信息量超单窗口 + 任务价值高 | Multi-agent（orchestrator-worker） |
| 长时程/异步，不想自建 loop 与沙箱 | Managed Agents（beta，较新源） |
反模式：为了「agentic」而 agentic。官方点名批评的两种姿势：① 复杂度没有换来可度量的结果改善就加多步 agentic 系统——BEA 原话是「只在能证明改善结果时才增加复杂度」；② 用框架的抽象层把底层 prompt 和响应藏起来，导致难调试、还诱使你加不必要的复杂度。官方建议直接用 API 起步——许多模式几行代码就能实现；用框架则必须理解底层代码，「对黑盒的错误假设是客户错误的常见来源」。反向反模式同样存在：任务明明开放式（如跨多信源研究）却硬编固定 pipeline，结果是路径覆盖不全、维护地狱。
🎯 学习重点：高频反模式是全流量上开放式 agent；正解通常是 routing 分层，仅把长尾开放任务升级。
案例 A：客服系统。
案例 B：跨 50 个信源的行业研究报告。
案例 C：内部文档问答（检索即答）。
🎯 学习重点：必须能同时比较灵活性、可预测性、成本、尾延迟、错误复合与托管边界。
| 权衡轴 | 一端 | 另一端 | 架构师动作 |
|---|---|---|---|
| 灵活性 vs 可预测性 | Agent 开放路径 | Workflow 固定路径 | 用「步数可否预判」定分界 |
| 成本 | chat ≈ 1× | agent ≈ 4×、multi-agent ≈ 15× token | 停止条件 + 预算上限 + 按价值定价场景 |
| 延迟 | 并行化（耗时≈最慢子任务） | 串行链（耗时=各步之和） | chaining 是拿延迟换准确率 |
| 错误行为 | 单步错→局部重试 | agent 错误复合滚雪球 | sandbox 大量试跑 + guardrails + 人审检查点 |
| 自建 vs 托管 | Messages API 细粒度控制 | Managed Agents 免建 loop/沙箱 | 按团队基建能力与合规要求（托管暂不适用 ZDR/BAA） |
| 记忆策略 | 预载全部上下文 | JIT 按需加载 + memory tool | context rot 下窗口是有限资源，取高信号最小集 |
（数据来源: Building Effective Agents、multi-agent research system、managed-agents overview/工程文、effective context engineering，均访问于 2026-08-30）
🧨 犀利细节｜预算按最坏路径而非平均路径：平均调用次数会掩盖长尾失控。容量规划至少同时看每请求最大迭代数、并发 worker 数、每轮工具/模型超时与 token 预算；SLO 看 P95/P99 时，不能拿「多数请求两轮结束」替代硬上限。
🎯 学习重点：易错题集中在无停止条件、模式过度设计、上下文滥塞、框架黑盒与模型层伪安全边界。
🎯 学习重点：见英文能立即说出控制流含义、适用条件与一个反模式，而不只会中文翻译。
考试与官方文档高频短语，务必见词知义：
🎯 学习重点：认证题通常以场景选型考控制流归属、停止条件、模式边界和成本延迟权衡。
本模块对齐 Claude 认证（CCAR-F / CCAR-P 等）中 agentic 系统设计域的典型考点（域框架见 00-certification-current-status/，此处只讲能力映射、不涉考题）：
备考建议：把 §1 对照表、§4 速查表和 §6 tradeoffs 表背成条件反射；场景题先问自己「步数可否预判？成功标准可否验证？错误成本多大？」三连。
🎯 学习重点：把模块 04 的工具回路视为执行底座，把模块 09/10 视为 harness 与生产治理的落地层。
本模块示例见 examples/（3 个脚本，均无 key 可跑）；实验见 labs/lab.md；自测见 questions/。