选择 Agentic 架构：决策驱动速成课

一门关于模式选择的概念速成课：什么时候使用顺序工作流、单 agent + ReAct + 工具、规划 + ReAct 执行，或多 agent 专家系统（4 种核心模式），以及什么时候在任一核心模式上叠加 reflection。目标读者是已经交付过 agent、需要按原则选择架构而不是按「看起来高级」来选择的工程师。

22 个概念 • 5 个决策 • 4 条学习路径。Reader 路径：2-3 小时纯概念阅读（决策树、5 种模式、失败信号，不需要环境设置）。Beginner / Intermediate / Advanced 路径：约 1 天、2-3 天、4-5 天（概念阅读，再逐步深入真实任务分类、部署拓扑草图，以及每种模式专属的评测信号接线）。诚实估计：Reader 路径 2-3 小时；一个团队要把模式选择内化成工作纪律，需要 4-5 天。进入第 5 部分的决策实验室前，先选择你的路径。

锚点文章：Bala Priya C, "Choosing the Right Agentic Design Pattern: A Decision-Tree Approach," Machine Learning Mastery, May 15, 2026：machinelearningmastery.com/choosing-the-right-agentic-design-pattern-a-decision-tree-approach。本课程的决策树以她的文章为主轴。本课程额外加入的是组合层：每种模式对你的部署拓扑和评测套件意味着什么。

---

白话版（先读这里）

你已经构建过 agent。也许是 Digital FTE 课程里 Maya 构建的客户支持 Worker，也许是 eval-driven 课程里的 evaluation agent，也许是你在 cloud deployment 课程中一路推到生产环境的 Tier-1 Support agent。现在你已经会构建 agent。 但你还不一定能有原则地决定：下一次到底该构建哪一种 agent。

生产环境中的 AI 有一种真实失败模式：工程师会选择看起来最厉害的模式，通常是多 agent，即使任务其实只需要顺序工作流，甚至 5 个步骤里有 3 个根本不需要 LLM。一个单 agent 加 2 个工具一天就能处理的问题，结果花几周做编排。相反的失败模式同样真实：任务确实需要拆给不同专家时，工程师却把它硬塞进一个带超长系统提示词的单 agent，最后 agent 被不适合单一心智模型的上下文压垮。

模式选择是在构建前发生的设计工作。 它问的是：「这个 agent 系统到底应该是什么形状？」答案可以有原则地得到：对任务提出 5 个问题，答案会映射到 5 种起始模式之一。本课程会讲这 5 个问题、5 种模式、说明模式选错的失败信号，以及真正上线时最重要的部分：每种模式对部署拓扑和评测套件意味着什么。

这门纪律不是「永远选最简单的模式」。 它是「选择与任务真实需求匹配的最简单模式；只有当你能说清楚哪个具体任务属性需要复杂度时，才增加复杂度」。多 agent 系统只有在专业分工或规模造成真实瓶颈时才是正确答案，不是因为它在幻灯片上看起来更高级。

这门课故意比 eval-driven 课程和 cloud deployment 课程短。决策逻辑框架本来就很紧凑；如果用每种模式的历史综述来填充，只会稀释这门纪律。紧凑是特性，不是缺陷。

📖 如果你还没有学过 Agent Factory 路线中前面的课程

本课程会交叉引用 operational envelope (Inngest)、eval discipline 和一次云部署，并把前面课程中的「Maya 的 Tier-1 Support agent」作为贯穿示例。即使没有读过那些课程，你也完全可以使用本课程。 5 问决策树、5 种模式，以及失败信号纪律本身就是一个可迁移框架。

如果没有前置课程背景，第一遍可以按这个顺序聚焦阅读：

• 第 1 部分（模式选择问题）：建立这门纪律
• 第 2 部分（5 问决策树）：概念主轴
• 第 3 部分的模式，但第一遍略读 operational-envelope 边栏
• 第 4 部分（失败信号与修正）
• 第 5 部分（决策实验室）：即使没有 Maya 的上下文，5 个 worked examples 也能落地
• 第 7 部分结语

第一遍可以当成预览或可选内容的部分：

• 概念 8.5（SDK 原语）：如果你使用 OpenAI Agents SDK 很有用；如果你使用其他框架，可以略读，因为底层模式形状会迁移
• 概念 8.6（带 Inngest 的 operational envelope）：如果你在交付生产级 agentic 系统很有用；如果你还处在只做设计的阶段，可以略读。「越复杂的模式需要越多运维机械结构」这个论点不依赖 Inngest
• 第 3 部分的部署组合边栏：如果你使用同一套云栈很有用；一般原则（哪些模式需要 sandbox、哪些不需要）会迁移到任何云部署

把这些交叉引用当成一般原则的具体例子，而不是准入门槛。这个框架不依赖它们也能工作。

平台映射表：每个 Agent Factory 选择对应什么

如果你使用不同技术栈，这张表会把每个 Agent Factory 引用映射到常见替代方案。决策树、5 种模式、失败信号和反模式图库在这些平台上完全相同；变化的只是原语名称。

打开平台映射表（如果你使用 Agent Factory stack，可以跳过）。

Agent Factory reference（本文使用的技术栈）	2026 年常见替代方案	这一层负责什么
Inngest（operational envelope）	Temporal, Restate, Dapr Workflows, AWS Step Functions, Azure Durable Functions, LangGraph (partial; durable execution via checkpointers)	触发器、持久执行、流量控制、HITL gate
OpenAI Agents SDK（agent engine）	LangGraph, AutoGen, CrewAI, AWS Strands, Pydantic AI, LlamaIndex Workflows	agent 循环、工具路由、多 agent 组合、结构化输出
Phoenix / Arize（trace observability）	Langfuse, Helicone, LangSmith, Logfire, Honeycomb, Datadog APM	单条 trace 的 agent 行为可观测性，以及 trace-to-eval 流水线
Azure Container Apps（harness runtime）	AWS Fargate, Google Cloud Run, Fly.io, Railway, Render, Kubernetes (any cloud)	长时间运行的 HTTP 服务宿主、自动扩缩、密钥、入口
Neon Postgres（durable state）	Supabase, AWS RDS Postgres, PlanetScale, CockroachDB, Google Cloud SQL	会话、运行、trace、审计日志：持久 agent 状态
Cloudflare R2（file storage）	AWS S3, Google Cloud Storage, Azure Blob, Backblaze B2	输入、输出、知识产物；供 sandbox 使用的预签名 URL 访问
Cloudflare Sandbox（code execution）	E2B, Modal, Daytona, Vercel Sandbox, Fly.io Machines, Cloudflare Containers	agent 生成代码的隔离工作区
@inngest_client.create_function（envelope primitive）	@workflow.defn (Temporal), state machine definition (Step Functions), StateGraph(...) (LangGraph)	注册持久函数单元
ctx.step.run(name, fn)（envelope primitive）	workflow.execute_activity() (Temporal), Task state (Step Functions), node in StateGraph (LangGraph)	重试时会 memoize 的持久 checkpoint
ctx.step.wait_for_event(...)（envelope primitive）	workflow.wait_condition() (Temporal), waitForTaskToken (Step Functions), interrupt() (LangGraph)	持久挂起，直到事件或超时；HITL 原语
Fan-out trigger（envelope primitive）	workflow.execute_child_workflow() parallel (Temporal), Map state (Step Functions), parallel edges (LangGraph)	一个 coordinator → N 个 specialist runs
Agent(...) + Runner.run()（SDK primitive）	Agent.execute() (LangGraph), Agent + initiate_chat() (AutoGen), Crew + kickoff() (CrewAI)	运行 agent 循环
@function_tool（SDK primitive）	@tool (LangGraph/LangChain), Tool(...) (AutoGen), Pydantic models in CrewAI	把 Python 函数暴露为 agent 工具
handoff(target_agent)（SDK primitive）	Command(goto=...) (LangGraph), nested chats (AutoGen), task delegation (CrewAI)	specialist 接管 conversation
Agent.as_tool()（SDK primitive）	Subgraph-as-node (LangGraph), nested agent calls (AutoGen), as_tool patterns in CrewAI	coordinator 把 specialist 当作工具使用
output_guardrail（SDK primitive）	Custom node + conditional edge (LangGraph), validator pattern (Pydantic AI), AWS Strands guardrails	对 agent 输出做 critique / validation pass

如何使用这张表。 当本课说「把 Runner.run() 包在 step.run 里」，而你使用 Temporal 加 LangGraph，就读作「把 Agent.execute() 包进 workflow.execute_activity()」。架构论点完全相同，语法不同。 需要避免的反模式是：不要为了读这门课而专门学习 Agent Factory 技术栈。映射原语，读取框架，然后应用到你的技术栈。

有一行不能干净映射：Agent.as_tool() 与 handoff()。 OpenAI Agents SDK 把「coordinator 保持控制」(as_tool) 和「specialist 接管」(handoff) 作为一等原语区分开。大多数其他框架要么合并这个区别，要么只实现其中一半。架构上重要的是这个区别本身；原语名称只是细节。 当你在自己的框架里选择 as_tool 风格还是 handoff 风格组合时，你做的就是本课命名的同一个架构选择；只是你的框架可能用不同方式暴露它。

---

术语表（读一次，需要时回来查）

点击展开完整术语表。

• Agentic design pattern。 AI agent 系统反复出现的一种架构形状：顺序工作流、ReAct + 工具、规划 + 执行、reflection、多 agent 专家。每种模式都对任务有特定假设；假设成立时，模式会产生价值；假设不成立时，模式会变成负担。
• Sequential workflow。 固定步骤流水线，每一步的输出进入下一步。solution path 事先已知；LLM 调用只用于解释或生成，不用于决定下一步做什么。示例：invoice intake → extract → validate → store → notify。
• ReAct (Reason + Act)。 一种 agentic 循环，agent 在推理当前状态和采取行动（通常是工具调用）之间交替，观察结果后继续重复。定义性特征：下一步行动在运行时决定，而不是提前指定。
• Planning agent。 在执行开始前产出显式计划（带依赖关系的阶段序列）的 agent。计划组织工作；单个步骤内部仍然可以使用 ReAct。示例：「research a market」→ 生成 5 步计划 → 用工具执行每一步。
• Reflection (self-critique)。 agent 生成输出后，根据明确标准进行 critique，并依据 critique 细化输出的模式。会增加延迟和成本；只有当标准可检查且错误代价高时才有价值。示例：带正确性检查的 SQL 生成。
• Multi-agent specialist system。 多个角色不同的 agent（researcher、writer、reviewer）协作完成任务，并由 routing agent 或 supervisor agent 协调的系统。它应由专业分工、上下文过载或并行执行需求来证明，而不是由审美来证明。
• Solution path。 解决任务的步骤序列。known path 表示这些步骤能在运行前指定；unknown path 表示步骤会从 agent 的调查中浮现。
• Task structure。 主要阶段及其依赖关系。articulable structure 表示执行前能描述这些阶段；emergent structure 表示阶段通过反馈才显现。
• Architectural fit。 一种模式的假设与任务真实属性之间的匹配。Pattern selection 是 fit-matching，不是 capability-matching：选择能力最强的模式是错误启发式。
• Coordination overhead。 在多个 agent 之间路由或协调 handoff 的成本，包括 token、延迟、调试复杂度和失败模式。多 agent 系统要支付这笔成本；它必须由 coordination 带来的收益来证明。
• Failure signal。 运行时症状，说明所选模式与任务不匹配。示例：ReAct 循环反复回到已解决工作（缺少结构）、planner 产出 execution 持续偏离的计划（过度结构化）、reflection 没有改善输出（标准含糊）。
• Pattern composition。 在一个更大系统的不同层使用不同模式。示例：顶层是 planning agent，每个计划步骤内部是 ReAct + 工具，最终综合上加 reflection。
• Agent (OpenAI Agents SDK)。 SDK 核心类：由 LLM 驱动的实体，通过 instructions= 定义，可选 tools=、可选用于结构化输出的 output_type=，以及可选 handoffs=。这是本课程所有模式的原子单元。
• Runner.run(agent, input) (OpenAI Agents SDK)。 运行 Agent 直到产生最终输出的 SDK 调用。SDK 在内部运行 reason-act-observe 循环：不需要手写循环。max_turns= 参数就是步骤预算。
• @function_tool (OpenAI Agents SDK)。 把 Python 函数变成 agent 可调用工具的装饰器。类型提示和 docstring 会自动成为工具的 JSON schema。
• handoff() (OpenAI Agents SDK)。 用于多 agent 转换的一等 SDK 原语：一个 agent 明确把 conversation 交给另一个 agent，SDK 保留上下文。当 specialist 需要接管面向用户的交互时使用。
• Agent.as_tool() (OpenAI Agents SDK)。 SDK 方法，把一个 Agent 包装成另一个 Agent 可以调用的工具。当 coordinator 需要保持控制并组合 specialist 输出时使用。
• output_guardrail (OpenAI Agents SDK)。 SDK 装饰器，把 validation / critique agent 接入另一个 agent 的输出路径。它是 SDK 原生的「阻止坏输出」式 reflection 原语；触发时会抛出 OutputGuardrailTripwireTriggered。
• Operational envelope (Inngest)。 运行时层，负责唤醒 agent function（triggers）、在中途崩溃时存活（通过 step.run 持久执行）、限制负载（concurrency、throttle、priority）并协调 HITL（step.wait_for_event）。它与你的云部署和 SDK engine 组合使用。在 operational-envelope 课程中讲解。
• @inngest_client.create_function (Inngest)。 把 Python async function 注册为 Inngest 持久执行单元的装饰器。声明触发表面和流控策略。
• ctx.step.run(name, fn, args) (Inngest)。 持久性 checkpoint。已完成步骤在重试时返回 memoized 输出；失败步骤独立指数退避重试。
• ctx.step.wait_for_event(...) (Inngest)。 持久挂起，直到匹配事件到达或超时触发。挂起期间消耗 0 compute。 这是 HITL gate 背后的运行时原语。
• Fan-out trigger pattern (Inngest)。 一个 coordinator function 发出 N 个事件；每个事件唤醒自己的 subscriber function。这是多 agent 系统中并行 specialist 执行背后的运行时原语。
• Replay (Inngest)。 失败运行带完整 trace 持久保存。发出修复，点击 replay；function 会用新代码从失败步骤恢复。成功步骤保持 memoized。

---

你准备好了吗？（前置要求）

1. 你已经构建过第一个 agent，或有等价经验。 本课讲的模式假设你理解 agent 循环是什么、工具调用是什么样子，以及模型如何返回结构化输出。如果你还没有构建过 agent，先完成 agent-building 课程。
2. 你至少构建过一个可工作的 agent。 无论它是 Maya 构建的客户支持 Worker、研究 agent、聊天机器人，还是 coding agent，你都需要有过一次架构选择（即使当时没意识到那是架构选择）并承受其后果的经验。
3. 你能读伪代码。 这是一门概念课，所以可执行代码很少。你会看到用于说明模式的伪代码；如果你能读 Python 或 TypeScript，就能读懂它。
4. （可选但强烈建议）你已经完成 eval 和 cloud deployment 课程。 本课程的主要贡献，是把模式选择与你的部署拓扑和评测套件组合起来。没有完成那些课程的读者仍然可以从框架中受益，但会错过集成层面的论证。

如果你缺第 4 项，仍然可以读这门课，把部署组合和评测组合边栏当成预览即可。框架本身不依赖它们。

先知道这些粗糙边界（诚实范围）

• 这是一门概念课，不是代码课。 它教你选择架构，而不是实现架构。实现纪律在前面的 Agent Factory 课程里。预计大约 30 页架构推理，加总约 5 页伪代码。
• 5 种模式并不穷尽现实。 现实中还有 graph-based agent systems、debate patterns、blackboard patterns、hierarchical task networks，以及本文未覆盖的其他形态。本课覆盖的是文章识别出的 5 种主导架构起点；截至 2026 年中，这 5 种覆盖了绝大多数生产级 agent 系统，但不是全部。
• 决策树是起点，不是最终答案。 真实 agent 架构会演化。一个以单 agent 加工具开始的系统，可能随着工作负载多样化成长为多 agent 系统；一个 planning-then-execution 系统，也可能随着路径更清晰而简化为顺序工作流。本课教的是起始决策，而不是演化全史。
• 成本和延迟是选择的一部分。 Reflection 增加延迟。多 agent 增加 token。Planning 增加额外 LLM 调用。本课程把这些成本当作真实约束；概念 18 会讲每种模式的开销什么时候合理。
• 文章是主轴；组合层是扩展。 Bala Priya C 的决策树是本课的结构骨架。本课增加文章没有覆盖的两层：（a）每种模式对部署拓扑意味着什么；（b）每种模式的失败模式在评测套件中是什么样子。如果你只读过那篇文章，本课程增加的是生产纪律层。

---

四条学习路径

Track	时间投入	你完成什么	适合谁
Reader（纯概念）	约 2-3 小时，无实验	完整概念弧线：第 1 部分（问题）、第 2 部分（决策树）、第 3 部分（5 种模式）、第 4 部分（失败信号）以及第 7 部分结语。没有分类练习，没有决策实验室。	工程负责人、平台架构师，或正在决定是否投入团队时间做系统化模式选择的好奇非工程读者。
Beginner	约 1 天	Reader 路径 + 决策实验室中的决策 1-2。用决策树分类两个任务（Maya 的 Tier-1 Support 和 incident-response agent）；在高层画出所选模式。	刚接触 agentic 架构、希望进行一轮有指导的模式选择练习的工程师。
Intermediate	约 2-3 天	Beginner 路径 + 决策 3-4。加入 research agent 和 enterprise onboarding agent；在你的云栈上画出部署拓扑；识别能捕捉每种模式失败模式的评测信号。	正在交付 agentic 系统、希望把模式选择与部署和评测组合起来的工程师。
Advanced	约 4-5 天	Intermediate 路径 + 决策 5 + 第 6、7 部分。加入 coding agent（最难案例）；探索模式组合（不同层的多个模式）；用完整纪律端到端架构一个假想 agent 系统。	希望把模式选择变成团队级纪律的高级工程师和技术负责人。

路径分叉建议。 工程负责人应从 Reader 路径开始。工程师默认选 Intermediate 路径；决策实验室才是框架真正内化的地方。不要因为第 2 部分读得快，就完全跳过第 5 部分。 框架只有应用到真实任务上才会留住。

🚀 最小可行路径：通往可用模式选择的最短路线。 读第 1 部分（问题）、第 2 部分（决策树），以及实验室中的决策 1（Maya 的 Tier-1 Support）。大约 90 分钟后，你就能用 5 个问题分类一个新任务并选择起始模式。其他内容会加深这门纪律；这是种子。

学完后你会得到什么（具体成果）

Reader 路径产出理解，不产出工件。你将能够解释为什么模式选择要在写代码前发生；描述 5 种模式及其典型任务假设；识别说明模式不匹配的 5 个常见失败信号。

Beginner / Intermediate / Advanced 路径会产出一套可工作的分类纪律：

• 能够对新任务走一遍 5 问决策树，并选择有原则的起始模式。
• 能够为每种模式在你的云栈上画出部署拓扑草图（顺序工作流需要哪些组件，多 agent 或 planning 系统需要哪些组件）。
• 能够把每种模式的常见失败模式映射到会捕捉它们的具体评测信号。
• 一个团队可共享的工件：一页「classify-this-task」模板，可用于设计评审。

---

TL;DR：本课程捍卫的四个主张

1. 模式选择是架构适配，不是能力匹配。 每种模式都对任务有假设。正确模式是其假设与任务真实属性匹配的那个，不是能力最多、结构最炫的那个。多 agent 并不「优于」顺序工作流；它只在专业分工或规模造成瓶颈的特定情形下更好。

   4 种核心模式 + 1 个叠加层。 决策树的 Q1-Q3 选择核心模式：顺序工作流、单 agent + ReAct + 工具、规划 + ReAct 执行，或多 agent 专家系统。Q4 决定是否把 reflection 作为叠加层加在所选核心之上。Reflection 不是第 5 个平级模式；它是包裹任一核心的质量控制层。 这个区别很重要：把 reflection 当作独立模式的学习者，会错过它必须与已有核心模式组合这一架构事实。

2. 关于任务的 5 个问题决定架构。 Q1-Q3 选择核心模式：solution path 是否已知？workflow 是否固定？task structure 是否可表达？Q4 决定是否在上面叠加 reflection：质量是否比速度重要且标准可检查？Q5 决定是否升级为多 agent：是否存在专业分工、上下文或规模瓶颈？答案会确定性地映射到一个起始架构。 文章说得对：文献缺少的是决策逻辑，而不是模式本身。

3. 模式选择会与部署拓扑和评测信号组合。 每种模式使用云栈的不同子集：顺序工作流不需要 sandbox 执行；多 agent 系统需要仔细的审计日志，因为 coordination failures 是最难处理的生产 bug。每种模式都有典型失败模式，你的评测套件要用不同方式捕捉。 很少有课程会教这个组合层，因为它需要部署和评测课程作为基础。

4. 决策树给出起点，不给出终局。 真实系统会演化。这门纪律不是「永远锁定架构」，而是「让起始决策有原则，观察失败信号，并让运行时证据引导演化」。模式选择是第一步；模式修订是持续动作。

你要学习的形状（一张图，后面反复回来）

这里先给出一棵决策树，后面的 22 个概念（19 个主概念，加上 8.5、8.6、16.5 这 3 个桥接概念）和 5 个决策都会围绕它组合。

这棵树的形状是：先问你是否真的需要一个 LLM 驱动的 agent（Q1-Q2）；如果需要，再问任务有多结构化（Q3）；然后只有在质量（Q4）和规模（Q5）创造真实价值时，才把它们叠加上去。每当某个概念或决策显得抽象时，回来看这张图。

---

第 1 部分：模式选择问题

概念 1：Pattern selection 是构建前的设计工作

大多数 agentic 系统课程会教你如何构建每种模式。本课程关注的是另一个问题：给定一个任务，你应该构建哪种模式？这个问题发生在构建之前，也应该发生在构建之前，但通常没人教，原因有点尴尬：每种模式的实现都有充分文档；在它们之间做选择的决策逻辑却没有。

模式目录已经成熟。ReAct 来自 2022 年的论文。Planning-then-execution 模式可以追溯到经典 AI 中的 STRIPS，并在 2023 年被 LLM 场景重新发现。Reflection 自 2023 年起已经被形式化。每个主流框架都会讲多 agent 架构。任何模式，你都能在 5 分钟内找到教程。你不容易找到的是：面对这个有这些具体约束的具体任务，哪种模式匹配？

这会制造的失败模式。 工程师会默认选择最近接触过的模式，或者演讲里看起来最厉害的模式。多 agent demo 尤其诱人，因为它们看起来像「真正的 AI」：agent 彼此交谈、分工、协调。团队为了一个单 agent 加 2 个定义良好的工具一天就能解决的问题，花几周搭编排。结果是：交付更慢、调试更难、token 成本比任务需要的更多。

相反的失败模式也真实存在，而且讨论更少。工程师会在任务确实需要结构拆解时选择「就用一个带很长系统提示词的单 agent」。agent 会被不适合单一心智模型的上下文压垮。工具调用错误级联。Reflection 成为团队唯一知道的修复方式，于是到处添加，现在每个响应都要 30 秒。他们交付了一个脆弱系统，而一个架构选择本来可以避免这一点。

本课程教授的纪律： 模式选择是架构适配匹配，不是能力匹配。不要问「最好的模式是什么？」（没有）。要问「这个任务实际需要什么，能够提供它的最小模式是什么？」第 2 部分的 5 问决策树就是系统回答这个问题的方法。

为什么这比过去更重要。 2023 年，agentic 系统还处于实验阶段。选错模式最多浪费一个周末。到 2026 年，agentic 系统已经在生产环境中服务真实用户；你选择的模式会决定部署拓扑、评测纪律和规模化运维成本。错误的模式选择现在会以复利形式变贵：按错误假设搭建的基础设施、针对错误失败模式编写的评测、响应错误事故的 runbook。模式选择已经从「偏好」变成了「高风险设计决策」。

结论：模式本身已有充分文档；如何在它们之间选择才是本课程填补的空白。模式选择是架构适配匹配，不是能力匹配。错误模式会在生产环境中昂贵地复合：错误基础设施、错误评测、错误 runbook。本课程教授能避免最常见模式选择失败的 5 问纪律。

概念 2：每种模式都对任务做出不同假设

让模式选择变得可处理的深层想法是：每种 agentic 模式都是一次关于任务形状的押注。当押注与现实匹配时，模式会增加价值。当押注错误时，模式会变成开销；有时是看不见、只是消耗 token 的开销，有时是会让系统彻底坏掉的灾难性开销。

下面是 5 种模式各自押注的事情：

顺序工作流押注：我提前知道步骤，而且每次都一样。 它押注 solution path 在运行前固定且可表达。如果为真，你不需要 LLM 来决定下一步做什么：workflow 自己知道。你只把 LLM 调用保留给真正需要解释的步骤（从文本中抽取这个，生成那个摘要）。成本可预测；延迟有界；失败模式明显。如果为假：如果步骤实际上会随输入内容变化，workflow 会强迫系统走错误路径，或直接失败。

单 agent + ReAct + 工具押注：我提前不知道路径；agent 会自己找出来。 它押注任务足够开放，下一步必须根据目前观察结果来决定。如果为真，ReAct 的循环（reason → act → observe → repeat）就是唯一能处理它的方法，任何预先确定的计划到第 3 步都可能错。如果为假：如果路径其实很稳定、可以写下来，ReAct 就会增加延迟、成本，以及 agent 循环或反复回到已解决工作的风险，却没有带来顺序工作流做不到的东西。

规划 + ReAct 执行押注：我能提前表达主要阶段和依赖，但每个阶段仍需要 adaptive reasoning。 它押注工作的形状已知（research → analyze → synthesize → report），但每个阶段的内容需要调查。如果为真，计划提供脚手架，防止 agent 漫游；每个阶段内部的 ReAct 处理不确定性。如果为假：如果计划实际上无法表达（用纯 ReAct），或每个阶段不需要 adaptive reasoning（用顺序工作流），计划就会变成开销，而且执行最终仍会偏离它。

Reflection 押注：输出质量比速度重要，而且质量可检查。 它押注 critique pass 能识别 generator 漏掉的缺陷，并且「好输出」的标准明确到 critique 有意义。如果为真，reflection 能通过抓住第一轮产生的错误（错误 SQL、薄弱法律论证、报告中的事实错误）来提高可靠性。如果为假：如果标准含糊，或 critic 与 generator 共享同样盲点，reflection 只会增加延迟和成本而不改善输出。更糟的是：它会制造「critique 已经验证了质量」的虚假信心，但实际上并没有验证。

多 agent 专家系统押注：没有任何单个 agent 具备足够专业能力、上下文或容量把这件事做好。 它押注任务确实能划分成专家角色（researcher + writer + reviewer；coder + security + docs），而且跨专家协调比把一切塞进一个 agent 更便宜。如果为真，specialist 在自己的领域会产出比 generalist 更好的结果，并行执行会提升吞吐量。如果为假：如果这些「specialist」大多在做同一件事，或协调开销主导了工作，你就增加了买不到价值的复杂度，并引入了新失败模式（路由错误、集成错误、责任不清）。

模式就是押注；任务的真实属性决定押注是否正确。 这就是为什么模式选择是 fit-matching。你不是在问「哪种模式最强大？」你是在问「哪种模式的押注最匹配我对这个任务的真实了解？」

结论：每种 agentic 模式都是关于任务的押注：顺序工作流押注已知固定路径，ReAct 押注未知自适应路径，planning 押注可表达结构，reflection 押注可检查质量标准，多 agent 押注真实专业分工需求。正确模式是押注与现实匹配的那个；模式选择是 fit-matching，不是 capability matching。

概念 3：两种失败模式：overshooting 与 undershooting

概念 2 已经说明每种模式都是一次押注。概念 3 命名这次押注出错的两种方式；在真实生产系统中，它们出现的频率大致相当。

Overshooting：选择了比任务需要更复杂的模式。 这是更出名的失败模式，也是演讲和 demo 最容易诱导你掉进去的那种。示例：

• 为一个单条 LinkedIn 帖子生成任务搭建 3 agent 系统（researcher、writer、reviewer）。「researcher」agent 的输出只有两段，随后还得由「writer」总结。reviewer 因为一个 self-checking prompt 就能抓住的问题拒绝 5% 输出。3 个 agent，3 倍成本，没有可测量的质量提升。
• 给一个其实是固定工作流的任务加 planning。planner 每次都产出同样的计划（因为任务相同）。每次运行都为无价值的额外 LLM 调用付费。更糟的是：当输入稍微不寻常时，planner 产出一个略有不同的计划，团队现在还得调试「为什么 planner 在这个输入上走了不同路径？」
• 给没有可检查标准的任务加 reflection。critic 和 generator 共享同一个模型、同一批训练数据，以及常常相同的盲点。reflection pass 要么直接盖章通过，要么生成冗长但不可操作的 critique。延迟翻倍；质量不变。

Overshooting 的失败模式是：你为任务不需要的能力付了钱，而且现在不容易撤掉，因为编排已经变成承重结构。 移除一个已经在生产环境运行 6 个月的多 agent 系统不是重构，而是重写。

Undershooting：选择了比任务真实需求更简单的模式。 这种失败模式很少出现在演讲里，因为它没那么戏剧化，但至少同样常见。示例：

• 用一个带 4,000 token 系统提示词的单 agent 处理 billing、technical、account 和 refund 等客户支持问题。agent 会把 billing 规则与 technical 规则混淆。Reflection 略有帮助，但修不了根因。任务真的需要 specialist routing；一个 agent hold 不住上下文。
• 对一个本该固定流水线处理的 workflow 使用 ReAct + 工具。agent 偶尔跳过步骤，偶尔回看已完成工作，偶尔编造不存在的工具调用。团队在提示词里加「stop conditions」和「progress criteria」，治疗症状而不是底层错配。成本方差变成 runbook 问题。
• 对确实需要验证的输出跳过 reflection。带细微错误的 SQL 查询进入生产环境。带引用错误的法律草稿发给客户。团队事后增加测试，但自然的错误捕捉位置本来是在生成时的 reflection pass。

Undershooting 的失败模式是：你交付了一个靠人工盯着或靠运气活着的脆弱系统。 生产环境会暴露缺口；补救要么是添加一开始就该使用的模式，要么是接受失败率作为业务成本。

为什么两种失败模式同样重要。 关于模式选择的讨论常聚焦 overshooting（因为它更显眼，就是没人能调试的多 agent 系统）。但 undershooting 同样常见，而且可以说更危险：它会产出看起来能工作、直到突然不工作的系统，失败模式也更微妙。一个只学会避免 overshooting 却识别不了 undershooting 的团队，只学会了一半纪律。

第 2 部分的决策树旨在暴露这两种失败模式。每个问题都询问一个任务属性（路径是否已知？结构是否可表达？质量是否可检查？）；如果答案不能证明更复杂的模式合理，树会路由到更简单的模式（防止 overshoot）。如果答案确实证明更复杂模式合理，树会明确路由到那里（通过让升级变得有意识来防止 undershoot）。

结论：模式选择有两种失败方式：overshooting（选择了比任务需要更复杂的模式，为没有帮助的能力付费）和 undershooting（选择了比任务需要更简单的模式，交付脆弱系统）。两者出现频率大致相当；演讲更常强调 overshooting，但 undershooting 至少同样危险，因为更隐蔽。第 2 部分的决策树通过询问任务属性而不是模式偏好来暴露这两种失败。

---

第 2 部分：5 问决策树

这一部分会逐题讲解决策树。每个概念覆盖 5 个问题中的一个：它测试什么、如何针对真实任务作答，以及答案会路由到哪种模式。读完第 2 部分，你就完整走过一遍决策树。

树的结构如下：

#	问题	它测试什么	路由到
Q1	solution path 能否提前定义？	流程是否能在运行前指定	如果能 → Q2（固定 workflow 检查）；如果不能 → 需要 adaptive reasoning，去 Q3
Q2	workflow 是否跨 runs 固定稳定？	同一组步骤是否每次都适用	如果是 → Sequential Workflow；如果不是 → 重新考虑 adaptive patterns
Q3	task structure 是否能在执行前表达？	主要阶段和依赖是否清楚	如果是 → Planning + ReAct execution；如果不是 → Single agent + ReAct + tools
Q4	quality 是否比 speed 更重要，且 criteria 可检查？	额外 critique / refinement pass 是否值得延迟和成本	如果是 → 在所选模式上加 Reflection layer；如果不是 → 跳过 reflection
Q5	是否存在 specialization、context 或 scale bottleneck？	一个 agent 是否缺少专业能力、上下文或并行容量	如果是 → Multi-Agent Specialist System；如果不是 → 保持 single agent

问题 1-3 决定核心模式。问题 4-5 是叠加层；它们可以应用在任一核心模式上，但只有在自身假设成立时才应用。

概念 4：Q1：solution path 能否提前定义？

这是最重要的问题，因为它决定你是否根本需要一个 agentic 系统。

「solution path」是什么意思。 具体说：如果我告诉你输入，你能不能告诉我产出输出的精确步骤序列？不是答案本身，而是路径。对于 invoice intake：接收邮件 → 抽取结构化字段 → 与数据库校验 → 存储 → 通知请求者。5 个步骤，每次都是同样 5 个步骤。 这就是已知 solution path。

对比一下：客户问「我为什么在 11 月 12 日被扣了两次款？」路径取决于你发现什么。先查交易历史。找到它。如果两笔扣款来自不同商户，就转向「这是不是 fraud？」如果是同一商户但时间戳不同，就转向「第二笔是不是 retry？」如果客户账户有多个用户，就转向「是否其他人购买了？」每个分支都会导向不同的下一步。路径无法提前指定；它从调查结果中浮现。 这就是未知 solution path。

如何诚实测试。 按顺序做 3 个测试：

1. 在看到输入前，你能否画出步骤流程图？ 如果能，路径已知。如果你的流程图需要「现在由 agent 决定下一步」这样的框，路径未知。
2. 这些步骤是否在多次运行中不变地重复？ Invoice intake 会重复。客户支持调查不会。研究报告的大纲可能每次都同形（引言、3 个小节、结论），但内容发现不是一个步骤序列；它是 adaptive search。
3. 输入变化时，步骤是否变化？ 已知路径会对不同输入产生同样的步骤序列。未知路径会根据每一步揭示的内容产生不同步骤序列。

团队常错在哪里。 最常见错误是因为任务描述听起来结构化，就相信路径已知。「处理退款请求」听起来已知：收到请求、查订单、退款、通知客户。真实退款请求不是这样。 有些需要 dispute investigation（这是不是 chargeback？），有些需要查 policy（这个客户的 plan 是否允许退款？），有些需要 escalation（金额超过 agent 权限），有些涉及多笔扣款需要消歧。4 步流程图是错的；真实路径是 adaptive 的。

镜像错误是：因为任务描述听起来开放，就相信路径未知。「今晚帮我在城里找一家好餐厅」听起来很 adaptive，但如果实际实现是：解析请求 → 用筛选条件查询餐厅数据库 → 按评分返回前 5 个，路径已知，顺序工作流才是正确模式。「agentic」的包装误导了你。

路由。 如果路径已知（并且稳定，见下一题 Q2），你正走向顺序工作流。你甚至可能不需要 LLM 驱动的 agent；你可能需要的是一个在特定步骤嵌入 LLM 调用用于解释或生成的 workflow。 如果路径未知，你需要 agentic reasoning；问题变成结构是否可表达（Q3，planning）或不可表达（Q3，纯 ReAct）。

一个有用启发式。 问自己：「如果我必须把它写成一个没有 LLM 调用的 Python 函数，我知道该如何组织它吗？」如果知道，路径大概率已知；LLM 只在特定推理或生成时刻需要。如果不知道，路径大概率未知；LLM 在做结构性决策，而不只是生成文本。

结论：Q1 问的是 solution path 是否能在运行前指定。已知路径路由到顺序工作流（Q2）；未知路径路由到 adaptive agentic reasoning（Q3）。最常见错误是任务描述听起来结构化、但实际实现是 adaptive 时误以为路径已知，例如退款处理、客户支持、调试。相反错误是实际是带 LLM 风味输入的 workflow，却误以为路径未知。用「没有 LLM 调用的 Python 函数」启发式测试。

概念 5：Q2：workflow 是否跨 runs 固定稳定？

你已经对 Q1 回答「是，路径已知」。Q2 是第二道检查：它在你真实预期的输入中是否固定且稳定？因为「已知」和「稳定」不是一回事。

区别。 一条路径可以原则上已知，但实践中会变化。考虑一个处理用户查询的「research assistant」agent。有时用户要快速答案（查一个事实并返回）。有时要多来源综合（搜索、比较、总结）。有时要分析上传的文档（读取、抽取 claims、评估）。你可以为每种情况写出路径，但路径会随输入类型变化。 这叫 known-but-variable，不是 known-and-stable。

相对地，invoice intake。每张发票都经过同样 5 个步骤。 路径稳定。每一步的内容会变化（不同 vendor、不同金额），但步骤结构不变。

为什么这重要。 顺序工作流假设稳定。如果你构建固定流水线，而路径会变化，那么流水线会为某些输入强迫错误路径：要么尝试应用不适用的步骤（quick-answer query 被完整 synthesis 流程处理），要么大声失败（document-analysis path 不适合 quick-answer step structure）。

测试。 看一组有代表性的真实输入（或仔细想象它们）。步骤序列在这些输入之间是否保持一致？

• 如果是，每个输入都经过同样步骤 → workflow 稳定；构建顺序工作流。
• 如果不是，不同输入需要不同步骤序列 → workflow 可变；你需要（a）显式分支 workflow 来处理每种变体，或（b）能根据输入自适应路径的 agentic 模式。

团队常错在哪里。 把「平均已知」当成「已知且稳定」。80% 情况是固定 workflow；20% 情况需要偏离。工程师为 80% 情况构建 workflow，再为 20% 添加 ad-hoc patch。最终 patch 支配了原始 workflow，你得到一个没人理解的未文档化混合体。 这种模式最常见于团队不愿承认任务比预期更 adaptive 时：顺序工作流感觉比 agentic 模式安全，于是他们过拟合。

路由。 如果 workflow 固定且稳定 → Sequential Workflow。到这条分支就停止。跳过问题 3，并且通常跳过问题 4。只有当规模迫使你跨 workflow instances 并行化时，才考虑 Q5。

如果 workflow 是 known-but-variable → 有两个选择：

1. 带显式分支的顺序工作流：把每种变体写成一个分支，并确定性地路由过去（通常用一个小 LLM 调用只做输入类型分类，然后路由）。适合变体很少且稳定的情况。
2. 把路径视作实际上未知：继续到 Q3，让 agentic reasoning 处理变化。适合变体很多或还在演化的情况。

务实启发式。 如果你用一只手就能列出所有变体，而且它们不常变化，就用分支 workflow。如果列不完，就用 agentic 模式。

结论：Q2 问的是已知路径是否也在预期输入中稳定。稳定路径路由到顺序工作流。Known-but-variable 路径要么路由到带显式分支的 workflow（少量稳定变体），要么路由到 agentic 模式（大量或演化中的变体）。陷阱是把「80% 情况固定」当成「固定」；20% 情况会长成支配原始设计的 patch。

概念 6：Q3：task structure 是否能在执行前表达？

你已经对 Q1 回答「路径未知」，需要 agentic reasoning。Q3 问下一件事：即使具体步骤未知，这项工作的高层结构是否能提前表达？

这里的「structure」是什么意思。 不是步骤本身；根据 Q1，步骤未知。这里指阶段及其依赖。示例：market research agent。你不能提前指定步骤（查哪些来源、研究哪些竞争对手、做哪些分析，取决于发现什么）。但你能表达结构：gather data → analyze → synthesize → report。4 个阶段，按这个顺序，依赖清楚。 这就是可表达结构。

对比一下：customer-support agent 处理「我遇到问题了」。agent 会调查。根据发现，工作可能需要 account lookup，然后 knowledge-base search，然后 policy check，然后 escalation；也可能这些都不需要，只是快速重定向。你无法表达阶段，因为这项工作不适合阶段结构；它是调查，完成时自然完成。这就是不可表达。

测试。 在看到任何具体输入前，试着把工作画成阶段图。你能否标出主要阶段及其依赖？

• 如果是，阶段清楚（gather → analyze → synthesize；或 design → implement → test；或 research → draft → review）→ 结构可表达；使用 planning。
• 如果不是，工作不适合阶段，它是调查、迭代或开放探索 → 结构不可表达；使用 ReAct。

团队常错在哪里。 发明不存在的结构。工程师会觉得计划总该可能，于是强行计划。planner 生成计划；执行马上偏离，因为任务其实没有那些阶段。团队随后要么（a）把偏离当成 planner 的 bug（「planner 产出了坏计划」；重写 planner；重复），要么（b）逐渐缩短计划，直到它变得平凡且毫无贡献。诚实答案本来是「这个任务不需要计划；用 ReAct」。

相反错误是：错过实际上存在的结构。工程师对确实有阶段的任务使用纯 ReAct。agent 会漫游、回看已解决工作，或失去整体进度感。把「记得做这些阶段」加进提示词只是 workaround；架构修复是在 ReAct 循环之上加 planning。

路由。 如果结构可表达 → Planning + ReAct execution。planning agent 产出阶段结构；ReAct 在每个阶段内部运行，以处理 Q1 识别出的未知步骤适应。

如果结构不可表达 → Single agent + ReAct + tools。agent 推理当前状态、采取下一步行动、观察结果并重复：除了 agent 自身维护的结构外，不再覆盖额外结构。

值得内化的启发式。 当工作的形状可预测但内容不可预测时，planning 有帮助。当连形状都取决于发现结果时，只用 ReAct 才正确。shape-vs-content 这个区别，是区分两者最干净的方法。

🔍 Q2 与 Q3 的混淆：用示例消歧

Q2（「workflow 是否固定稳定？」）和 Q3（「task structure 是否可表达？」）即使有经验的团队也会绊倒。两者都在问可预测性；区别在于问的是哪一种可预测性：

问题	它问什么	「yes」意味着什么	「yes」路由到
Q2	steps 本身是否跨 runs 固定	同一个 Python 函数调用序列每次都能产生正确答案。不需要 LLM 驱动的下一步决策。	Sequential workflow
Q3	即使 step-level 工作变化，major stages 是否能提前表达	你能在看到具体输入前，在白板上描述阶段结构。LLM 仍然要在每个阶段内部决定做什么。	Planning + ReAct execution

最容易伤人的混淆是：工程师看到任务有结构（「这里显然有阶段：research、analyze、write」），于是对 Q2 回答 YES。但「存在结构」是 Q3 的问题，不是 Q2 的问题。 Q2 问的是你能否预测运行时的精确步骤序列；如果 agent 在每个阶段内部仍需要做决策（哪些来源、哪些分析、哪些 framing），Q2 的答案就是 NO，你应该来到 Q3。

区分 Q2 与 Q3 的 3 个边界示例：

示例 A，invoice intake（Q2 = YES → Sequential workflow）：extract → validate → store → notify。每次都是同样 5 个步骤。 LLM 抽取字段并写通知，但不决定下一步做什么。step sequence 固定。

示例 B，market research report（Q2 = NO, Q3 = YES → Planning + ReAct）：gather data → analyze → synthesize → draft → review。阶段可表达，但每个阶段内部由 agent 决定做什么（查哪些来源、关注哪些竞争对手、做哪些分析）。阶段固定；阶段内步骤自适应。

示例 C，customer-support investigation（Q2 = NO, Q3 = NO → Single agent + ReAct）：agent 调查客户问题。没有预先确定的阶段结构：根据发现，工作可能是一次 lookup，也可能是 5 次 lookup 加一个 policy check 再加 escalation。阶段和步骤都不固定。

注意，示例 B 是第 5 部分的 Decisions 只部分练到的情形。如果你发现自己同时想说「这里有清晰阶段」以及「planner 产出计划但执行一直偏离」，你就在 Q2 / Q3 边界上，答案几乎总是 Planning + ReAct，而不是 Sequential workflow。

Q2 中 known-but-variable 子情况值得单独命名。 有时 Q1 = YES（路径已知），但 Q2 = NO（跨输入可变），例如 workflow 根据输入类型有 3-4 个稳定变体（quick lookup vs. multi-source synthesis vs. document analysis）。这既不是 Sequential workflow，也不是 Planning + ReAct；这是带显式输入类型路由的 branched workflow。概念 5 覆盖它；概念 16.5 的 anti-pattern gallery 中「给稳定 workflow 加 planning」那一行覆盖的是反向失败。

结论：Q3 问的是任务高层结构（阶段和依赖）是否能在执行前表达。可表达结构路由到 planning + ReAct execution（计划提供形状；ReAct 处理每个阶段内的未知内容）。不可表达结构路由到纯 ReAct + 工具（agent 自适应地发现形状和内容）。陷阱是发明不存在的结构（强行计划，执行偏离）以及错过实际存在的结构（对有阶段的工作使用纯 ReAct，导致漫游）。

概念 7：Q4：quality 是否比 speed 更重要，且 criteria 可检查？

Q4 是两个叠加层问题中的第一个。核心模式（顺序工作流、ReAct，或 planning + ReAct）已经由 Q1-Q3 选定。Q4 问的是是否在上面叠加 reflection。

Reflection 做什么。 agent 产出输出后，critique pass 根据明确标准评估它。如果 critique 识别出缺陷，agent 会细化或重新生成。这个模式的押注（来自概念 2）是：critique pass 能抓住 generator 漏掉的错误，而且「好输出」的标准明确到 critique 有意义。

Reflection 有价值必须同时满足两个条件。

1. 质量比速度重要。 Reflection 至少增加 1 次额外 LLM 调用（critique），常常增加 2 次（critique + refinement）。对延迟敏感的交互场景（实时客户支持、conversational agents）来说，这笔成本通常太高。对输出会被人审阅或交给下游系统的 batch 场景（报告生成、代码生成、文档起草）来说，延迟通常可以接受。测试：如果响应慢 2-5×，但输出质量显著更高，是否可接受？
2. 评估标准明确且可检查。 含糊标准会产生含糊 critique。「确保它很好」不是标准。「验证 SQL 可解析、只访问列出的表、且不使用 SELECT *」才是。没有明确标准，critique pass 就会变成不能改善输出的冗长闲聊，并且常常制造「AI 已经检查过了」的虚假信心。

两个条件同样重要。 给延迟敏感任务加 reflection 是浪费时间。给标准含糊任务加 reflection 是表演。两种失败都常见；两者都来自跳过 Q4、只是因为 reflection 听起来严谨就添加它。

测试。 问两个问题：

• 如果这个响应慢 3-5×，用户（或下游消费者）会因为质量显著提升而接受吗？如果不会，reflection 不符合延迟预算。
• 我能否用 5-10 条具体 bullet points 写清楚这个任务的「好输出」到底是什么，让另一个 LLM 能读这些条目并检查输出？如果不能，reflection 不符合标准清晰度。

如果两个答案都是 yes，reflection 有价值。如果任一个是 no，跳过 reflection。

团队常错在哪里。

因为 critic 听起来严谨而添加 reflection。「先生成，再 critique」听起来像好工程。很多时候确实是；有时只是展示。测试标准是 critique 是否以可测量方式改变了输出。如果你添加 reflection 后，post-reflection 输出 90% 时间都与 pre-reflection 相同，reflection 没在工作；它只是在增加成本。

对 generator 和 critic 使用同一个模型与提示词风格。critic 拥有相同训练数据、相同偏差、相同盲点。它倾向于 rubber-stamp。有效的 reflection 模式要么（a）为 critic 使用不同模型，要么（b）用根本不同视角来 framing critic（「你是严格审稿人，专门找问题」vs. generator 的 helpful framing），要么（c）给 critic 明确检查工具（运行 SQL、解析 JSON、按 schema 校验）。

对不可检查输出做 reflection。Reflection 适合「错误」可定义的任务：有错误的 SQL、不能编译的代码、遗漏源文关键事实的摘要。它不适合「好」很主观的任务：营销文案、创意写作、对话回复。主观领域从 human-in-the-loop review 中受益通常多于 LLM reflection。

路由。 如果两个条件都成立，就在 Q1-Q3 选出的核心模式之上添加 reflection 层。它不替代核心模式；它包裹核心模式。带 reflection 的顺序工作流先运行 workflow，再 critique 最终输出。带 reflection 的 ReAct agent 先完成自己的循环，再 critique 最终输出。Reflection 是事后质量控制，不是核心模式的替代品。

如果任一条件不成立，就跳过 reflection。如果你确实需要质量保证但标准不可检查，正确修复是 human review，而不是 LLM reflection。

结论：Q4 问的是 quality 是否比 speed 更重要，并且 evaluation criteria 是否明确可检查。两个条件都必须成立，reflection 才有价值。对延迟敏感任务做 reflection 是浪费时间；对标准含糊任务做 reflection 是表演。两个最常见失败模式是因为 reflection 听起来严谨就添加它（却不检查是否改变输出），以及用同一模型和提示词风格做 generator 与 critic（导致 rubber-stamping）。当 reflection 合理时，它叠加在核心模式之上，而不是替代核心模式。

概念 8：Q5：是否存在 specialization、context 或 scale bottleneck？

Q5 是第二个叠加层问题，也是后果最重的问题，因为多 agent 系统是最昂贵的构建模式；如果证明错误，也是最昂贵的移除模式。

多 agent 系统押注什么。 3 个经常被混在一起的不同主张：

1. Specialization claim： 任务需要不同专业能力，而单个 agent 无法在一个提示词里很好持有。coder、security reviewer 和 documentation writer 各自有不同的最佳提示词、最佳工具和最佳评估标准。把三者塞进一个 agent 会让三者都平庸。
2. Context claim： 任务需要的上下文超过单个 agent 能有效使用的范围。即使上下文窗口技术上足够大，随着上下文增长，检索和推理也会退化。把工作拆给多个 agent，每个 agent 使用自己的聚焦上下文，可以保持推理质量。
3. Scale claim： 任务包含可并行运行的工作，多 agent 系统能比单个顺序 agent 更快执行。并行研究 10 个竞争对手，比一个一个研究更快。

每个主张都必须针对真实任务单独测试。

specialization claim 最常被未经证据地相信。工程师看到「构建一个功能」这样的任务，会按角色拆解（architect、coder、tester、reviewer），因为这感觉直观。这种直觉错的时候和对的时候一样多。 真实功能开发往往由一个有良好工具访问的 agent 做得更好；architect-coder-tester 分离引入的 handoff 成本可能超过专业分工收益。测试这个主张：如果某个领域专家只专注这一片，工作是否会有实质改善？

context claim 在规模上更常为真。一个 agent 跨 10 个知识库做 10 次检索，会累积削弱推理的上下文。拆成 10 个 retrieval-and-summary agent，每个产出聚焦 brief，再组合这些 brief，常常表现更好，因为每个 retrieval agent 的上下文都保持小而聚焦。但这是一个真实架构决策，不是默认选项。

scale claim 最容易测试：并行执行是否提供可测量的吞吐提升？任务是否真的能干净并行？如果工作有严格顺序依赖（每一步需要上一步输出），并行多 agent 执行只会增加协调成本，不会买到速度。

测试。 3 个子问题：

1. 我能否说出证明 specialist 合理的具体专业能力？「这样更干净」不算。「reviewer 需要应用 OWASP 标准，而 coder 不该被要求全部学会」算。如果说不出具体专业能力，specialization claim 大概率是审美性的。
2. 任务上下文是否会超过单个 agent 能有效使用的范围？如果任务需要多个不同知识库、跨许多来源的长时间调查，或每个阶段使用专门工具集，通常是 yes。如果上下文能放进一个管理良好的提示词，通常是 no。
3. 工作是否真的能并行，并带来可测量吞吐提升？如果工作是顺序的（每一步依赖上一步），并行执行没有帮助。如果工作是真正独立的（研究 10 个竞争对手、评估 10 个候选人、总结 10 份文档），并行化有真实价值。

如果至少一个子问题得到强 yes，多 agent 就合理。如果 3 个问题都只是「maybe」或「为了组织原因，有独立 agent 会更好」，保持单 agent 模式。协调开销真实且很大。

团队常错在哪里。

为了组织原因构建多 agent 系统。「我们有 3 个团队做这件事，所以就做 3 个 agent。」这是让 agent 架构镜像组织结构。几乎总是错的。 多 agent 系统应该围绕任务属性设计，而不是团队边界。（3 个团队可以协作构建一个 agent；组织结构和 agent 结构不必匹配。）

低估协调成本。agent 之间的每次 handoff 都引入一个序列化点（一个 agent 的输出成为另一个 agent 的输入）、一个潜在失败点（handoff 格式可能不匹配）、一个调试难点（出错时到底哪个 agent 导致的？）。多 agent 系统的调试成本大约比单 agent 系统高一个数量级：判断成本是否合理时，要把这一点计入推理。

为了展示复杂度而构建多 agent。这是演讲和 demo 失败模式。多 agent 系统在架构图里很漂亮；它们展示「真正的 AI」。如果真实任务不能证明它们合理，你构建的是漂亮开销。

路由。 如果 specialization、context 或 scale 造成真实瓶颈 → Multi-Agent Specialist System。系统可能有一个 coordinator / routing agent 加 specialist，或带显式 handoff contract 的 specialist，或通过共享状态通信的 specialist。核心模式（顺序工作流、ReAct、planning + ReAct）仍然适用于每个 specialist 的领域；多 agent 是模式的组合，不是对它们的替代。

如果不存在真实瓶颈 → 保持单 agent 模式。如果 Q4 条件成立，可以加 reflection；但不要因为审美原因加多 agent。

Q5 的量化触发器：触发多 agent 决策的具体指标。 「specialization、context 或 scale bottleneck」默认依赖判断，而判断正是 pattern-overshoot 滋生的地方。尽可能用测量替代判断。 下面这些触发器是经验规则，能把 Q5 从主观的「感觉像 specialists」移动到可辩护的「我们测到了 X，而且 X 超过阈值」。

Bottleneck claim	能证明升级合理的量化触发器	指标测量什么
Specialization	单 agent trace 显示工具路由错误集中在特定知识领域（粗略工作阈值：受影响类别中大约三分之一 runs，需按你自己的 baseline 校准）。示例：统一 billing+technical agent 在大量 technical queries 上选错工具，因为 billing 术语主导了上下文。	按 query category 分段的 per-trace tool-correctness：来自评测套件的 Phoenix evaluator
Specialization（定性 fallback）	无法测量？升级前必须写一份 specialist role 说明，用普通英文写清每个角色的职责、工具和验收标准。如果说明含糊，或角色职责重叠 >40%，specialization claim 就是审美性的，而不是架构性的。	文档评审，不是指标
Context overflow	随上下文增长，holdout set 上的准确率有实质下降（测你自己的曲线；粗略信号：15K → 45K token sweep 中下降约 10 个点值得调查）。示例：research agent 加载 25 份源文档后，15K context 准确率 78%，30K 为 71%，45K 为 62%。	golden dataset 上的 context-vs-accuracy 曲线
Scale（可并行）	每次 run 有 >5 个独立子任务，并且单 agent 执行延迟超过面向用户延迟预算的 >2×。示例：研究 10 个竞争对手 → 单 agent 顺序执行需要 8 分钟，预算是 3 分钟 → 并行多 agent 执行是唯一适配路径。	端到端延迟 + 子任务独立性分析
Scale（吞吐）	运行量超过单 agent 设计 rate-limit ceiling 的 10×，且没有 per-tenant concurrency cap 能维持公平性。示例：每 tenant 每天 5K runs，而 OpenAI quota 是 500 RPM，需要跨多个 agent identity 或 specialist-style decomposition 做 fan-out。	生产负载 × API rate limits：在 operational envelope 的 flow-control dashboards 中可见

证据层级。 证明多 agent 的证据从强到弱：

1. Production trace data 显示瓶颈（最好：你有证据说明单 agent 系统确实以这种方式失败）
2. Holdout-set measurements 显示瓶颈（强：受控实验）
3. Domain analysis 加书面 specialist-role specification（可接受：至少定义了你要构建什么）
4. 「感觉像 specialists」（不足：pattern-overshoot 就住在这里）

一个有用自检。 「我们能先交付的最小单 agent 设计是什么？什么具体失败会迫使我们以后升级到多 agent？」如果答案是「我们会在生产 trace 中发现 X failure pattern」，就先交付单 agent，并让升级触发器在该触发时触发。多 agent 很少是错误终点；它几乎总是错误起点。

结论：Q5 问 specialization、context 或 scale 是否造成真实瓶颈，从而证明多 agent 架构合理。3 个主张（specialization、context、scale）必须分别测试，并在可能时对照量化触发器测试（阈值是示例，需按系统校准：大约三分之一 runs 出现工具路由错误、高上下文下准确率下降约 10 个点、延迟超过预算 2× 以上）。Specialization 最常被无证据相信；context 在规模上更常真实；scale 最容易测试。最大失败模式是为了组织或审美原因构建多 agent，而不是为了任务属性；协调开销真实且很大，移除已部署的多 agent 系统是重写，不是重构。先从单 agent 开始；让测量触发升级。

概念 8.5：OpenAI Agents SDK 原语：每种模式使用什么

在第 3 部分逐一讲 5 种模式前，先把模式选择连接回实现。前面的课程把 OpenAI Agents SDK 作为锚点框架来讲。 本课的模式不是要你从零重新实现的抽象架构形状；它们是用你已经见过的 SDK 原语组合出来的形状。本概念把每种模式映射到构建它的具体 SDK 原语。

对模式选择重要的 5 个原语。

Primitive	它是什么	哪些模式使用它
Agent	核心类，一个由 LLM 驱动、带 instructions、tools 和可选结构化输出 schema 的实体。每种模式的原子单元。	全部 5 种模式
Runner.run(agent, input)	运行 agent 循环，直到产出最终输出。SDK 为你运行循环：不需要手写 reason-act-observe cycle。	单 agent + ReAct（最突出）、Planning + ReAct、多 agent（每个 specialist）
@function_tool	把 Python 函数变成 agent 可调用工具的装饰器。Type signatures 和 docstrings 会自动成为工具 schema。	单 agent + ReAct、Planning + ReAct、多 agent（每个 specialist）、顺序工作流（当 LLM-step 需要工具时）
handoff(target_agent)	用于多 agent 转换的一等 SDK 原语：一个 agent 明确把控制权交给另一个，并保留 conversation context。比手写 coordinator 更干净。	多 agent（主要用途）；Planning + ReAct（planner-to-executor）
output_guardrail / input_guardrail	在 agent 输入或输出上运行 validation / critique pass 的 SDK 原语。SDK 原生 reflection 模式。	Reflection（主要用途）；任何需要输入校验的模式

还有一个值得命名的原语：Agent.as_tool()。 它把一个 Agent 转换成另一个 Agent 可调用的工具。这是 SDK 用于分层多 agent 组合的机制（coordinator agent 像调用任何函数工具一样调用 specialist agent）。使用 Agent.as_tool() 的多 agent 系统比使用 handoff() 的多 agent 系统更简单，因为 coordinator 保持控制；handoff() 适合你确实希望 specialist 接管 conversation 的情形。

打开模式到 SDK 原语的映射（第一遍可略读；实现时再打开）。

模式 → 原语映射一览。

Sequential workflow:
    Agent(output_type=...) at the LLM-steps; plain Python everywhere else
    Runner.run() called once per LLM-step: no agentic loop (the agent has no tools)

Single agent + ReAct + tools:
    Agent(instructions=..., tools=[@function_tool, @function_tool, ...])
    Runner.run(agent, input): the SDK runs the reason-act-observe loop

Planning + ReAct execution:
    planner = Agent(output_type=PlanSchema)
    plan = await Runner.run(planner, task)
    for stage in plan.stages:
        result = await Runner.run(stage.agent, stage.input)

Single agent + reflection:
    Agent(..., output_guardrails=[critic_guardrail])
    OR: Agent(..., tools=[Agent.as_tool(critic_agent)])

Multi-agent specialist system:
    coordinator = Agent(handoffs=[researcher, writer, reviewer])
    OR: coordinator = Agent(tools=[researcher.as_tool(), writer.as_tool(), ...])

第 3 部分后面的代码块会用完整 SDK 细节展示这些形状。

为什么这个映射对模式选择重要。 SDK 原语不只是实现便利，它们编码了架构决策。选择 handoff() 还是 as_tool() 本身就是一个 pattern-composition 决策。 handoff() 意味着「specialist 接管 conversation」；as_tool() 意味着「coordinator 保持控制并把 specialist 当作函数使用」。前者适合 specialist 需要直接与用户互动；后者适合 coordinator 组合 specialist 输出。知道该用哪个，是本课程所教授的同一套模式选择纪律的下游结果。

与 worked example 的连接。 客户支持 Worker（Maya 的 Tier-1 Support agent）使用 Agent + @function_tool（用于 lookup、refund、escalation）+ Runner.run()（在 FastAPI handler 中）。它是单 agent + ReAct + 工具模式，正是概念 10 将用 SDK 细节讲解的模式。Maya 的实现就是本课程 5 种模式之一；另外 4 种是当任务属性变化时你会选择的变体。

概念 8.5 的结论：SDK 原语是全部 5 种模式的构建块。Agent 是原子单元；Runner.run() 运行循环；@function_tool 把 Python 函数暴露为工具；handoff() 和 as_tool() 把 agent 组合成多 agent 系统；output_guardrail 实现 reflection。模式 → 原语映射让本课的架构选择具体化：模式选择不是抽象的；它是在选择组合哪些 SDK 原语以及如何组合。

概念 8.6：每种模式的 operational envelope 考量（以 Inngest 为具体例子）

独立读者提示。本概念讲的是模式选择的运维后果，不是教 Inngest。 这个架构论点会泛化到任何 durable-execution 平台（Temporal、Restate、Dapr Agents、AWS Step Functions）；Inngest 只是具体例子，因为 operational-envelope 课程讲的是它。如果你使用不同平台，或仍处在 operational platform 未定的设计阶段，请关注模式架构论点：模式越复杂，就越依赖 operational envelope。 把 Inngest 原语替换成你平台的原语即可。

概念 8.5 把模式映射到 engine 原语（OpenAI Agents SDK）。概念 8.6 把模式映射到 operational envelope 原语：让 agent 循环能在失败中存活、扩展到许多并发用户，并与向它发事件的外部世界集成的运行时机械结构。SDK 运行 agent 循环；envelope 让 agent 循环达到生产级。 每种模式使用不同 envelope 原语；模式越复杂，就越依赖 envelope。

在 Agent Factory 路线中，operational envelope 是 Inngest。下面的原语是 Inngest 的；底层模式架构论点是通用的。

对模式选择重要的 operational-envelope 原语。

Primitive	它是什么	哪些模式最常使用
@inngest_client.create_function	把函数注册到 durable-execution runtime 的装饰器。被运维管理的工作单元。	全部 5 种模式
TriggerEvent, TriggerCron	触发表面：外部世界发出的事件，以及唤醒 function 的 schedule。agent 不是在你调用它时运行；它是在外部世界触发 trigger 时运行。	全部 5 种模式；cron 与 incident response 和 batch workflow 最相关
ctx.step.run(name, fn, ...)	每次调用都是持久 checkpoint；已完成步骤在重试时返回 memoized output；失败步骤独立重试。生产可靠性底层机制。	顺序工作流（最直接映射）、Planning + ReAct（每个 stage 一个 step.run）、Reflection（独立 generator / critic steps）
ctx.step.wait_for_event(...)	function 持久挂起，消耗 0 compute，直到匹配事件到达或超时触发。HITL gate 背后的运行时原语。	任何需要 human approval 的模式；多 agent（specialist 之间）；reflection（当 human judgment 是 critic 时）
concurrency, throttle, priority	每个 function 的 flow-control policy。Concurrency 限制 active runs；throttle 限制 starts/sec；priority 排队排序；per-key concurrency 提供 multi-tenant fairness。	多 agent（最关键，per-specialist limits 防止 rate-limit exhaustion）；任何高流量单 agent 模式
Fan-out triggers	一个事件唤醒 N 个订阅函数；或一个 parent 触发 N 个 child events。并行 specialist 执行背后的运行时原语。	多 agent（并行拓扑）；Planning + ReAct（当 stages 可并行时）
Replay + dead-letter	失败 runs 持久保存；发出修复、点击 replay，function 用新代码从失败步骤恢复。失败前的步骤保持 memoized。	全部模式，但模式越复杂 replay 越重要，因为长 run 中途失败时风险更大

打开以 Inngest 为例的模式到 operational envelope 映射（第一遍可略读；实现时再打开）。

模式 → 原语映射一览。

Sequential workflow:
    @inngest_client.create_function(trigger=TriggerEvent(...))
    async def workflow(ctx):
        a = await ctx.step.run("extract", extractor_agent.run, ...)
        b = await ctx.step.run("validate", validate, a)
        c = await ctx.step.run("store", db.insert, b)
        await ctx.step.run("notify", notifier_agent.run, ...)
    # Each step independently checkpointed; failure → memoized resume

Single agent + ReAct + tools:
    @inngest_client.create_function(
        trigger=TriggerEvent(event="customer/email.received"),
        concurrency=[Concurrency(limit=10, key="event.data.customer_id")],
    )
    async def support(ctx):
        result = await ctx.step.run("agent-loop", Runner.run, support_agent, ctx.event.data["query"])
        # If agent needs HITL escalation, use step.wait_for_event inside the agent's tool
        return result.final_output

Planning + ReAct execution:
    @inngest_client.create_function(trigger=TriggerEvent(event="research/started"))
    async def planning(ctx):
        plan = await ctx.step.run("plan", Runner.run, planner, ctx.event.data["task"])
        results = {}
        for stage in plan.stages:
            # Each stage = one step.run. Crash mid-stage → only that stage retries.
            results[stage.id] = await ctx.step.run(f"stage-{stage.id}", Runner.run, stage.agent, ...)
        return await ctx.step.run("synthesize", Runner.run, synthesizer, results)

Single agent + reflection:
    @inngest_client.create_function(trigger=TriggerEvent(...))
    async def reflective(ctx):
        output = await ctx.step.run("generate", Runner.run, generator, ctx.event.data["task"])
        critique = await ctx.step.run("critique", Runner.run, critic, output)
        if not critique.final_output.is_safe:
            output = await ctx.step.run("refine", Runner.run, generator, refine_prompt(output, critique))
        return output

Multi-agent specialist system:
    # Coordinator triggers fan-out of specialist events
    @inngest_client.create_function(trigger=TriggerEvent(event="research/landscape.requested"))
    async def coordinator(ctx):
        plan = await ctx.step.run("plan", Runner.run, planner, ctx.event.data["topic"])
        await ctx.step.run("fan-out", fan_out_specialist_events, plan.competitors)
        # Each specialist runs independently as its own function:

    @inngest_client.create_function(
        trigger=TriggerEvent(event="research/competitor.research"),
        concurrency=[Concurrency(limit=5, key="event.data.tenant_id")],  # per-tenant cap
    )
    async def competitor_research(ctx):
        return await ctx.step.run("research", Runner.run, researcher, ctx.event.data["target"])

第 3 部分后面的边栏会按每种模式给出显式 operational-envelope section，展示这些映射。

为什么这个映射对模式选择重要。 有两个在架构图层面看不见、但会在生产中狠狠咬人的生产失败模式：

1. 中途崩溃。 一个 6 步的 planning + ReAct execution 在第 4 步崩溃（没有 durable execution）时，会重新为前 3 步付费。operational-envelope 课程对此做了量化：按 GPT-5 级别定价，一个多阶段 agent flow 每次崩溃可能重新支付约 $0.10-$2.00。每天 1000 runs，仅崩溃造成的丢失工作量就大约是每月 $30-$600。顺序工作流便宜地从崩溃中恢复，因为重试很短；multi-agent + reflection 系统昂贵地从崩溃中恢复，因为重试很长。 模式越复杂，operational envelope 的 step.run memoization 价值越能直接折算成钱。
2. 规模化协调。 一个有 5 个 specialist、10 个 tenants，并且 bursts 为 100 events/minute 的多 agent 系统，如果没有 per-specialist concurrency caps，会耗尽 rate limits。operational envelope 把它变成一行：concurrency=[Concurrency(limit=5, key="event.data.tenant_id")]。本课程的决策树选择模式；operational envelope 的 flow-control primitives 让所选模式在规模上保持健康。

部署组合。 operational envelope（Inngest）与你的云部署是组合关系，不是竞争关系。cloud deployment 课程讲云拓扑：ACA + Neon + R2 + Cloudflare Sandbox + Phoenix。operational-envelope 课程讲包裹这个拓扑中 SDK runner 的层。真实生产系统两者都会用： 部署在 ACA 上的 Inngest functions，调用 Runner.run() 并放在 step.run() 块内，Neon 存储 agent traces，sandbox 执行工具代码。第 3 部分的部署组合边栏会明确命名这两层。

评测组合。 Inngest 的结构化 trace（每个 step 的 input、output、retry count、latency）会像 SDK 的 agent trace 一样，通过 OpenTelemetry 流入 Phoenix。评测套件的失败检测模式（trace-length anomalies、plan-execution divergence、rubber-stamping）都适用于 Inngest-instrumented runs；加入 operational envelope 不会改变评测套件。

概念 8.6 的结论：operational envelope（Inngest）是全部 5 种模式的生产基底。Triggers 唤醒 function；step.run 让它持久；step.wait_for_event 实现 HITL gates；concurrency、throttle 和 priority 在负载下塑形；fan-out 协调多 agent specialists；replay 处理 bug-fix recovery。模式越复杂，envelope 越有价值：顺序工作流没有它也能存活；multi-agent + reflection 系统需要它。Envelope 与你的云部署和评测套件组合使用，不是替代关系，而是生产架构中的平行层。

三层并排看。 概念 8.5 和 8.6 一起说明，任何生产级 agentic 模式都是 3 层的组合：operational envelope（Inngest）、engine（OpenAI Agents SDK）和 cloud deployment。外部世界从顶部发出 triggers（客户邮件、billing 或 Slack 或 CRM 的 webhooks、cron schedule、来自其他 Workers 的 fan-out events、human approvals）；这些 triggers 向下流经 3 层。下图映射了每层中的原语及其作用。每当第 3 部分的 operational-envelope 边栏显得抽象时，回来参考这张图。

要点：3 层是堆叠关系。Inngest（envelope）包裹 SDK（engine），二者都运行在 cloud deployment 中。本课程选择模式；这 3 层把所选模式变成生产现实。 第 3 部分的全部 5 种模式都是这 3 层的组合；每种模式的差异在于每层使用哪些原语。模式越复杂（multi-agent with reflection），operational-envelope 层越关键，因为 coordination、durability 和 HITL 不再是可选项。

第 2 部分后，用 AI 试一次。 你已经有了 5 个问题。先在一个真实任务上用一次，再读深入模式。打开 Claude Code 或 OpenCode session，粘贴：

「我正在学习如何选择 agentic 架构。请从我真实工作中挑一个我可能为它构建 agent 的真实任务。先让我描述它，然后带我走完 5 个问题：Q1（solution path 是否已知？）、Q2（workflow 是否固定稳定？）、Q3（task structure 是否可表达？）、Q4（quality 是否超过 speed，且 criteria 可检查？）、Q5（是否有 specialization、context 或 scale bottleneck？）。当我的回答含糊，或我想选择比任务需要更复杂的模式时，请反驳我。最后告诉我这些答案指向哪种起始模式。」

你正在学习的东西：只有把 5 个问题用在你真正关心的任务上，它们才会变成反射。拿一个真实任务，大声走完一遍，并让某个东西反驳薄弱回答，比继续读后面 10 页更有价值。

---

第 3 部分：深入 5 种模式

第 2 部分按问题层面走完了决策树。第 3 部分按模式层面走它。对于 5 个终点模式中的每一种，我们都会讲：这个模式是什么、它的典型实现是什么、它对你的部署拓扑意味着什么，以及你的评测套件要观察什么，才能发现模式被误用。

部署与评测组合是本课程额外增加的层。很少有 agentic 模式课程会教这一层，因为它需要部署和评测课程作为基础。如果你没有学过那些课程，把边栏当成后续预览；如果你学过，组合层会让模式选择变成可运维的东西。

在逐一讲模式前，先看总结整个部分的矩阵。 每种模式使用云栈的不同子集；部署成本差异真实且显著。阅读概念 9-13 时可以回来参照。

矩阵把每种模式（列）映射到它需要的云部署组件（行）。对勾表示需要；叉表示不需要；波浪线表示有条件需要。

模式选择编码的成本纪律是：同样任务量下，一个在多 agent 系统上再叠加 reflection 的架构，成本可能是顺序工作流的很大倍数（示意比例，约数十倍，不是测量基准）。顺序工作流完全跳过 sandbox 和 bridge-Worker 层，因此避免了大块基础设施；在没有理由时选择 ReAct 或多 agent，就是为任务不需要的能力付费。

要点：顺序工作流有两个明确的「不需要」标记（sandbox 和 bridge Worker），这意味着它比 agentic 模式少很多基础设施。多 agent 有最多的扩展标记（per-specialist tracing、per-specialist bridge-Worker config）。这张矩阵把决策树的成本纪律可视化了。

概念 9：Sequential workflow：典型形状、部署、评测信号

它是什么。 一个固定步骤流水线，每一步的输出进入下一步。路径已知且稳定（Q1=yes，Q2=yes）。LLM 调用只保留给真正需要解释或生成、抽取、总结、分类的步骤，而不是用于决定下一步做什么。

OpenAI Agents SDK 中的典型实现：

from agents import Agent, Runner
from pydantic import BaseModel

class Invoice(BaseModel):
    vendor: str
    amount_cents: int
    due_date: str
    line_items: list[dict]

class NotificationMessage(BaseModel):
    subject: str
    body: str

# Two narrow agents: each does ONE LLM-step in the workflow.
# Notice: no tools, no agentic loop. Just structured-output extraction.
extractor = Agent(
    name="invoice_extractor",
    instructions="Extract structured invoice fields from the email body. Be strict about field types.",
    output_type=Invoice,
)

notifier = Agent(
    name="notification_writer",
    instructions="Write a brief notification message to the requester, referencing the invoice details.",
    output_type=NotificationMessage,
)

async def invoice_intake_workflow(email_content: str) -> ProcessingResult:
    # Step 1: extraction (SDK Agent with structured output)
    extraction = await Runner.run(extractor, email_content)
    invoice: Invoice = extraction.final_output

    # Step 2: validation (plain Python, no LLM)
    validation = validate_against_db(invoice)
    if not validation.ok:
        return ProcessingResult(status="rejected", reason=validation.reason)

    # Step 3: store (plain Python, no LLM)
    record_id = db.insert(invoice)

    # Step 4: notify (SDK Agent with structured output)
    notif = await Runner.run(notifier, f"Invoice {record_id} from {invoice.vendor} stored. Notify {invoice.requester}.")
    email.send(invoice.requester, notif.final_output.subject, notif.final_output.body)

    return ProcessingResult(status="completed", record_id=record_id)

注意 SDK 形状：两个很窄的 Agent 实例，每个只做一个 LLM-only 工作（抽取、通知写作）。每个 agent 都通过 output_type= 获得结构化输出，不做自由文本解析。 Runner.run() 调用两次，每个 LLM-step 一次。没有工具、没有 @function_tool decorators、没有 handoffs，因为 workflow 不需要 agentic reasoning，只需要嵌入普通 Python 的 LLM 调用。

值得内化的 SDK 洞察： 并非每次使用 Agent 都是「agentic」。一个 Agent 带 output_type= 且没有工具时，就是 SDK 惯用的「调用 LLM 并获得 typed response」方式，正好满足顺序工作流解释步骤的需求。你在使用 SDK，但没有使用 agent loop。

部署组合。 顺序工作流使用云栈的最小子集：

• 使用的 SDK 原语： Agent（用 output_type= 做结构化抽取 / 生成）、每个 LLM-step 一次 Runner.run()。没有 @function_tool，没有 handoff()，没有 as_tool()，没有 output_guardrail。agent loop 未使用；因为 agent 没有工具，Runner.run() 在一次 LLM 调用后返回。
• Azure Container Apps 上的 FastAPI harness：需要，你仍然需要 HTTP 服务接收请求。
• 用于持久状态的 Neon Postgres：需要，用于 workflow 记录和幂等性。
• 用于 LLM 调用的 OpenAI API：需要，但只用于特定需要的步骤。
• 用于文件的 Cloudflare R2：可能需要，只在 workflow 处理文件产物时需要。
• 用于执行的 Cloudflare Sandbox：不需要。 顺序工作流不运行 agent 生成代码；它运行的是嵌入 LLM 调用的确定性代码。sandbox 层（以及 bridge Worker）不需要。

这是关于顺序工作流最容易被低估的发现：它们不需要 cloud-deployment 课程教授的大部分部署复杂度。 如果你的任务适合顺序工作流，你可以用 FastAPI + Postgres + OpenAI 技术栈交付，完全跳过 sandbox 基础设施。成本节省：明显少于完整 agentic deployment，因为你完全跳过 sandbox 和 bridge-worker 层。不要为模式不需要的能力付费。

评测信号。 顺序工作流专属的评测套件要观察：

Failure mode	评测会把它捕捉为什么
Extraction step misreads the input	输出 schema validation 失败；DeepEval 捕捉 structured-output mismatch
Validation logic has a gap	生产 case 漏过；trace 显示 valid-but-wrong record 进入 storage
Notification message is off-tone or factually wrong	Phoenix inline evaluator 捕捉生成消息问题；提升到 golden dataset
Workflow handles a case it wasn't designed for	DeepEval test suite 包含 edge case inputs；失败暴露 workflow 的 assumption boundary

关键洞察是：顺序工作流 evals 关注步骤级正确性，而不是 agent 推理质量。你独立测试每个使用 LLM 的步骤（抽取是否返回正确 schema？生成是否产生正确语气？）。你测试 workflow 的分支点（validation 是否捕捉应捕捉的 case？）。你不需要测试「agent 是否选择了正确路径」，因为路径固定。

团队在生产中常错在哪里。 把嵌入 LLM 的 workflows 当成 agentic。团队会为既没有工具调用、也没有推理步骤的 workflow 添加 agent loop 观测（tool-call tracing、reasoning-step inspection）。你只需要标准 request/response tracing 加每步 structured-output validation。 Phoenix 的 agent-reasoning dashboard 对这种情况过重；App Insights 的标准 request tracing 才是合适层级。

Operational envelope。 顺序工作流是 Inngest durable-execution 模型最直接的适配对象。模式本身就是固定步骤、每步可能失败、依赖确定，这正是 Inngest functions 的用途。

• 使用的 Inngest 原语： 用 @inngest_client.create_function 注册 workflow；用 TriggerEvent 或 TriggerCron 作为唤醒信号；每个 workflow step 一个 ctx.step.run("step-name", fn, args)。没有 step.wait_for_event（常规 workflow 不需要 HITL）、没有 fan-out（workflow 是线性的）、没有复杂流控。
• 1:1 映射： 顺序工作流中的每个步骤都成为 Inngest function 中的一次 ctx.step.run 调用。概念 9 代码里的 5 步 invoice intake（extract → validate → store → notify）会变成 5 个 step.run 调用。第 3 步崩溃 → 第 1-2 步返回 memoized output，第 3 步重试。
• 成本收益： 按每次 LLM 调用 $0.001-$0.05 计算，如果 workflow 在第 5 步崩溃且没有 memoization，会重新为第 1-4 步付费。有 memoization 时，只有第 5 步重试。operational-envelope 课程量化了这一点；workflow 越长，节省越会复合。

顺序工作流加 Inngest 是本课程中最简单的生产就绪 agentic deployment。许多被误认为「agentic systems」的真实 workflow，其实应该是带 step.run checkpoints 的 Inngest functions。 决策树的 Q1（「路径是否已知？」）本质上是在问你是否应该选择没有 agent loop 的 Inngest。

概念 9 的结论：当路径已知且稳定时，顺序工作流是正确模式。它使用云栈的最小子集（不需要 sandbox），把 LLM 调用保留给 interpretation-only steps，并在步骤级而不是 agent-reasoning 级评测。最常见的生产错误，是用不需要的 agent-grade observability 过度观测 workflow。

概念 10：Single agent + ReAct + tools：典型形状、部署、评测信号

它是什么。 一个 agent 在推理当前状态与采取行动（工具调用）之间交替，观察结果后重复。路径未知（Q1=no），结构不可表达（Q3=no）。定义性特征是：agent 根据刚刚观察到的内容决定下一步做什么。

OpenAI Agents SDK 中的典型实现：

from agents import Agent, Runner, function_tool

# Tools: plain async Python functions, exposed to the agent via the decorator.
# Type hints and docstrings become the tool's schema automatically.
@function_tool
async def lookup_account(account_id: str) -> dict:
    """Look up an account's current state including balance, plan, and billing status."""
    return await db.accounts.find_by_id(account_id)

@function_tool
async def lookup_transactions(account_id: str, since_days: int = 90) -> list[dict]:
    """Return recent transactions for an account; defaults to last 90 days."""
    return await db.transactions.find(account_id=account_id, since=since_days)

@function_tool
async def issue_refund(transaction_id: str, amount_cents: int, reason: str) -> dict:
    """Issue a refund. Fails if amount exceeds agent's authority ($500). Returns refund_id."""
    return await refund_service.create(transaction_id, amount_cents, reason)

@function_tool
async def escalate_to_human(reason: str, context: dict) -> str:
    """Hand the case to a human reviewer. Returns the escalation ticket id."""
    return await escalation_service.create_ticket(reason, context)

# One Agent with all the tools. The SDK runs the reason-act-observe loop.
support_agent = Agent(
    name="tier1_support",
    instructions=(
        "You are a Tier-1 customer support agent. Investigate the customer's issue "
        "using your tools. Issue refunds only when policy clearly allows and the "
        "amount is under $500. Escalate any ambiguous case. If you cannot determine "
        "the right action within 3 lookups, escalate. State when you are done."
    ),
    tools=[lookup_account, lookup_transactions, issue_refund, escalate_to_human],
)

# The FastAPI handler: exactly the customer-support Worker's shape.
async def handle_support_request(customer_id: str, query: str) -> str:
    result = await Runner.run(
        support_agent,
        input=f"Customer {customer_id} asks: {query}",
        max_turns=25,  # explicit step budget: non-optional in production
    )
    return result.final_output

注意 SDK 形状：一个带多个工具的 Agent，通过 Runner.run() 调用。SDK 在内部运行 reason-act-observe 循环：你不用写 for step in range(max_steps): response = llm.chat(...); for tool_call in response.tool_calls: ...。max_turns 参数是步骤预算；命中时 SDK 会抛出 MaxTurnsExceeded。

值得内化的 SDK 洞察： canonical ReAct loop 就是一次 Runner.run() 调用。复杂性在工具定义和 agent instructions 中；循环机械结构是 SDK 的责任。这正是 Maya 的 Tier-1 Support agent，即客户支持 Worker 背后的模式。

部署组合。 单 agent ReAct 使用云栈的大部分组件：

• 使用的 SDK 原语： Agent（带 tools= 和 instructions=）、暴露为工具的每个 Python 函数上的 @function_tool decorator、用于 agentic loop 的 Runner.run(agent, input, max_turns=N)。这是 canonical SDK 形状，正是客户支持 Worker 部署的形状。没有 handoff() 或 as_tool()（那是多 agent 原语）；没有 output_guardrail（那是 reflection）。
• Azure Container Apps 上的 FastAPI harness：需要，用于 HTTP 服务。
• 用于持久状态的 Neon Postgres：需要，用于 sessions、runs、traces。关键，因为 agent 的 reasoning trace 是主要调试工件。
• 用于文件的 Cloudflare R2：如果 agent 处理文件输入 / 输出，则需要。
• 用于执行的 Cloudflare Sandbox：如果 agent 有代码执行工具，需要。agent 运行 apply_patch、shell commands 或任意 Python；这些代码进入 sandbox。bridge Worker 必须存在。
• Background worker pattern：需要，因为 ReAct loops 可能超过 30 秒，不应阻塞 HTTP request。

评测信号。 ReAct 的失败模式是 reasoning-level，因此评测信号也是 reasoning-level：

Failure mode	评测会把它捕捉为什么
Agent loops, revisiting solved work	Trace-length anomaly：同一工具被用相似参数反复调用。Phoenix flag
Agent invokes nonexistent tools (hallucinated tools)	SDK 中的 tool-call validation；structured trace 显示 invalid call；CI eval 通过 DeepEval 捕捉
Agent gives up before solving (premature termination)	将最终输出与 expected behavior 比较；trace 显示步骤很少；DeepEval 捕捉
Agent's reasoning diverges from its actions	Phoenix tool-correctness evaluator：agent 陈述的理由是否匹配它调用的工具
Tool call latency cascades (each step is slow)	OTel timing 显示总 runtime 超过 latency budget

关键洞察是：ReAct evals 必须捕捉推理 trace，而不只是 input/output。trace 就是数据。 如果你只检查 agent 是否得到了正确答案，就会错过它靠运气工具调用得到正确答案的情况，也会错过它本该得出正确答案、却因为一个坏决策失败的情况。Phoenix 的 inline trace evaluators 是 ReAct 的承重可观测性层。

团队在生产中常错在哪里。 让步骤预算默认无限。没有 step cap 的 ReAct loop 迟早会遇到让它无限循环的输入，燃烧 token、阻塞 workers、耗尽 rate limits。一定要显式限制步骤（25 是合理默认；有些任务需要 50；极少需要 100）。命中上限是需要调查的信号，不是应该移除的 workaround。

Operational envelope。 单 agent + ReAct 可以干净包进 Inngest，但有一个结构决策要做对：把整个 agent loop 做成一个 step.run，还是拆成多个 steps？

• 使用的 Inngest 原语： 带 event trigger 的 @inngest_client.create_function（TriggerEvent(event="customer/email.received")，Maya 的精确设置）；用 ctx.step.run("agent-loop", Runner.run, agent, input) 包裹 SDK 的 Runner.run() 调用；用 concurrency 和 throttle 保护下游系统；可选地，在 escalation tool 内部使用 ctx.step.wait_for_event 实现 HITL。
• 结构选择： 标准模式是让整个 agent loop 成为一个 step.run。SDK 在内部运行 reason-act-observe loop；从 Inngest 视角看，它是一个持久步骤。loop 中途崩溃 → 整个 loop 重试（SDK traces 会丢失，但 function 恢复）。另一种分解方式是把每个工具调用包进自己的 step.run，获得更细粒度持久性，但需要把 SDK 的 loop 从 Runner.run() 中抬出来，这很脆弱。除非有具体理由，否则默认每个 agent loop 一个 step.run。
• 通过 wait_for_event 做 HITL： 概念 10 代码中的 escalation tool 会变成 Inngest 模式。agent 调用 escalate_to_human 时，该工具发出一个事件（refund/approval.requested），function 通过 step.wait_for_event 挂起，直到人类响应。agent 代码保持干净，它只是调用工具；持久性由 envelope 处理。
• Concurrency caps： concurrency=[Concurrency(limit=10, key="event.data.customer_id")] 防止单个客户的突发流量饿死其他人。这是 operational envelope 的 per-key concurrency 模式，直接应用到 Maya 的部署。

Maya 的 Tier-1 Support agent 隐式就是这种组合：SDK Agent + Runner.run() 作为 engine，ACA + Neon + R2 + sandbox 作为 deployment，再加 Inngest envelope（若存在）负责 triggers、durability 和 flow control。第 5 部分的决策 1 会把这种组合显式化。

概念 10 的结论：当路径未知且结构不可表达时，single-agent ReAct 是正确模式。它使用云栈大部分组件（如果 agent 运行代码，则需要 sandbox；Python harness 需要 bridge Worker）。评测纪律捕捉 reasoning trace，而不只是最终输出：Phoenix 是 ReAct 的承重可观测性，因为 trace-level signals 才能抓住典型失败（looping、hallucinated tools、premature termination、reasoning-action divergence）。

概念 11：Planning + ReAct execution：典型形状、部署、评测信号

它是什么。 两层模式：planning agent 在执行开始前产出显式计划（带依赖关系的 stages）；ReAct + 工具处理每个 stage 内部的工作。step level 的路径未知（Q1=no），但 stage level 的结构可表达（Q3=yes）。

OpenAI Agents SDK 中的典型实现：

from agents import Agent, Runner, function_tool
from pydantic import BaseModel
from typing import Literal

class Stage(BaseModel):
    id: str
    description: str
    agent_role: Literal["researcher", "analyzer", "synthesizer"]
    depends_on: list[str]  # other stage ids
    step_budget: int

class Plan(BaseModel):
    task_summary: str
    stages: list[Stage]
    success_criteria: str

# Planner: an Agent that produces a structured plan, no tools.
planner = Agent(
    name="market_research_planner",
    instructions=(
        "Given a research task, produce a plan with 3-7 stages. Each stage has clear "
        "dependencies and a step budget. Prefer fewer broader stages over many narrow ones."
    ),
    output_type=Plan,
)

# Three execution specialists: each with its own tools and instructions.
researcher = Agent(
    name="researcher",
    instructions="Investigate the assigned topic using your tools. Return a structured brief.",
    tools=[web_search, fetch_url, read_document],
)
analyzer = Agent(
    name="analyzer",
    instructions="Analyze the briefs from researchers. Identify patterns, contradictions, gaps.",
    tools=[compute_metrics, compare_briefs],
)
synthesizer = Agent(
    name="synthesizer",
    instructions="Synthesize the analyzed findings into a coherent report.",
    tools=[draft_report, format_citations],
)

ROLE_TO_AGENT = {"researcher": researcher, "analyzer": analyzer, "synthesizer": synthesizer}

async def planning_then_react(task: str, session_id: str) -> str:
    # Stage 1: Generate the plan via the planner Agent
    plan_result = await Runner.run(planner, task)
    plan: Plan = plan_result.final_output
    await db.runs.persist_plan(session_id, plan)  # cloud deployment: plan persistence

    # Stage 2: Execute each stage via the matching specialist Agent
    stage_results: dict[str, str] = {}
    for stage in topological_order(plan.stages):
        agent = ROLE_TO_AGENT[stage.agent_role]
        stage_input = compose_stage_input(stage, stage_results, task)
        stage_run = await Runner.run(agent, stage_input, max_turns=stage.step_budget)
        stage_results[stage.id] = stage_run.final_output
        await db.runs.persist_stage(session_id, stage.id, stage_run.final_output)

    # Stage 3: Final synthesis via the synthesizer one more time
    final = await Runner.run(
        synthesizer,
        f"Compose the final report. Plan: {plan.model_dump_json()}. Results: {stage_results}",
    )
    return final.final_output

注意 SDK 形状：planner 是一个 Agent，带 output_type=Plan 且没有工具（只产出结构化输出）。每个执行 stage 使用与该 stage 角色匹配的 specialist Agent，通过 Runner.run() 调用。计划由 Pydantic 结构化，因此 SDK 在类型层校验它：不是解析 JSON 然后祈祷。Plan persistence 通过云部署中的 Neon-Postgres runs 表完成（客户支持 Worker 已经接好了）。

值得内化的 SDK 洞察： structured-output Agent + tool-using Agent 是 planning + ReAct execution 的两半。SDK 的 output_type= 让计划成为一等工件；其余只是围绕 Runner.run() 调用的普通编排代码。

部署组合。 Planning + ReAct 使用与单 agent ReAct 相同组件，并额外增加一种纪律：

• 使用的 SDK 原语： planner Agent 带 output_type=PlanSchema（无工具，只做结构化输出）；每个角色一个 execution Agent，带 tools=[...] 和 @function_tool decorators；Runner.run() 对 planner 调用一次，并对每个 stage 调用一次。Plan persistence 位于 cloud deployment 的 runs 表中，不在 SDK 本身；SDK 在多次 Runner.run() 调用之间是无状态的。
• 概念 10 中所有 ReAct 部署要求：同样的 harness、sandbox、R2、background worker。
• Neon 中的 plan persistence。 计划本身是值得为审计和可恢复性存储的工件。一个新表或对 runs 表的 schema 扩展会追踪 plan_id、计划内容，以及逐阶段进度。
• 长时间 runs 更常见。 计划通常有 5-10 个 stages，每个可能运行 20-30 个 ReAct steps。端到端运行 5-10 分钟很正常。background worker pattern 是强制的，不是可选的。

评测信号。 Planning + ReAct 在纯 ReAct 之外增加新失败模式：

Failure mode	评测会把它捕捉为什么
Planner produces a plan execution diverges from	对比 plan 与实际 stage execution；当 stages 被跳过、重排或运行中被实质重定义时标记
Plan has missing stages (an obvious step isn't in the plan)	与类似任务的 golden-dataset plans 比较；DeepEval 标记 structural divergence
Stage handoffs lose context	检查每个 stage 的输入；如果 stage N 不能引用 stage M 的关键输出，handoff 丢了信息
Plan is over-detailed (each stage is a single tool call)	Plan-stage size analysis；如果每个 stage 只执行 1-2 个 ReAct steps，planning layer 没在工作
Plan is under-detailed (one stage covers vast scope)	Plan-stage size analysis；如果一个 stage 运行 50+ ReAct steps，planning 实际没有分解

关键洞察是：planning + ReAct evals 必须把 plan quality 与 execution quality 分开测量。好计划坏执行，与坏计划好执行，看起来完全不同；把二者混在一起会产生错误诊断。「plan-execution divergence」这个评测信号最有信息量，它说明 planner 正在产出任务实际上没有的结构。

团队在生产中常错在哪里。 把计划当成合同来信任。计划是起始结构；stage 内执行可能合理地发现下一个 stage 需要与原计划不同的工作。把 divergence 一律当坏事会制造僵化；把它一律当正常会消除 planning 的价值。正确纪律是：记录每一次 divergence，定期复盘 divergence 是否有模式（反复出现的 divergence 意味着 planner 需要改进），并允许小的 stage 内适应自然发生。

Operational envelope。 Planning + ReAct execution 是 Inngest step.run 模型最清晰的适配对象；每个 stage 映射到一个 step.run，持久性收益会在多阶段 run 中复合。

• 使用的 Inngest 原语： parent function 使用 @inngest_client.create_function；每个 stage 一个 ctx.step.run（step.run("plan", Runner.run, planner, task)，然后每个 execution stage 一个 step.run）；如果某些 stages 有非瞬时失败模式，为每个 stage 配置 retries=；用 concurrency 限制并行 runs。
• plan-then-execute 映射： step.run("plan", ...) 产出计划；function 遍历 plan.stages，对每个 stage 调用 step.run(f"stage-{stage.id}", ...)。如果 function 在执行中途崩溃（比如 6 个 stages 中的第 4 个），Inngest 会从 memoization 恢复 plan 和 stages 1-3；只有 stage 4 重试。 Plan persistence 是免费的，Inngest 会把它存为 "plan" step 的输出。
• 成本影响： 这里的节省是所有模式中最大的。一个 planning + ReAct run 可能需要 5-10 分钟并涉及 20-30 次工具调用；第 8 分钟崩溃且没有 durability，会重新为所有内容付费。operational envelope 的 memoization 在 GPT-5 级别定价下，每次崩溃 run 可节省 $0.50-$2.00。对每天 1000 个此类 runs、且有 1-5% 因瞬时基础设施问题崩溃的系统来说，这直接节省每月 $150-$1000 的 LLM 成本。
• 并行 stage execution： 彼此没有依赖的 stages 可以通过 operational envelope 的 fan-out pattern 并行化（每个 stage 一个事件，各自触发自己的 function），同时保留 per-stage durability。

如果 envelope 中有 Inngest，概念 11 部署组合中「Neon 中的 plan persistence」要求会部分变得不必要，因为 Inngest 会把 plan 存为 "plan" step 的输出。Neon 仍然通过 OTel 跟踪 run，用于审计和可观测性，但 plan-recovery story 由 Inngest 而不是应用代码处理。

概念 11 的结论：当结构可表达但 step-level 工作需要适应时，planning + ReAct execution 是正确模式。它使用完整 ReAct 部署栈，再加 plan persistence 和 background-worker pattern。评测纪律把 plan quality 与 execution quality 分开；plan-execution divergence 是最有信息量的信号，说明 planner 正在产出任务实际上没有的结构。

概念 12：Single agent + reflection：典型形状、部署、评测信号

它是什么。 叠加在任一核心模式之上的层：agent 产出输出后，critique pass 根据明确标准评估它；如果识别出缺陷，agent 会细化或重新生成。Reflection 由 Q4 证明合理（quality > speed 且 criteria 可检查）。

OpenAI Agents SDK 中的典型实现。 SDK 为 reflection 提供两个不同原语；根据你想要 validation（阻止坏输出）还是 refinement（改善边界输出）来选。

风格 1，output_guardrail 用于 validation-style reflection（轻量 SDK 原生模式）：

from agents import Agent, Runner, output_guardrail, GuardrailFunctionOutput, RunContextWrapper
from pydantic import BaseModel

class SQLReview(BaseModel):
    is_safe: bool
    issues: list[str]
    reasoning: str

# A critic Agent: uses a different model from the generator to avoid blind-spot overlap.
sql_critic = Agent(
    name="sql_critic",
    model="claude-opus-4-5",  # different model family from the generator
    instructions=(
        "Review the SQL query. Check that it parses, hits only allowed tables, "
        "does not use SELECT *, and has appropriate WHERE clauses. Flag any issues."
    ),
    output_type=SQLReview,
)

@output_guardrail
async def critic_guardrail(ctx: RunContextWrapper, agent: Agent, output: str) -> GuardrailFunctionOutput:
    review_result = await Runner.run(sql_critic, output)
    review: SQLReview = review_result.final_output
    return GuardrailFunctionOutput(
        output_info={"issues": review.issues, "reasoning": review.reasoning},
        tripwire_triggered=not review.is_safe,
    )

# The generator Agent: uses output_guardrails to invoke the critic.
sql_generator = Agent(
    name="sql_generator",
    model="gpt-5",  # different model family from the critic
    instructions="Generate a SQL query that answers the user's question.",
    tools=[fetch_schema, list_tables],
    output_guardrails=[critic_guardrail],
)

# When tripwire fires, Runner.run raises OutputGuardrailTripwireTriggered.
# Catch it and decide: retry with critique context, escalate, or fail loudly.

风格 2，单独 critic-and-refiner loop 用于 refinement-style reflection（当你想让 generator 修复输出，而不只是阻止坏输出时）：

async def with_reflection(task: str, max_refinements: int = 2) -> str:
    output = (await Runner.run(sql_generator, task)).final_output
    for refinement in range(max_refinements):
        critique = (await Runner.run(sql_critic, output)).final_output
        if critique.is_safe and not critique.issues:
            return output
        # Refinement: feed the critique back to the generator
        refine_prompt = f"Original query:\n{output}\n\nCritic flagged: {critique.issues}\n\nRevise the query."
        output = (await Runner.run(sql_generator, refine_prompt)).final_output
    return output  # max refinements reached; output is best-effort

注意两种 SDK 形状：output_guardrail 是 SDK 原生的「阻止坏输出」模式：声明式、绑定到 agent 定义、在每次 Runner.run() 上自动运行。单独 critic-and-refiner loop 是 SDK 惯用的「改善边界输出」模式：更灵活，但你要自己写编排。两种模式都为 critic 和 generator 使用不同模型。 这就是概念 7 命名的纪律，通过每个 model= 参数（位于对应 Agent 上）在 SDK 中具体化。

值得内化的 SDK 洞察： reflection 在 SDK 里不是独立框架原语，而是 Agent + Agent 的组合。output_guardrail decorator 只是把第二个 agent 接入第一个 agent 输出路径的 SDK 约定。

部署组合。 Reflection 叠加在核心模式之上，因此部署组合取决于底下是什么：

• 使用的 SDK 原语： output_guardrail（SDK 原生 validation 原语）用于 block-bad-outputs reflection；或两个 Agent 实例（generator + critic），并对每个 agent 调用 Runner.run() 实现 refinement-style reflection。关键点：critic 应该使用不同于 generator 的 model=，同一个 SDK，不同模型家族。
• 如果 core 是顺序工作流，reflection 增加 1-2 次 LLM 调用；部署结构不变。
• 如果 core 是 ReAct + tools，reflection 在 agent loop 完成后增加 1-2 次 LLM 调用；部署结构不变。
• 如果 core 是 planning + ReAct，reflection 常常放在 stages 之间（在 stage N+1 开始前 critique stage N 的输出），也放在最终 synthesis 上；这会增加延迟。

新的部署考量：model variety。 如果 critic 使用不同于 generator 的模型（Claude critique GPT，或反过来），harness 需要支持多个 model providers。cloud deployment 课程教授的是 single-provider deployment；添加 reflection 常常会让 multi-provider 成为真实需求。相应地规划 secrets-management 和 routing。

评测信号。 Reflection 有自己的典型失败模式：

Failure mode	评测会把它捕捉为什么
Reflection doesn't change the output (rubber-stamping)	比较 pre-reflection 与 post-reflection outputs；如果它们 >80% 时间几乎相同，reflection 没在工作
Reflection refines in the wrong direction (makes output worse)	用 golden dataset 分别评分 pre- 和 post-reflection；净负面影响意味着 critic 误触
Critic and generator share blind spots	A/B test：同一 generator，两个不同 critics（不同模型或提示词）；如果 critique content 强相关，critics 还不够独立
Criteria drift over time (the criteria list grows or shrinks ad-hoc)	对 criteria list 做版本控制；当变更不对应 documented decisions 时标记
Refinement loops exceed the budget	Refinement counter 超过阈值；调查为什么 critic 持续发现 generator 修不掉的缺陷

关键洞察是：reflection evals 必须衡量 reflection 是否净正向，而不只是它是否运行。一个运行但不改变输出的 reflection pass 是开销；一个让输出更差的 reflection pass 是有害的。「rubber-stamp」失败模式最难检测，因为表层指标看起来健康（延迟上升、错误持平），但没有赚回成本。

团队在生产中常错在哪里。 因为 reflection 听起来严谨就添加它。团队添加「generate, then critique」模式，却不衡量 critique 是否抓住 generator 漏掉的东西。几个月后，reflection pass 已经用额外 LLM 调用花了 $X，却提供了 $0 可测量质量提升。纪律是：部署第一个月内测量 reflection 的净贡献；如果贡献低于阈值，就移除它。

Operational envelope。 Reflection 与 Inngest 的 step model 组合得很好；每个 pass（generate、critique、refine）成为自己的 step.run，持久性收益与你在任何单次失败前已经完成的 pass 数量成正比。

• 使用的 Inngest 原语： 每次运行 3 或 4 个 ctx.step.run 调用，step.run("generate", ...)、step.run("critique", ...)，以及 0-2 个 step.run("refine-N", ...) refinement attempts。可选：当 critic 是人类时使用 ctx.step.wait_for_event（function 挂起，直到 human reviewer 发出 approval event，这是 operational envelope 提供的同一个 HITL-gate 原语）。
• durability win： 如果 generator step 成功完成（通常是最昂贵的步骤，因为它产出被 critique 的输出），而 critic step 出现瞬时失败（rate limit、network blip），只有 critic step 重试。generator 的输出会 memoized，不会重新生成。operational envelope 的 step.run 纪律会防止 reflection 添加的延迟在崩溃时复合成双倍成本。
• HITL reflection。 当 evaluation criteria 不能由另一个 LLM 检查（概念 7 中「subjective domains」 caveat）时，正确答案常常是 human reflection。Inngest 的 step.wait_for_event 让它很干净：step.run("generate", ...) → step.run("send-to-reviewer", ...) → step.wait_for_event("await-human-decision", timeout=timedelta(hours=4)) → step.run("act-on-decision", ...)。function 在人类 review 期间挂起，消耗 0 compute。 operational-envelope 课程会详细讲 HITL 模式。
• reflection 的 cost-per-output 纪律： Inngest 的 run-level cost tracking（每个 step.run 的 LLM 成本）让测量 reflection 净贡献变得很简单。Per-run cost comparison（with-reflection vs. without-reflection）只差一个 Phoenix dashboard query。

概念 12 中的两种 SDK reflection 风格（output_guardrail vs. 单独 critic-and-refiner loop）都能自然地与 Inngest envelope 组合。按 reflection style 选择 SDK 风格；envelope 纪律两者相同。

概念 12 的结论：当 quality 比 speed 更重要，并且 criteria 可检查时，reflection 是正确叠加层。它叠加在任何核心模式之上。评测纪律衡量 reflection 是否净正向；rubber-stamping 是最隐蔽失败模式，因为表层指标看起来健康。如果 reflection 部署一个月后没有可测量地改善输出，就移除它。

概念 13：Multi-agent specialist system：典型形状、部署、评测信号

它是什么。 多个角色不同的 agent 协作完成任务。Q5 证明它合理：specialization、context 或 scale 造成真实瓶颈。模式组合很重要：每个 specialist 的内部架构可以是顺序工作流、ReAct 或 planning + ReAct。多 agent 不是其他模式的替代品；它是它们的组合。

3 种 SDK 原生拓扑，每种使用不同 SDK 原语。

拓扑 1，coordinator 把 specialists 当作工具（SDK 的 Agent.as_tool() 模式）。 coordinator 保持控制；specialists 像函数工具一样被调用。

from agents import Agent, Runner, function_tool

# Three specialists, each with its own tools and instructions.
researcher = Agent(name="researcher", instructions="...", tools=[web_search, fetch_url])
writer = Agent(name="writer", instructions="...", tools=[draft_document])
reviewer = Agent(name="reviewer", instructions="...", tools=[lint_check, fact_check])

# The coordinator uses specialists as_tool(): calling them like functions.
coordinator = Agent(
    name="coordinator",
    instructions=(
        "Decompose the task into research, writing, and review phases. "
        "Use the specialist tools in order. Compose their outputs into a final report."
    ),
    tools=[
        researcher.as_tool(tool_name="research_topic", tool_description="Investigate a topic and return a brief"),
        writer.as_tool(tool_name="draft_document", tool_description="Draft a document from research notes"),
        reviewer.as_tool(tool_name="review_document", tool_description="Review a draft and return critique"),
    ],
)

async def coordinator_topology(task: str) -> str:
    result = await Runner.run(coordinator, task, max_turns=30)
    return result.final_output

拓扑 2：Sequential handoff（SDK 的 handoff() 模式）。 specialists 接管 conversation；SDK 在它们之间传递上下文。

from agents import Agent, Runner, handoff

# Define specialists; each one declares which agents it can hand off TO.
final_reviewer = Agent(name="reviewer", instructions="Review the draft and produce the final output.")
writer = Agent(
    name="writer",
    instructions="Draft from the research. When the draft is ready, hand off to the reviewer.",
    handoffs=[handoff(final_reviewer)],
)
researcher = Agent(
    name="researcher",
    instructions="Investigate the topic. When research is complete, hand off to the writer.",
    tools=[web_search, fetch_url],
    handoffs=[handoff(writer)],
)

async def handoff_topology(task: str) -> str:
    # Start with the researcher; the SDK threads control through handoffs.
    result = await Runner.run(researcher, task, max_turns=50)
    return result.final_output  # whoever ended up holding the conversation

拓扑 3，由 synthesizer 组合并行 specialists。 SDK 通过 Runner.run() 独立运行每个 specialist；synthesizer 组合它们的输出。

import asyncio
from agents import Agent, Runner

# Five domain specialists running in parallel: one per competitor to research.
competitor_specialist = Agent(
    name="competitor_research",
    instructions="Research one competitor in depth: pricing, product, positioning, recent news.",
    tools=[web_search, fetch_url, read_document],
)
synthesizer = Agent(
    name="synthesizer",
    instructions="Compose competitor briefs into a single comparative landscape report.",
)

async def parallel_topology(competitors: list[str]) -> str:
    # Each specialist runs independently: different Runner.run() calls.
    parallel_briefs = await asyncio.gather(*[
        Runner.run(competitor_specialist, f"Research: {c}", max_turns=15)
        for c in competitors
    ])
    briefs_text = "\n\n".join(r.final_output for r in parallel_briefs)
    final = await Runner.run(synthesizer, briefs_text)
    return final.final_output

注意这里用到的 3 个 SDK 原语：

• Agent.as_tool() 把 agent 包装为可调用工具，coordinator 保持控制，像调用函数一样调用 specialists。最适合 coordinator 需要组合输出并决定下一步的情况。
• handoff() 把 conversation 传给另一个 agent，控制权转移，SDK 管理上下文。最适合 specialist 需要接管面向用户交互的情况。
• 并行 Runner.run() + asyncio.gather() 独立运行 specialists：没有共享 conversation，没有 handoff。最适合 specialists 独立工作、输出由 synthesizer 组合的情况。

值得内化的 SDK 洞察： SDK 为多 agent 组合提供原生原语。你不需要手写 routing logic。as_tool() 用于分层组合；handoff() 用于顺序接管；并行 Runner.run() 用于 fan-out。在它们之间选择，本身就是一个模式选择决策，并且是 Q5 暴露出的同一组任务属性的下游结果。

部署组合。 多 agent 系统使用完整云栈，并额外需要一条关键纪律：

• 使用的 SDK 原语： Agent.as_tool() 用于分层组合（coordinator 保持控制）；handoff() 用于顺序接管（specialist 接管 conversation）；并行 Runner.run() + asyncio.gather() 用于 fan-out。每个 specialist 都是自己的 Agent，有自己的 tools= 列表和 instructions=。SDK 管理 handoff 中的上下文传递；你不手写 routing。
• 每个 specialist 都需要单 agent ReAct 的所有要求（harness、必要时 sandbox、R2、background worker）。
• Neon 中的 per-specialist runs / traces。 每个 specialist 的执行都是自己的 run；多 agent 系统是 parent run，引用 child runs。schema 需要 parent_run_id 和 agent_role 列。
• Routing audit logs。 记录每个 routing decision（哪个 specialist？什么 handoff format？）。多 agent 失败通常表现为 wrong-routing-decision 或 lost-context-on-handoff；没有显式 routing logs，调试几乎不可能。
• Per-specialist cost tracking。 多 agent 系统很容易失去对哪个 specialist 正在烧 token 的追踪。per-specialist cost attribution 能防止 runaway cost 隐藏在 aggregate metrics 里。

Bridge Worker 加 specialists。 如果多个 specialists 都运行代码，你可能需要多个 bridge-Worker configurations（为不同 specialists 的 tooling needs 使用不同 Manifests），或一个能按 specialist identity 路由的单 bridge Worker。复杂度上升比多数人预期更快：这就是部署拓扑成本开始主导的地方。

评测信号。 多 agent 的失败最难评测，因为失败可能发生在 3 层：specialist 内部、routing / coordination 中，或 integration 中：

Failure mode	评测会把它捕捉为什么
Specialist produces wrong output	每个 specialist role 上的标准 per-agent eval（把每个 specialist 当作独立 agent 来评测）
Coordinator routes to the wrong specialist	Routing-accuracy eval：给定任务，是否去了正确 specialist？需要 golden dataset 中有标注 routing examples
Handoff loses information (specialist B can't use specialist A's output)	Handoff-completeness eval：specialist B 是否拿到了 specialist A 提供的必要信息？起初人工标注；模式清晰后可自动化
Integration combines specialists' outputs incorrectly	针对 golden dataset 的 end-to-end eval；如果 specialists 单独通过但集成输出失败，问题在 integration
Specialists disagree without resolution	Inconsistency detector：并行 specialists 产出冲突答案；aggregator 要么明确解决冲突，要么暴露冲突
Coordination overhead exceeds work value	Cost-per-correct-output：如果多 agent 成本超过单 agent 3×，质量提升低于 20%，架构没有赚回开销

关键洞察是：多 agent evals 需要3 个独立 scoreboard：specialist quality、routing accuracy、integration quality。把它们混在一起会产生没有意义的 aggregate scores。 每个 specialist 的单独质量可能是 95%，routing accuracy 可能是 90%，integration quality 可能是 80%，端到端系统表现约 68%（乘积）。不分开，你就不知道该改哪一层。

团队在生产中常错在哪里。 把多 agent 系统当成一个整体。出错时，团队调试整个系统，而不是定位到某一层。解决方案：从第 1 天起强制 per-specialist tracing 和 per-handoff logging。没有这些，多 agent 调试会比单 agent 调试困难得多、慢得多，常常是大倍数差距；这也是该模式最大的隐藏成本之一。

打开以 Inngest 为例的 multi-agent operational-envelope 映射（第一遍可略读；实现时再打开）。

Operational envelope。 多 agent 是最依赖 Inngest operational envelope 的模式。几乎每个 envelope 原语都会发挥作用：fan-out 用于并行 specialists，per-key concurrency 用于 tenant fairness，priority 用于 tier-based queueing，HITL gates 用于 specialists 之间，replay 用于部分失败恢复。

• 使用的 Inngest 原语（本课程中最广泛的组合）：

  • Fan-out trigger pattern 用于并行 specialist execution：coordinator function 发出 N 个 specialist events；每个 specialist 是自己的 @inngest_client.create_function，有自己的 TriggerEvent。一个 event 唤醒 N 个 functions；它们并行运行；Inngest 独立追踪每个。
  • 每个 specialist run 一个 step.run，位于每个 specialist function 内，durability story 与单 agent ReAct（概念 10）相同，但乘以 N。
  • Per-key concurrency caps 防止任一 tenant 独占 specialist capacity：concurrency=[Concurrency(limit=5, key="event.data.tenant_id")]。per-key concurrency 是这里的承重模式。
  • Priority expressions 用于 tier-based fairness：Enterprise tenant runs 在队列中排在 Free tier 前面。
  • specialists 之间的 step.wait_for_event，当 handoffs 需要 human approval 时使用（例如 research → human-vetted research → analysis）。
  • Replay 用于部分失败恢复：当 5 个 specialists 中 3 个失败、2 个成功时，修复 failing-specialist 的代码并 replay；2 个成功 specialists 的输出保持 memoized。

• coordination-cost 洞察： 概念 13 指出 multi-agent 的 coordination overhead 是最大的隐藏成本。Inngest 原语吸收了大部分开销：routing logic 变成 events + triggers（没有手写 router）；handoff contracts 变成 event schemas（由 SDK 校验的 Pydantic models）；integration failures 变成 replay candidates（不是丢失工作）；per-specialist cost tracking 变成 per-function dashboard metrics。

• 量化节省。 没有 Inngest 的多 agent 系统通常需要：

  • 自定义 routing / dispatch layer（约 500-2000 行代码）
  • 自定义 retry / dead-letter handler（约 200-1000 行）
  • 带 timeouts 的自定义 HITL approval queue（约 500-1500 行）
  • Per-tenant rate limiting（约 300-800 行）
  • 自定义 replay / recovery tooling（约 500-2000 行）

  合计：2,000-7,000 行 operational-envelope code，必须测试、调试、维护。有了 Inngest，这会变成约 50-200 行 trigger declarations 和 step.run 调用。总成本差异会在生产级多 agent 系统生命周期中持续复合。

• 3 个 scoreboard 的可观测性仍然保留。 评测套件中的 per-specialist quality、routing accuracy 和 integration quality scoreboards（来自概念 13 的 eval signals）仍然适用；Inngest 的 structured traces 通过 OTel 流入 Phoenix，所以评测纪律不变。

cloud deployment 中「per-specialist tracing、routing audit logs、cost tracking per specialist」的要求会被 Inngest 部分吸收。你仍然需要 application-level traces（Phoenix），但 audit logs 和 cost tracking 会成为 Inngest dashboard 中 function-runs 的函数。组合关系是：Inngest 拥有 run-level operational data，Phoenix 拥有 trace-level evaluation data，Neon 拥有 application-level audit。三层各自负责最擅长的事情。

概念 13 的结论：多 agent 专家系统使用完整云栈，并加上 per-specialist tracing、routing audit logs 和 cost-per-specialist tracking。评测纪律要求 3 个独立 scoreboard（specialist quality、routing accuracy、integration quality），因为 aggregate scores 会掩盖哪一层失败。Coordination overhead 是最常被低估的成本；没有严格 per-specialist instrumentation，调试会比单 agent 难得多、慢得多。

第 3 部分后，用 AI 试一次。 你已经看到每种模式的部署成本，以及每种模式如何失败。选一个你真实可能使用的模式，让它具体化。打开 Claude Code 或 OpenCode session，粘贴：

「请挑出我下一步最可能构建的 agentic 模式（sequential workflow、single agent with ReAct and tools、planning with ReAct，或 multi-agent specialist system）。针对这个模式，带我走两件事。第一，部署拓扑：它需要哪些组件（HTTP service、durable state、file storage、sandboxed code execution、background workers、trace observability），哪些可以跳过？第二，我在生产中应该首先观察的单个 failure signal 是什么，以及在改架构前应该尝试的具体便宜修复是什么。请针对我的模式具体说明，不要泛泛而谈。」

你正在学习的东西：如果你不能说清楚一个模式的运行成本，以及你如何知道它坏了，那么模式选择还不是真实选择。这会把部署与评测组合从读过的内容，变成你能在白板上画出来的内容。

---

第 4 部分：失败信号与模式修订

你已经选择了一个起始模式。系统运行起来了。什么会告诉你模式错了？你该怎么办？ 第 4 部分覆盖 Bala Priya C 文章中的 5 个典型失败信号，并把它们映射到评测套件中的具体 eval 与 observability signals，同时给出不需要放弃架构的 targeted fixes。

概念 14：5 个 failure signals（以及各自含义）

文章识别了 5 个运行时症状，说明模式与任务不匹配。每个症状都有典型形状；看过两次后就能马上认出。

信号 1：ReAct loops 或 revisits solved work。 agent 在一次 run 中多次用相似参数调用同一个工具。或者它产出部分输出后，又从零重新推导。这个模式缺少结构或停止条件。 agent 不知道什么时候完成。

可观测性中它会出现在哪里：trace-length anomalies（多数 runs 需要 15 步，这次用了 40 步）；duplicate-tool-call patterns（同一个 customer_lookup 调用 5 次）；reasoning-loop signals（模型 reasoning text 出现「let me try this again」或等价表达）。

按频率排序，可能含义是：

• agent 的 prompt 没有定义工作什么时候「done」
• tool contracts 太宽松（多个工具都似乎能做同一件事；agent 在它们之间摇摆）
• 任务确实需要 planning（Q3 本应是 yes）

信号 2，planner 创建了计划，但 execution 偏离。 计划说「stage 1：research；stage 2：draft；stage 3：review」。执行完成 stage 1 后跳到 stage 3，再回到 stage 2。或者执行添加了 planner 没有包含的 stages。任务比 planning 押注假设的更不可预测。

可观测性中它会出现在哪里：plan-execution divergence metric（计算 planned stages 和 executed stages 的 edit distance）；reordering signals（stages 不按 dependency order 运行）；inserted-stage signals（执行包含计划中没有的 stages）。

按频率排序，可能含义是：

• 任务结构部分可表达，而不是完全可表达；planner 正确识别 major phases，但遗漏 adaptive sub-phases（使用 lightweight planning）
• planner 的训练与这个任务领域不匹配（用领域示例改进 planning prompt）
• 任务确实没有可表达结构（Q3 本应是 no；降级为 pure ReAct）

信号 3，reflection 没有改善答案。 critique pass 运行、产出 critique，agent refine，但 refined output 与原始输出不可区分。或者 refined output 更糟。reflection 押注失败了：criteria 含糊，或 critic 与 generator 共享盲点，或两者都有。

可观测性中它会出现在哪里：pre/post-reflection comparison scores（如果统计上不可区分，reflection 没在工作）；criterion-firing rates（哪些 criteria 触发 refinement？如果总是同一个，只有那个 criterion 有用）；critic-generator agreement rate（如果 critic 几乎总是通过，它在 rubber-stamping）。

按频率排序，可能含义是：

• criteria 太含糊，无法推动 refinement（让它们更具体且可检查）
• critic 和 generator 是同一模型且提示词相似（使用不同模型，或根本不同的 critic framing）
• 任务其实不需要 reflection（Q4 本应是 no；质量可能重要，但 criteria 不可检查）

信号 4，多 agent routing fails。 coordinator 把任务发送给错误 specialist。或者两个 specialists 产出 aggregator 无法调和的冲突输出。或者 specialists 之间的 handoff 丢失关键信息。coordination overhead 正在主导工作。

可观测性中它会出现在哪里：routing accuracy metric（将 coordinator 的 routing decisions 与 golden-dataset labels 比较）；handoff-completeness signals（specialist B 的输入没有引用 specialist A 输出中的关键内容）；integration-failure rate（specialists 单独通过，end-to-end 失败）。

按频率排序，可能含义是：

• specialists 角色重叠（澄清边界；合并重叠 specialists）
• handoff contracts 是隐式的（让它们显式化；要求 structured handoff formats）
• 任务其实不需要多 agent（Q5 本应是 no；收敛为 single agent）

信号 5，system feels complex but not better。 最难诊断，因为没有单一 eval signal 能捕捉它。架构有多层（例如 planning + reflection + multi-agent），但输出质量并不比更简单 baseline 可测量地更好。架构在解决一个审美问题，而不是任务瓶颈。

可观测性中它会出现在哪里：没有单一 observability signal。检测需要 baseline comparison：实现同一任务的更简单版本（single agent + ReAct + tools，无 reflection、无 multi-agent），并在 golden dataset 上测量质量。如果简单版本表现与复杂版本相差约 10% 以内，复杂架构没有赚回成本。

几乎所有情况下，可能含义是：

• 团队没有测试每一层是否合理，就叠加模式；overshoot 在多个决策中累积

概念 14 的结论：5 个典型 failure signals 指向 pattern-task mismatch：ReAct loops / revisits（缺少结构）、plan-execution divergence（过度结构化）、reflection not improving（criteria 含糊）、multi-agent routing failures（过度拆分）、system-feels-complex-but-not-better（累积 overshoot）。每个信号都有典型 observability shape。识别信号是第一步；修复不总是架构性的，有时只是收紧 prompt 或澄清 contract。

概念 15：不放弃架构的 targeted fixes

识别 failure signal 并不总意味着重写架构。大多数修复在 prompt、contract 或 instrumentation 层，而不是 architecture 层。 本概念把每个 signal 映射到最便宜的 fix-first 选项。

Signal	最先尝试的最便宜修复	如果不奏效	需要的架构变化
ReAct loops/revisits	添加显式 stop conditions（"you have completed the task when…"）和 tool boundaries（"use X for purpose Y; do not use X for Z"）	改进 tool contracts（更好的描述、更清晰返回类型）	添加 planning layer（升级到概念 11 的模式）
Plan-execution divergence	切换到 lightweight planning（更少、更宽的 stages）	用领域特定示例改进 planner prompt	降级到 pure ReAct（概念 10）
Reflection not improving	让 criteria 更具体且可检查（数值阈值、schema validation、显式规则）	使用不同模型做 critic；或使用显式检查工具（parser、validator）	如果没有改善出现，完全移除 reflection
Multi-agent routing fails	对已知 cases，把 coordinator 从 LLM-based routing 切换为 deterministic routing	让 handoff contracts 显式且结构化（Pydantic models，不是 free-text）	合并重叠 specialists；如果 Q5 实际不成立，收敛为 single agent
Complex-but-not-better	移除最上层（最近添加的 pattern）并测量	再移除下一层；迭代	回到有强 baseline 的 single agent；只有有证据时才重建

原则： 在能工作的最小范围内修复。收紧 prompt 比改 tool contract 便宜。改 tool contract 比改架构便宜。改架构比重写便宜。大多数 failure signals 可以在 prompt 或 contract 层处理，不要先去拧 architecture knob。

例外： 如果某个 failure signal 在 prompt 和 contract 修复后仍反复出现，那就是架构确实错误的证据。区分「我可以继续 patch」和「我一直 patch，它又以新方式失败」。后者就是重新走模式选择的信号。

概念 15 的结论：failure signals 不总需要架构变化。大多数可以在 prompt 层（stop conditions、criteria specification、role boundaries）或 contract 层（tool descriptions、handoff structures、routing logic）修复。架构变化是最后手段，不是第一动作。例外是：prompt 和 contract 修复后仍反复失败，说明模式本身错了；这时重新走决策树。

概念 16：决策树什么时候会错

决策树很好。它不是不会错。下面是树的第一答案会错的 3 种情况，以及处理方法：

情况 1，任务属性在部署后变化。 原本稳定的 workflow 变成 adaptive（业务增加 20 个 edge cases）。原本需要专业能力的工作变成 commodity（LLM 变强，generalist 现在能处理过去需要 specialist 的工作）。真实示例：一个从顺序流水线开始的客户支持 workflow（extract → classify → route → respond），在团队增加 personalization、history-awareness 和 tone-matching 后变成 adaptive。原始模式现在错了，但系统已经在生产中。

修复：概念 14 的 failure-signal observability 应该捕捉这一点。当 workflow paths 开始失败，因为真实输入不再匹配 workflow 预期形状，那就是信号。用新的任务属性重新走决策树。不要因为原始选择已经部署，就假装它仍然正确。

情况 2，不同 sub-tasks 需要不同模式。 Maya 的 Tier-1 Support agent 处理 routing、lookups、refunds、escalations。有些是 workflow-shaped（lookup：deterministic）。有些是 ReAct-shaped（refund investigation：adaptive）。单 agent ReAct 模式可以处理全部，但只是够用，不是优秀。修复：识别这是一个多模式组合机会。顶层 coordinator 路由到 pattern-specific sub-systems：lookup 用顺序工作流，investigation 用 ReAct + tools，复杂多步骤 disputes 用 planning。这个组合是多 agent，但 specialists 不是按角色划分，而是按模式划分。

情况 3，约束改变答案。 决策树假设你可以选择任何适配模式。有时你不能。硬延迟预算排除 reflection。硬成本预算排除多 agent。硬简单性要求排除 planning。当约束排除决策树会选择的模式时，你要么改变约束、改变任务范围，要么接受更差适配。

修复：把 constraint-driven pattern choices 作为单独决策显式记录。记录：「决策树指向 multi-agent，但我们因为 cost ceiling 选择 single-agent。已知限制：specialization-driven failures 会更常见。」这样 constraint-driven choice 变得可见且可回访；约束变化时，你知道要重新考虑什么。

概念 16 的结论：决策树是起点，不是永久答案。3 种情况需要重新走树：任务属性在部署后变化（通过 failure-signal observability 捕捉）、不同 sub-tasks 需要不同模式（组合多个模式）、约束排除树的答案（显式记录 constraint-driven choice）。模式选择是迭代的，不是一次性的。

概念 16.5：Anti-pattern gallery：常见错误选择以及该怎么办

第 5 部分会走正确模式选择的 worked examples。在这之前，先看反面：常见错误选择和各自更好的替代方案。识别反模式本身就是一项技能：即使学生内化了决策树，在架构诱惑很强时仍可能掉进 pattern-overshoot 或 pattern-undershoot。

图中的不对称（5 个 overshoot anti-patterns 对 3 个 undershoot）反映了生产系统中的真实频率。Overshoot 更显眼，因为复杂模式更适合做 demo；undershoot 更危险，因为失败模式更微妙。两者都同样值得在设计评审时抓住。下面表格给出图库的完整文字：

Bad choice	为什么失败	更好的起始模式
Multi-agent for simple content generation（例如，为单条 LinkedIn post 用 3 个 agents：researcher + writer + reviewer）	Coordination overhead 远超 specialization gain。「researcher」输出一段文字，再由「writer」总结。Routing failures、handoff format mismatches、3 倍 tokens，却没有可测量质量提升。	Single agent + ReAct + tools（概念 10），或者如果内容形状固定，用 sequential workflow（概念 9）。只有当 Q5 真的触发时才使用 multi-agent。
ReAct for fixed invoice processing（extract → validate → store → notify）	agent 偶尔跳过步骤，偶尔重新校验已完成工作，偶尔编造工具调用。5% runs 耗尽 step budget。团队给 prompt 加「stop conditions」，治疗症状而不是架构错配。	Sequential workflow（概念 9）。路径已知且稳定；LLM-driven loop 是错误工具。
Planner for open-ended debugging（planner 产出 5-stage plan；execution 马上偏离）	任务结构无法提前表达。planner 产出的计划到 stage 2 就变错。Plan-execution divergence 主导 trace。团队要么无休止收紧 planner，要么把计划当装饰。	Single agent + ReAct + tools（概念 10）。Pure ReAct 处理 shape 和 content 都未知的任务。
Reflection on tasks with vague quality criteria（marketing copy、conversational responses、subjective content）	critic 和 generator 共享盲点。Critique 变成 rubber-stamping。延迟翻倍；质量不变。更糟：团队获得「AI 已检查」的虚假信心。	要么完全移除 reflection（最常见正确答案），要么用 human review 替代 LLM reflection（概念 12）。LLM reflection 只适用于可检查标准。
One giant agent for many domains（billing + technical + account + refund + sales，全塞进一个带 4,000-token system prompt 的 agent）	Context overflow、role confusion、tool-routing errors 级联。Reflection 略有帮助，但修不了根因。agent 用 billing policy 回答 technical questions，反之亦然。	Multi-agent specialist system（概念 13），按 domain 划分 specialists，coordinator 按 intent classification 路由。Q5 的 specialization claim 在这里确实触发。
Adding planning to a stable workflow（planner 因为任务相同而每次产出同一计划）	每次 run 都为没有贡献的额外 LLM 调用付费。当输入稍微不寻常时，planner 产出略不同计划，团队现在还得调试「为什么 planner 走了不同路径？」	Sequential workflow（概念 9）。当路径固定时，不需要 planning，直接写下路径。
Pure single-agent for tasks needing massive context（一个 agent 把 20 份源文档、3 个知识库和一个 database schema 全塞进 prompt）	Context window degradation。上下文越大，agent 推理越弱；模型会漏掉你以为它一定能看到的东西。	带 focused contexts 的 multi-agent specialist system（概念 13）。每个 specialist 只加载自己需要的上下文；synthesizer 组合输出。Q5 的 context claim 在这里确实触发。
Skipping reflection on outputs that genuinely need verification（SQL queries to production、legal drafts to clients、code changes to repos）	细微错误出货。团队事后加测试，但事后测试抓到的错误少于在生成时捕捉。	在核心模式上添加 reflection layer（概念 12）。当 criteria 确实可检查时，reflection 真有价值。Q4 触发；不要跳过。

反模式图库背后的规律： 大多数错误选择由审美吸引导致 pattern-overshoot（multi-agent 看起来厉害、planning 看起来严谨、reflection 看起来谨慎）。另一个更小但同样重要的子集由简单性偏好导致 pattern-undershoot（一个大 agent、对 workflow tasks 用 pure ReAct、对可检查输出不做 reflection）。决策树旨在暴露两种错误：通过询问任务属性，而不是模式偏好。

锁定模式选择前的有用自检： 「如果一位高级工程师 review 我的选择，最可能提出什么反对意见？」如果你无法预测并回应这个反对意见，你可能还没有做出有原则的选择。

概念 16.5 的结论：模式选择最常因 overshoot（比需要更复杂）失败，较少但同样有害地因 undershoot（比需要更简单）失败。anti-pattern gallery 命名了两类失败的常见形状。内化这些能加快决策树纪律；在构建前识别自己 draft architecture 中的反模式，正是框架产生的实践技能。见本课程末尾的一页 design-review template。 它包含一个显式 anti-pattern check（「如果高级工程师 review 这个选择，会反对什么？」），把这门纪律变成团队设计评审中的可操作动作。

---

第 5 部分：决策实验室

第 5 部分会对 5 个真实任务走决策树。每个 Decision 都是一个 worked classification：任务、5 个问题的回答、得出的模式、部署拓扑草图，以及要观察的评测信号。重点不是正确答案，而是看到这门纪律如何应用。

每个 Decision 都遵循同一形状：

• 任务（一段话）
• 走树（用任务特定推理回答 5 个问题）
• 模式选择与理由
• 部署拓扑草图（哪些云组件、Neon 中新增什么表、什么 bridge-Worker config）
• 要观察的评测信号（哪些 eval patterns、哪些 Phoenix evaluators）
• 模拟路径提示，给没有学过 deployment 和 eval 课程的读者

决策 1：Maya 的 Tier-1 Support agent

任务。 一个 customer-support agent 处理 incoming queries。agent 可以：查 account information、查 transaction history、查 policy rules、搜索 knowledge base、在权限范围内发起 refunds，并在权限超出或 case 含糊时 escalate 给 human review。agent 与客户保持对话式交互。

轮到你。 在继续读之前，先对这个任务走 5 个问题。先承诺一个模式，再对照 worked answer 检查自己。（或者把任务粘贴给你的 AI，让它用 Q1 到 Q5 考你，并在你的推理薄弱时反驳。）

先自己走一遍，再打开 worked answer。

走树。

Q1：solution path 能否提前定义？不能。客户 query 差异巨大：「where's my refund?」需要 lookup；「I was charged twice」需要 investigation；「I want to cancel」可能需要 account changes；「can you explain my bill」需要 policy lookup 和 explanation。路径未知。

Q2：N/A（Q1 是 no，所以跳过 Q2）。

Q3：task structure 是否能在执行前表达？不能。这里没有可表达的「stages」；只有调查，完成时自然完成。agent 可能做一次 lookup 后回复，也可能做 5 次 lookup 加 3 次 policy checks。没有清晰 stage structure。

Q4：quality 是否比 speed 更重要？混合。speed 很重要，因为客户在实时对话中等待；quality 也重要，因为错误 refund 决策会让业务损失钱。但「good response」的 evaluation criteria 无法实时检查。 它涉及对客户情况是否被妥善处理的细腻判断。Reflection 不适合这里。

Q5：是否存在 specialization、context 或 scale bottleneck？边界情况。agent 确实需要处理 billing、technical、account 和 refund issues，看起来像 specialization case。但： 大多数客户问题跨类别重叠，specialist routing 带来的 handoff friction 会超过 specialization benefit。single agent 是正确选择。

模式选择：Single agent + ReAct + tools。 概念 10 的模式。

部署拓扑草图。 这正是 customer-support Worker 的 cloud deployment 已经构建的东西。完整栈：ACA 上的 FastAPI，Neon 用于 sessions、runs 和 traces，R2 用于任何 attached documents，Cloudflare Sandbox 通过 bridge Worker 提供给 agent 偶尔生成 refund-documentation files 时使用的 apply_patch 工具，超过 30 秒的 runs 使用 background worker。与该部署已经交付的内容相比，不需要部署变化。

要观察的评测信号。 ReAct 的典型失败：

• Trace-length anomalies（Phoenix dashboard）
• Tool-call duplication（agent 3 次查询同一 account）
• Reasoning-action divergence（Phoenix tool-correctness evaluator）
• Premature termination（agent 太早说 "I can't help"）
• Step-budget exhaustion（agent 循环超过 25 步仍未产出输出）

生产中最可能的失败模式： agent 会在含糊 refund cases 上循环。修复：添加显式 stop conditions（「如果你在 3 次 lookup 内无法确定正确 refund amount，就 escalate」），并澄清「继续调查」与「escalate to human」之间的边界。

Operational envelope。 Maya 的 setup 是 customer-support agent 的 canonical Inngest 组合：

• Trigger： TriggerEvent(event="customer/email.received")，email-ingestion webhook 发出事件；function 为每封 customer email 唤醒。
• Durability： 把 Runner.run(support_agent, ...) 包进单个 step.run("agent-loop", ...)。中途崩溃 → 整个 agent run 重试；loop 内部 sub-steps 是 SDK-internal，不单独持久。
• Escalation 上的 HITL： escalate_to_human 工具发出 refund/approval.requested，function 通过 step.wait_for_event 挂起最长 4 小时。等待期间消耗 0 compute。人类通过 Slack approve；function 带 verdict 恢复。
• Concurrency： concurrency=[Concurrency(limit=10, key="event.data.customer_id"), Concurrency(limit=50)]，每个客户最多 2-3 个并发 runs（愤怒客户不能饿死其他人），全局 50（保护 OpenAI rate limit 和 Neon connection pool）。

决策 1 的模拟路径提示。 即使没有 deployment 和 eval 课程，你也可以在纸面上完成这个练习：为 Maya 的任务走 5 个问题，证明模式选择合理，并画出 agent 需要哪些工具（account lookup、transaction lookup、policy search、refund issuance、escalation）。决策 1 教的是分类纪律；部署细节会加深它，但不是内化框架的必要条件。

决策 2：Incident response agent

任务。 一个 on-call agent 接收 alerts（来自 monitoring systems、customer reports 或 internal teams）并执行初始 incident response：检查 service health、关联最近 deploys、识别可能 root cause、在适用时运行 remediation runbook，并在情况 novel 或 severe 时 escalate 给 human on-call。agent 必须产出清晰 incident report。

轮到你。 在继续读之前，先对这个任务走 5 个问题。先承诺一个模式，再对照 worked answer 检查自己。（或者把任务粘贴给你的 AI，让它用 Q1 到 Q5 考你，并在你的推理薄弱时反驳。）

先自己走一遍，再打开 worked answer。

走树。

Q1：solution path 能否提前定义？部分可以。有一个标准结构：「check service health, correlate deploys, identify cause, attempt remediation, escalate if needed」。但具体路径取决于实际发生了什么。 service A 的 latency spike 可能导向「rollback recent deploy」；service B 的 500-error spike 可能导向「restart pod」；customer-reported issue 可能导向「investigate user-specific data flow」。路径在 step level 未知，但在 stage level 有结构。

Q2：N/A。

Q3：task structure 是否能在执行前表达？能。 阶段清楚：triage → diagnose → remediate → report。每个 incident 都经过这些阶段，即使每个阶段内部具体工作不同。结构可表达。

Q4：quality 是否比 speed 更重要？对 incident response 来说，speed 极其重要：incident 每多一分钟都会让业务付费。但 quality 也重要，因为错误 remediation 会让情况更糟。在执行前对 remediation steps 做 reflection 是合理的。 一个快速 critique pass 问「这个 remediation 安全吗？是否匹配 incident 的真实症状？」值得付出延迟。对 remediation decisions 添加 reflection。

Q5：是否存在 specialization、context 或 scale bottleneck？没有。一个 agent 访问 monitoring、deploy history、runbook library 和 remediation tools，就能处理它。不要多 agent。

模式选择：Planning + ReAct execution，并在 remediation steps 上加 reflection。 概念 11 + 12 叠加。

部署拓扑草图。 基于 ReAct 部署（概念 10），再加 plan persistence（概念 11）。具体新增：

• 新 Neon 表：incidents（incident_id, severity, plan, current_stage, remediation_history）
• plan 显式存储，并随着 stages 完成而更新
• remediation 上的 reflection 作为单独 agent 运行（建议使用不同模型，例如 Claude-instance critique GPT-instance，或反过来，避免盲点重叠）
• background worker pattern 强制需要（incident runs 可能需要 5-15 分钟）

要观察的评测信号。

• Plan-execution divergence（计划是否匹配实际发生的事情？）
• Remediation 上的 reflection effectiveness（critique 是否抓住过不安全 remediation？如果几个月都没有，reflection 可能在 rubber-stamping）
• Time-to-resolution metric（incident response 以速度评判；跟踪并对回归告警）
• Escalation accuracy（agent 该 escalate 时是否 escalate？该 remediate 时是否 remediate？）

生产中最可能的失败模式： planner 为简单 incidents 产出过度详细计划，增加延迟。修复：用合适 plan granularity 的示例训练 planner：清晰 incident 用短 plan，含糊 incident 用长 plan。计划的价值不在于全面，而在于与情况尺寸匹配。

Operational envelope。 Incident response 会用到几乎每个 Inngest primitive：cron、events、fan-out、durability、HITL、replay：

• Triggers： 双 trigger，TriggerCron(cron="*/5 * * * *") 用于 proactive health checks，TriggerEvent(event="incident/alert.fired") 用于 reactive incidents。同一个 function shape 处理两者。
• 每阶段 durability： planning stage 和每个 remediation step 都用一个 step.run；如果 remediation 中途失败，前面 stages 保持 memoized。
• Remediation 上的 HITL： 在 planner 输出与执行之间，step.wait_for_event("await-remediation-approval", timeout=timedelta(minutes=15)) 作为 human reviewer 的 gate。timeout 很紧，因为 incidents 对时间敏感。
• False-positive bug fixes 的 replay： 当某个 remediation script 有 bug，导致 incidents 以特定方式失败时，修复脚本并从 Inngest dashboard 批量 replay failed incidents。不需要手动重新 triage incident。

决策 2 的模拟路径提示。 这是第一个引入模式组合的 Decision（planning + reflection）。即使在纸面上，练习也很有价值：注意添加 reflection 的选择不是单独来自 Q4，而是来自 Q4 具体应用到 remediation step。Reflection 很少是 all-or-nothing；它常常叠加在特定 high-stakes outputs 上。

决策 3：Market research agent

任务。 给定一个 topic（「competitive landscape in agentic AI middleware」）和 research brief（关键问题、深度要求、deadline），agent 产出 research report。工作包括：识别相关来源、搜索多个数据库、阅读并抽取文档、跨来源比较 claims、起草 findings，并产出最终报告。

轮到你。 在继续读之前，先对这个任务走 5 个问题。先承诺一个模式，再对照 worked answer 检查自己。（或者把任务粘贴给你的 AI，让它用 Q1 到 Q5 考你，并在你的推理薄弱时反驳。）

先自己走一遍，再打开 worked answer。

走树。

Q1：solution path 能否提前定义？不能。查哪些来源、调查哪些竞争对手、运行哪些分析，都取决于过程中发现什么。路径未知。

Q2：N/A。

Q3：task structure 是否能在执行前表达？能。标准 research-report 形状：gather data → analyze → synthesize → draft → review。虽然具体来源和分析未知，major phases 清楚。结构可表达。

Q4：quality 是否比 speed 更重要？是，而且很强。research reports 会被决策者阅读；事实错误和薄弱分析有真实后果。质量标准部分可检查：「all claims are sourced」、「competitor analysis covers each major player」、「synthesis answers the brief's questions」。Reflection 合理，尤其适用于 synthesis 和 final draft。

Q5：是否存在 specialization、context 或 scale bottleneck？很可能有，主要是 context。深入研究需要加载大量 source material；把这些都放进一个 agent 的 context window，会有 reasoning degradation 风险。把工作拆成 per-source research-and-summarize agents，产出 focused briefs，再组合这些 briefs，是正确模式。因为 context-management 原因使用多 agent。

模式选择：Multi-agent specialist system，顶层带 planning，research specialists 内部用 ReAct，并在最终 synthesis 上用 reflection。 组合概念 11、13 和 12。

部署拓扑草图。 完整云栈加多 agent 新增项（概念 13）：

• Neon 中的 parent-run + per-specialist run structure（parent_run_id, agent_role）
• 针对哪个 specialist 收到哪个 source 的 routing audit logs
• per-specialist cost tracking（research agents 阅读 50 页 PDF 时会快速烧 token）
• bridge Worker 处理 specialists 共享的 document-reading tools
• aggregator agent 从共享 Neon 表读取 specialists 存放的 summaries

要观察的评测信号。

• 3 个独立 scoreboards：per-specialist research quality、routing accuracy（正确 specialist 是否拿到正确 source？）、integration quality（final report 是否很好综合 specialists findings？）
• 顶层 plan 上的 plan-execution divergence
• final synthesis 上的 reflection effectiveness
• Cost-per-correct-output（multi-agent + reflection 很贵；需要跟踪并证明合理）

生产中最可能的失败模式： specialists 产出优秀 individual briefs，但 aggregator 无法干净 synthesize，因为 briefs 使用不一致格式或术语。修复：强制 structured handoff formats（brief structure 使用 Pydantic schemas），让 aggregator 收到形状统一的输入。

Operational envelope。 Market research 是本课程最核心的 fan-out 示例，正是 Inngest flow-control primitives 为之设计的模式：

• Fan-out trigger pattern： coordinator function 为每个 competitor 发出一个 research/competitor.research 事件；每个事件触发独立 function run。N 个 competitors → N 个 parallel function runs，全部独立追踪，全部独立持久。
• Per-tenant concurrency cap： competitor-research function 上的 concurrency=[Concurrency(limit=5, key="event.data.tenant_id")]，防止某个 tenant 的「research 50 competitors」请求独占系统。
• Per-specialist durability： 每个 competitor-research run 有自己的 step.run 调用（web search、document fetch、brief generation）；research 中途崩溃只重试失败 step，而不是整个 research run。
• Aggregation as a separate function： 当所有 specialist runs 完成（Inngest 发出 "all done" events）后，由 research/landscape.synthesize 触发的 synthesizer function 读取 briefs 并组合最终报告。通过 events 解耦；没有 shared state。
• Cost-per-specialist visibility： Inngest 的 per-function dashboard 显示每个 competitor 的 token spend；异常值（competitor X 成本是其他的 5×）会立刻可见。

决策 3 的模拟路径提示。 这个 Decision 展示的是模式组合：multi-agent 不是对其他模式的替代；它是它们的组合。planning agent 使用 planning；research specialists 使用 ReAct；synthesis agent 使用 reflection。Multi-agent 是拓扑；拓扑内部的模式仍然是同一套 5 种模式。

决策 4：Enterprise onboarding agent

任务。 当新的 enterprise customer 注册后，agent 运行 onboarding workflow：provision tenant（创建 accounts、databases、configuration）、填充 seed data、邀请 administrators、安排 kickoff meetings、发送 welcome materials。工作涉及多个确定性 provisioning steps 和少量个性化沟通。

轮到你。 在继续读之前，先对这个任务走 5 个问题。先承诺一个模式，再对照 worked answer 检查自己。（或者把任务粘贴给你的 AI，让它用 Q1 到 Q5 考你，并在你的推理薄弱时反驳。）

先自己走一遍，再打开 worked answer。

走树。

Q1：solution path 能否提前定义？能。 Onboarding 有固定序列：provision → configure → seed → invite → schedule → send-welcome。每次 onboarding 都按这个顺序经过这些步骤。某些步骤内容会个性化（welcome message 引用客户名称和行业），但 step sequence 不变。路径已知。

Q2：workflow 是否跨 runs 固定稳定？是。 每个 enterprise customer 都遵循同一个 onboarding workflow。稳定。

Q3、Q4、Q5：N/A 或 no。因为 workflow 固定，决策树在 Q2 终止。

模式选择：Sequential workflow。 概念 9。

部署拓扑草图。 最小云栈：

• ACA 上的 FastAPI
• Neon 用于 onboarding state（哪个 customer 在哪个 step）
• R2 用于任何 documents（welcome PDFs、onboarding guides）
• 个性化步骤嵌入 LLM 调用（welcome message generation、如果客户请求则生成 account-name suggestions）
• 不需要 sandbox。 不需要 bridge Worker。 不需要面向长时间 agentic reasoning 的 background-worker pattern（不过 workflow 本身可能作为 background job 运行以应对规模）。

这是明显比完整云栈便宜的部署，因为任务不需要 cloud deployment 的大部分复杂度。

要观察的评测信号。

• Step-level correctness（每个 provisioning step 成功；extraction 返回 valid schemas）
• Workflow completion rate（多少比例 onboarding 成功完成？）
• Personalization quality（LLM-generated welcome messages；Phoenix 可以评估 tone、factual accuracy）
• Failure mode：workflow steps 被应用到错误输入（validation gaps）

生产中最可能的失败模式： edge-case enterprise（不寻常行业、特殊 compliance requirements）不适合标准 workflow。修复：要么（a）为 edge case 添加显式分支（如果 edge cases 很少），要么（b）承认 workflow 正在变成 variable，并考虑升级到 ReAct + tools（如果 edge cases 激增）。持续观察这个转变：workflows 常常从稳定开始，逐渐变成 adaptive。

Operational envelope。 Enterprise onboarding 是本课程中最干净的 Inngest 顺序工作流示例：每一步都是一个 step.run，没有 agentic 复杂度：

• Trigger： TriggerEvent(event="customer/enterprise.signed_up")，当 deal 在 CRM 中 closed 时触发。
• 每个 onboarding step 一个 step.run： step.run("provision-tenant", ...)、step.run("configure-defaults", ...)、step.run("seed-data", ...)、step.run("invite-admins", ...)、step.run("schedule-kickoff", ...)、step.run("send-welcome", ...)。每个 step 都持久；第 4 步崩溃 → 第 1-3 步 memoized。
• 不需要 HITL： 标准路径中 onboarding 完全自动化；没有 step.wait_for_event 调用。
• step.sleep 用于延迟动作： step.sleep("wait-2-days-before-followup", timedelta(days=2)) 安排一个 onboarding 完成 2 天后的 follow-up，等待期间消耗 0 compute。
• Cron pairing： 一个独立 cron-triggered function（TriggerCron("0 9 * * *")）每天扫 customer database，找出 stalled onboarding（某一步失败且 retries 用尽）；cron function 为 stuck cases 发出 recovery events。

这是明显比其他模式便宜的部署，Inngest 让成本纪律可见：function dashboard 展示逐步骤成功率和逐步骤成本，因此你能看到哪个 onboarding step 是瓶颈。

决策 4 的模拟路径提示。 这个 Decision 很重要，因为它是 agentic patterns 的反例。任务不需要 agentic reasoning。 带嵌入 LLM 调用的 workflow 更便宜、更可靠、更容易调试。workflow 能解决时，不要选择 ReAct。 这是决策树教授的最重要纪律。

决策 5：Coding agent（advanced track）

任务。 一个 coding agent 收到 feature request 并产出可工作的实现：阅读现有 codebase、设计变更、写代码、写测试、运行测试、修复失败，并产出一个可供人类 review 的 PR。codebase 很大，变更可能复杂，correctness 很重要。

轮到你。 在继续读之前，先对这个任务走 5 个问题。先承诺一个模式，再对照 worked answer 检查自己。（或者把任务粘贴给你的 AI，让它用 Q1 到 Q5 考你，并在你的推理薄弱时反驳。）

先自己走一遍，再打开 worked answer。

走树。

Q1：solution path 能否提前定义？不能。Coding work 包含持续发现：codebase 里有什么、现有代码如何组织、测试揭示哪些 edge cases。路径未知。

Q2：N/A。

Q3：task structure 是否能在执行前表达？部分可以。 高层形状清楚：理解需求 → 理解 codebase → 设计变更 → 实现 → 测试 → 修复 → 产出 PR。但： 对复杂变更，design phase 可能迭代（design → discover constraint → revise design → re-discover constraint）。可表达，但内部需要适应。

Q4：quality 是否比 speed 更重要？是，非常重要。进入生产环境的代码有真实后果。质量标准可检查：tests pass or fail、type checks pass or fail、linter passes or fails、code review 识别具体问题。Reflection 非常合理。

Q5：是否存在 specialization、context 或 scale bottleneck？specialization 和 context 都真正存在。 Coding 至少涉及 3 个不同技能集：code generation（写好代码）、security review（抓漏洞）、documentation（解释变更）。每个都能从聚焦 agent 受益。多 agent 合理。

模式选择：Multi-agent specialist system，顶层带 planning，specialists 内部用 ReAct + tools，并对 code outputs 做显式 reflection。 组合其他 4 种模式。

部署拓扑草图。 完整云栈加多 agent 扩展：

• Coordinator agent：接收 feature request，产出带 stages 的 plan（design → code → review → document）
• Coder specialist：ReAct + tools（读 codebase、写文件、运行测试）。重度使用 sandbox（运行测试、执行代码）。bridge Worker 强制需要。
• Reviewer specialist：ReAct + tools（读取 coder 输出、运行 security checks、运行 linters）。较轻 sandbox 使用。
• Documentation specialist：更简单，可能是 sequential（extract changes → generate docs）。
• coder 最终 PR 上的 reflection layer（是否通过全部 tests？是否匹配 requirement？）。
• Neon 中的 per-specialist runs；routing audit logs；per-specialist cost tracking（coder 将主导成本）。

要观察的评测信号。 全部多 agent 的 3 个 scoreboards，加上 reflection metrics。特别关注：

• Code-correctness eval（生成代码是否通过 tests？）
• Security-review effectiveness（reviewer 是否抓到 vulnerabilities？false-positive rate 也重要）
• Plan-execution divergence（coordinator 的 plan vs. 实际 shipped 内容）
• Cost-per-PR（这是昂贵模式；确保它赚回成本）

生产中最可能的失败模式： reviewer specialist 成为瓶颈，要么过严（因为小风格问题拒绝有效代码），要么过松（让有真实 bug 的代码通过）。修复：为 reviewer 的 decision 制定显式 criteria，并用单独 eval 将 reviewer judgments 与人类 reviewer 对同一代码的 judgments 对齐评分。

Operational envelope。 coding agent 使用每个 Inngest primitive；这是证明完整 operational envelope 合理的模式：

• Triggers： TriggerEvent(event="github/issue.assigned_to_agent")，当 issue 被分配时触发；或者 Slack 中的 chat command 发出事件。
• Fan-out coordination： coordinator function 将 feature 拆成 stages，然后向 specialist functions 发事件（coding/specialist.code、coding/specialist.review、coding/specialist.docs）。每个 specialist 都是自己的 function，有自己的 concurrency 和 durability。
• 每次 file edit 一个 step.run： coder specialist 把每次文件修改包进 step.run("edit-{path}", ...)，这样多文件编辑中途崩溃不会丢失已完成编辑。memoization 在这里尤其有价值：部分完成后重新运行 LLM 生成的代码变更成本很高，而且有偏离原计划的风险。
• PR merge 上的 step.wait_for_event： agent 产出 PR 后，function 通过 step.wait_for_event("await-human-merge-approval", timeout=timedelta(days=2)) 挂起。人类在 GitHub review 并 approve；function 恢复执行 post-merge cleanup。
• Per-tenant concurrency： coder specialist 上的 concurrency=[Concurrency(limit=2, key="event.data.tenant_id")] 防止一个 tenant 独占 coding capacity。（Coding 很贵；per-tenant caps 很关键。）
• 用于 tier-based fairness 的 priority： Enterprise tenants 的 coding tasks 在队列中跳到 Free-tier 前面（priority=Priority(run="100 - (event.data.tier_priority * 100)")）。
• 部分失败的 replay： reviewer specialist 因可修复原因拒绝代码时，coder 修复并重新触发 review event；function dashboard 显示每个 PR 的 iteration history。
• 用于 safety windows 的 step.sleep： merge 后用 step.sleep("await-tests-stable", timedelta(hours=2)) 等待 2 小时 CI runs，确认变更没有破坏下游 tests 后，agent 再标记工作完成。

决策 5 的模拟路径提示。 这是最难的 Decision，因为任务确实需要每种模式组合在一起。这里的练习不是记住哪些模式适用，而是看到决策树如何系统地识别要组合哪些模式，以及在哪里组合。coding agent 不是因为复杂才「advanced」；它 advanced 是因为模式组合的纪律需要练习。

---

轮到你：第六个决策由你完成（没有答案）

上面的五个 Decisions 都有 worked answer 可以核对。这个没有。请从你自己的工作中取一个真实任务，也就是你真的可能为它构建 agent 的任务，然后自己完整走一遍。

你的任务。 用一句话写清楚：输入是什么，agent 产出什么，以及什么状态算 done。

走完五个问题，并在继续前提交每个答案： Q1 solution path、Q2 workflow stability、Q3 task structure、Q4 checkable quality、Q5 measurable bottleneck。然后预测 senior engineer 最可能提出的 objection，写下来，并 defend 或 simplify 你的选择。

---

第 6 部分：诚实前沿

概念 17：Cost 和 latency 是架构约束，不是 afterthoughts

到目前为止，本课程把模式选择讲得仿佛成本和延迟是次要因素。在生产环境中，它们常常是主要因素。概念 17 会明确命名每种模式的成本和延迟 profile，让你带着预算约束走决策树。

每种模式的成本 profile（粗略数量级，假设 GPT-5 级别定价）：

Pattern	每个任务成本	成本驱动因素
Sequential workflow	1×（baseline）	LLM 调用次数（通常每个 workflow 1-3 次）
Single agent + ReAct	3-10×	ReAct iterations 数量（每个 loop 调用一次模型）
Planning + ReAct execution	5-15×	Planning 调用 + per-stage ReAct loops
Single agent + reflection	underlying pattern 的 2-3×	Critique + refinement passes
Multi-agent specialist	5-20×	specialist runs 数量 + coordinator + integration

这些数字是示意性的，不是精确值。重要的是比例：同样任务量下，一个叠加 reflection 的多 agent 系统，成本可能比顺序工作流高 30-60×。 如果这个倍数由质量证明，没问题。如果由审美证明，那就是等着发生的预算灾难。

每种模式的延迟 profile：

Pattern	延迟	驱动因素
Sequential workflow	最低（约 1-5s）	确定性步骤 + 顺序 LLM 调用
Single agent + ReAct	中等（约 10-30s）	每个 loop 一次模型调用；loops 可能拉长
Planning + ReAct	中高（约 30-90s）	Planning 调用 + 顺序 stage execution
Single agent + reflection	underlying pattern 的 2-3×	Critique + refinement 增加乘法延迟
Multi-agent specialist	可变	并行执行有帮助；coordination 增加开销

与决策树的集成。 Q4（quality vs. speed）隐含处理 latency。Q5（specialization / scale）隐含处理 cost。 但决策树不会显式说「因为你的延迟预算是硬约束，答案要比树建议的模式少一层复杂度」。这是树之上的 constraint-layer decision。

实践纪律： 走决策树前，先写下你的 latency 和 cost budgets。如果树选出的模式违反任一预算，你有 3 个选项：

1. 改变约束。 获取更多预算、提高延迟容忍度，或接受更慢交付。
2. 改变范围。 减少系统必须做的事，让较简单模式能够处理。
3. 接受更差适配。 使用较简单模式，并接受更复杂模式本会捕捉的一些失败模式会发生。

记录你选择了哪一项以及为什么。当系统出现复杂模式本可防止的 failure modes 时，你会想记起当时做了什么取舍。

概念 17 的结论：cost 和 latency 是架构约束，不是 afterthoughts。每种模式都有典型成本和延迟 profile，模式组合时乘数会复合。同样任务量下，multi-agent with reflection 可能花费 sequential workflow 的 30-60×（示意比例）。决策树通过 Q4 和 Q5 隐含处理这些因素，但显式预算约束有时会覆盖树的答案；记录覆盖理由，并有意识地接受随之而来的 failure modes。

概念 18：Pattern composition：不同层上的多个模式

本课程大部分时间把模式讲成好像只能选一个。真实系统常常在不同层组合模式：顶层 planning agent，每个 plan stage 内部是 ReAct + tools，final output 上加 reflection。决策 3 和 5 已经展示过这一点；概念 18 将它命名为一等架构动作。

3 种值得识别的组合形状：

Hierarchical composition。 高层模式包裹低层模式。示例：

• Planning agent（顶层）+ ReAct + tools（每个 stage 内部）
• Multi-agent coordinator（顶层）+ sequential workflows（specialists 内部）
• ReAct（顶层）+ sequential workflow（作为 ReAct agent 需要 deterministic work 时调用的工具）

Sequential composition。 模式先后运行，前一个输出进入后一个。示例：

• Sequential workflow（抽取结构化数据）→ ReAct agent（调查结构化数据）
• ReAct agent（生成输出）→ reflection layer（critique 并 refine）

Conditional composition。 不同模式处理不同情况，由 router 选择模式。示例：

• 对 known-shape requests，路由到 sequential workflow；对 unknown-shape requests，路由到 ReAct
• 对 high-stakes outputs，应用 reflection；对 low-stakes outputs，跳过

组合的务实规则： 每一层的模式选择都必须用同样 5 个问题证明，并且要把问题应用在该层范围内。顶层模式通过对整体任务走树选择。每个子组件的模式通过对该子组件所做的事走树选择。不要因为 composition 听起来高级就组合模式；只有当每层任务属性要求它时，才组合。

最常见组合错误： 因为增加层看起来像好工程，所以增加层。一个 coding agent 如果对每个输出都 multi-agent + planning + reflection，并且外面再包 circuit breaker pattern，听起来很严谨；实际往往不必要。通过移除最上层来测试组合。 如果输出没有退化，那一层没有赚回成本。

概念 18 的结论：真实系统会在不同层组合模式：hierarchical（一种模式包裹另一种）、sequential（一种模式的输出进入另一种）、conditional（不同 case 用不同模式）。每层的模式选择都必须在该层 scope 上走决策树来证明。最常见组合错误是因为 layered architectures 听起来高级而添加层；测试方法是移除最上层，检查质量是否退化。

---

第 7 部分：结语

概念 19：Pattern selection 是 Agent Factory curriculum 的连接组织

本课程是 what an agent is（agent-building 课程，关于 agent loops 和 tools）与 what it takes to ship one（cloud deployment 课程中的生产部署、eval-driven 课程中的运维评估）之间的桥梁。

没有模式选择，中间的连接组织就缺失了。你能构建 agent，也能部署它，但二者之间的设计决策，即这个任务需要哪种 agent，仍然没有原则。 本课程填补这个空白。

5 个问题看起来很简单。路径是否已知？workflow 是否稳定？结构是否可表达？质量是否比速度重要？是否存在专业分工瓶颈？但它们编码了这个领域过去 5 年整理出的架构区别。模式目录（ReAct、planning、reflection、multi-agent）已经存在；缺失的是在它们之间选择的决策逻辑。 Bala Priya C 的文章填补这个空白；本课程用 Agent Factory 学生需要的部署与评测组合扩展它。

部署组合是让本课程与众不同的贡献。 很少有 agentic 模式课程会教每种模式对云栈意味着什么：

• 顺序工作流完全跳过 sandbox 层
• 单 agent ReAct 使用完整技术栈
• Planning + ReAct 增加 plan persistence 和更长 background workers
• Reflection 常常引入 multi-provider model routing
• 多 agent 需要 per-specialist tracing、routing audit logs 和 per-role cost attribution

这些不是抽象担忧。它们是小工作负载每月 $130 的部署，与因为模式过度复杂而同样工作负载每月 $400 的部署之间的差别。 模式选择既是架构纪律，也是成本纪律。

评测组合是第二项贡献。 每种模式都有典型失败模式，你的评测套件要用不同方式捕捉：

• 顺序工作流：通过 DeepEval 做 step-level correctness
• ReAct：通过 Phoenix 观察 reasoning traces
• Planning + ReAct：把 plan-execution divergence 作为 custom metric
• Reflection：pre/post comparison 与 rubber-stamp detection
• 多 agent：面向 specialist quality、routing、integration 的 3 个独立 scoreboards

没有 pattern-aware evaluation，评测套件就是泛化的，会错过每种模式产生的具体失败。 本课程逐一命名要看什么，让你的评测套件具备模式感知能力。

Agent Factory 路线的结尾 thesis sentence 现在会略有不同。 agent-building 课程开篇说：agent loop is the engine of an AI-native company。cloud deployment 课程结尾说：agent loop, deployed at production scale with the right architectural separation, observed across the right surfaces, and graded continuously against a living eval suite, is what an AI-native company actually runs on。本课程补上缺失前缀：the right agent loop for the task 才是 AI-native company 运行的东西。 选错形状，无论 overshooting 还是 undershooting，都会让系统交付更慢、成本更高、失败模式更多。模式选择是第一个设计决策；其余一切都在它下游。

本课程之后是什么。 cloud deployment 课程结尾命名了 3 个前沿：agent-to-agent commerce、identic-AI deployment specifics、multi-region active-active。这些仍然是未来课程。本课程再增加一个： pattern-specific testing harnesses。当前评测套件是泛化的；未来课程可以构建模式专属测试生成器（例如「sequential workflow tester」生成覆盖 workflow 分支的输入；「multi-agent routing tester」生成 probing coordinator routing logic 的输入）。这是一个真实前沿，而且依赖本课程的模式 taxonomy 作为前提。

用 AI 做最终练习。 打开 Claude Code 或 OpenCode session。粘贴：

「我刚完成一门关于 agentic pattern selection 的课程。请挑一个我下一季度在真实工作中可能想为它构建 agent 的真实任务，不要玩具例子。和我一起走 5 问决策树，让我回答每个问题，并在我的推理薄弱时反驳。然后告诉我你建议的模式、需要的 cloud deployment topology，以及我应该观察哪些 eval signals。请具体讨论 task properties，不要泛泛而谈。」

你正在学习的东西：决策树只有应用到你的任务，而不是课本例子上，才会真正留下。这个练习会把纪律压进一个你真的会做出的具体决策。 保存 AI 的回复；开始构建 agent 时再回来复看。

结论：本课程是 agent design（agent loops 和 tools）与 agent deployment（cloud deployment 和 eval 课程）之间的连接组织。5 问决策树编码了文献多年形成的架构区别；组合层把每种模式映射到具体部署与评测纪律。结尾 thesis 是：the right agent loop for the task 才是 AI-native company 运行的东西，而模式选择是第一个设计决策，后续一切都从它流出。关于本课程产出的可操作工件，请看 References 前最后一节的一页 design-review template：可打印、团队可共享，按同样 5 个问题，约 15-20 分钟走完每个架构提案。

---

快速参考

两位友人 review 都指出 cheat sheet 太密；下面按所属 Part 分组每一行，这样你可以按小节导航，而不是滚动 22 行。

第 1 部分：模式选择问题

每个 Concept 的一句话回顾

#	Concept	核心要点
1	Pattern selection 是构建前的设计工作	Patterns 已有充分文档；选择它们的 decision logic 没有。错误选择会在生产中昂贵复合。
2	每种 pattern 都是关于任务的押注	Sequential workflow 押注已知路径；ReAct 押注未知路径；planning 押注可表达结构；reflection 押注可检查 criteria；multi-agent 押注真实 specialization needs。
3	两种失败模式，overshoot 和 undershoot	Overshoot（比需要更复杂）是出名模式；undershoot（比需要更简单）同样常见且更隐蔽。

第 2 部分：5 问决策树

#	Concept	核心要点
4	Q1：solution path 能否提前定义？	已知路径路由到 workflows；未知路径路由到 agentic reasoning。用「没有 LLM calls 的 Python function」启发式测试。
5	Q2：workflow 是否固定稳定？	稳定路径路由到 sequential workflow；known-but-variable 要么路由到 branched workflow，要么路由到 agentic patterns。
6	Q3：task structure 是否可表达？	Articulable → planning + ReAct execution；not articulable → pure ReAct。Shape-vs-content 区别。Q2 / Q3 消歧边栏讲边界案例。
7	Q4：Quality > speed 且 checkable criteria？	两个条件都必须成立，reflection 才有价值。最常见失败：rubber-stamping、vague criteria、latency budget violations。
8	Q5：Specialization、context 或 scale bottleneck？	3 个主张分别测试，并尽可能对照量化触发器：>30% tool-routing errors（specialization）、高上下文下 >10% accuracy drop（overflow）、>2× latency budget overrun（scale）。

桥接概念：从模式选择到实现

#	Concept	核心要点
8.5	SDK primitives：每种模式使用什么	Agent 是原子单元。Runner.run() 运行循环。@function_tool 暴露工具。handoff() 用于 specialist takeover；as_tool() 用于 coordinator-in-charge。output_guardrail 用于 reflection。模式选择是在选择组合哪些 primitives。
8.6	每种模式的 operational envelope（以 Inngest 为具体例子）	Triggers 唤醒 function（TriggerEvent, TriggerCron）；step.run 让它持久；step.wait_for_event 实现 HITL gates；concurrency / throttle / priority 塑造负载；fan-out 协调 multi-agent specialists；replay 处理 bug-fix recovery。模式越复杂，envelope 越关键。

第 3 部分：深入 5 种模式

#	Concept	核心要点
9	Sequential workflow，pattern、deployment、evals、envelope	使用云栈最小子集（不需要 sandbox）。step-level evals，不是 agent-reasoning evals。最直接映射到 Inngest functions。
10	Single agent + ReAct，pattern、deployment、evals、envelope	完整云栈，包括 bridge Worker。Phoenix trace evals 是承重层。整个 agent loop 一个 step.run。
11	Planning + ReAct execution，pattern、deployment、evals、envelope	增加 plan persistence；更长 background workers。Plan-execution divergence 是关键 eval signal。每个 stage 一个 step.run。
12	Single agent + reflection（additive layer），pattern、deployment、evals、envelope	叠加在任一 core pattern 之上。常引入 multi-provider model routing。Rubber-stamping 是最隐蔽失败。SDK output_guardrail 或独立 generator / critic。
13	Multi-agent specialist system，pattern、deployment、evals、envelope	完整云栈加 per-specialist tracing。需要 3 个独立 scoreboards。使用每个 Inngest primitive（fan-out、per-tenant concurrency、priority、HITL）。Coordination overhead 真实存在。

第 4 部分：Failure signals 与修订

#	Concept	核心要点
14	5 个 failure signals	ReAct loops（缺结构）、plan-execution divergence（过度结构化）、reflection no-improve（criteria 含糊）、multi-agent routing fail（过度拆分）、complex-but-not-better（累积 overshoot）。
15	先在最小 scope 修复	prompt-level fixes（stop conditions、criteria specs）先于 contract-level（tool descriptions、handoff structures），再先于 architectural changes。
16	决策树什么时候会错	task properties post-deploy 变化、不同 sub-tasks 需要不同 patterns、constraints 排除树的答案。重新走树。
16.5	Anti-pattern gallery，常见错误选择	5 个 overshoot anti-patterns + 3 个 undershoot。Multi-agent for content（→ single agent）；ReAct for invoice（→ workflow）；planner for debugging（→ ReAct）；reflection on vague criteria（→ remove）；one giant agent（→ multi-agent）；skipping reflection on checkable output（→ add）。

第 5 部分：决策实验室（5 个 Decisions，见下表）

第 6 部分：诚实前沿

#	Concept	核心要点
17	Cost 和 latency as architectural constraints	Multi-agent + reflection 可能花费 sequential workflow 的 30-60×（示意比例）。显式记录 constraint-driven pattern choices。
18	不同层的 pattern composition	Hierarchical、sequential、conditional。每一层 pattern choice 都由该 scope 上的同样 5 个问题证明。

第 7 部分：结语

#	Concept	核心要点
19	Pattern selection as connective tissue	连接 agent design（agent loops 和 tools）与 deployment（cloud deployment 课程）。适合任务的正确 agent loop，才是 AI-native company 运行的东西。

5 个 Decisions（第 5 部分）

#	Decision	Core pattern + additive layers

五个 Decisions（Part 5）

| 1 | Maya's Tier-1 Support agent | Core: Single agent + ReAct + tools（概念 10）。无 additive layers。 | | 2 | Incident response agent | Core: Planning + ReAct execution（概念 11）。+ Reflection layer 用于 remediation steps（概念 12）。 | | 3 | Market research agent | Core: Multi-agent specialist system（概念 13），specialists 内部使用 planning + ReAct。+ Reflection layer 用于 synthesis。 | | 4 | Enterprise onboarding agent | Core: Sequential workflow（概念 9）。无 additive layers。agentic patterns 的反例。 | | 5 | Coding agent | Core: Multi-agent specialist system（概念 13），specialists 内部使用 planning + ReAct。+ Reflection layer 用于 coder output。advanced case：每个架构决策都被组合。 |

五个问题和五种模式

Q1: Can the solution path be defined in advance?
    Yes  → Q2
    No   → Q3 (need agentic reasoning)

Q2: Is the workflow fixed and stable across runs?
    Yes  → SEQUENTIAL WORKFLOW
    No   → Q3 (or branched workflow if few stable variants)

Q3: Is the task structure articulable before execution?
    Yes  → PLANNING + REACT EXECUTION
    No   → SINGLE AGENT + REACT + TOOLS

Q4: Quality > speed AND criteria are checkable?
    Yes  → Add REFLECTION on top of the chosen pattern
    No   → Skip reflection

Q5: Specialization, context, or scale bottleneck?
    Yes  → MULTI-AGENT SPECIALIST SYSTEM
    No   → Keep single-agent pattern

Design-review template（一页，可打印）

一份可在团队中共享的 worksheet，用于在 design review 中应用本课程框架。每个 architecture proposal 打印一份。模板走同样 5 个问题，并暴露同样的组合决策；价值不在于独自填完它，而在于让这些问题在讨论中可见。

═══════════════════════════════════════════════════════════════════════
  COURSE ELEVEN: Agentic Architecture Design Review
═══════════════════════════════════════════════════════════════════════

Task name: _______________________________________________________

Task description (1-3 sentences):
  ________________________________________________________________
  ________________________________________________________________
  ________________________________________________________________

Reviewer(s): __________________________  Date: ____________________

───────────────────────────────────────────────────────────────────────
  CORE PATTERN (Q1-Q3)
───────────────────────────────────────────────────────────────────────

Q1. Can the solution path be defined in advance?
    [ ] YES, known        → go to Q2
    [ ] NO, adaptive      → skip to Q3
  Evidence:
    ______________________________________________________________

Q2. Is the workflow fixed and stable across runs?
    [ ] YES, stable        → CORE = Sequential Workflow → skip to Q4
    [ ] NO, variable        → continue to Q3
  Evidence:
    ______________________________________________________________

Q3. Is the task's high-level structure articulable before execution?
    [ ] YES, articulable   → CORE = Planning + ReAct execution
    [ ] NO, emergent       → CORE = Single Agent + ReAct + tools
  Evidence:
    ______________________________________________________________

  → CORE PATTERN CHOSEN: ________________________________________

───────────────────────────────────────────────────────────────────────
  ADDITIVE LAYERS (Q4-Q5)
───────────────────────────────────────────────────────────────────────

Q4. Quality > speed AND criteria are checkable?
    [ ] YES: both          → ADD Reflection layer
    [ ] NO: vague criteria → DO NOT add reflection
    [ ] NO: latency budget → DO NOT add reflection (consider human review)
  Checkable criteria (if YES):
    ______________________________________________________________
    ______________________________________________________________

Q5. Specialization, context, or scale bottleneck?
    [ ] YES: specialization (name it): _______________________________
    [ ] YES: context overflow (describe): ____________________________
    [ ] YES: parallelizable scale (quantify): ________________________
    [ ] NO: keep single agent

  → If Q5 is YES → upgrade CORE to: Multi-Agent Specialist System
    Specialist roles: ____________________________________________

───────────────────────────────────────────────────────────────────────
  FINAL ARCHITECTURE
───────────────────────────────────────────────────────────────────────

Core pattern:         ________________________________________________
+ Reflection (Y/N):   ________________________________________________
+ Multi-agent (Y/N):  ________________________________________________

───────────────────────────────────────────────────────────────────────
  IMPLEMENTATION & DEPLOYMENT
───────────────────────────────────────────────────────────────────────

SDK primitives used (Concept 8.5):
  [ ] Agent (with output_type if structured)
  [ ] Runner.run(agent, input, max_turns=__)
  [ ] @function_tool decorators on N tools (N = __)
  [ ] handoff() between agents
  [ ] Agent.as_tool() for coordinator composition
  [ ] output_guardrail (if reflection layer)

Operational envelope primitives (Concept 8.6, if applicable):
  [ ] Trigger: ___________________________________________________
  [ ] step.run per: _____________________________________________
  [ ] step.wait_for_event for: __________________________________
  [ ] Concurrency cap: ______ per ______________________________
  [ ] Fan-out for: ______________________________________________
  [ ] Priority/fairness rule: ___________________________________

Cloud deployment subset needed (Concept 9-13 sidebars):
  [ ] FastAPI on ACA (always)
  [ ] Neon Postgres
  [ ] R2 (if files in/out)
  [ ] Sandbox + Bridge Worker (if agent runs code)
  [ ] Phoenix (if agentic: any pattern except pure sequential workflow)

───────────────────────────────────────────────────────────────────────
  RISK ANALYSIS
───────────────────────────────────────────────────────────────────────

Cost class (Concept 17):
  [ ] 1× baseline (Sequential workflow)
  [ ] 3-10× (Single agent + ReAct)
  [ ] 5-15× (Planning + ReAct)
  [ ] +2-3× core (with Reflection)
  [ ] 5-20× (Multi-agent)

Latency budget check:
  Expected latency: ___________________________________________
  User-facing budget: _________________________________________
  [ ] Fits           [ ] Tight           [ ] Will not fit

Most likely failure signal to watch (Concept 14):
  [ ] ReAct loops / revisits solved work
  [ ] Plan-execution divergence
  [ ] Reflection not improving output
  [ ] Multi-agent routing failures
  [ ] System feels complex but not better
  Mitigation if it appears:
    ______________________________________________________________

Eval signals to wire (Concept 9-13 sidebars):
  ______________________________________________________________
  ______________________________________________________________

───────────────────────────────────────────────────────────────────────
  ANTI-PATTERN CHECK (Concept 16.5)
───────────────────────────────────────────────────────────────────────

If a senior engineer reviewed this choice, what would they object to?
  ______________________________________________________________
  ______________________________________________________________

Counter-argument (why our choice is right despite the objection):
  ______________________________________________________________
  ______________________________________________________________

───────────────────────────────────────────────────────────────────────
  SIGN-OFF
───────────────────────────────────────────────────────────────────────

Architecture approved for: [ ] Prototype  [ ] Pilot  [ ] Production
Approved by:    ______________________________________________________
Re-review date: ______________________________________________________

═══════════════════════════════════════════════════════════════════════

模板故意设计成每个架构提案 15-20 分钟可以走完。填表本身就是纪律；价值在于让问题在团队对话中可见。每个重大架构决策打印一份；把填完的版本保存到团队的 design-decision archive。

References

• Bala Priya C, "Choosing the Right Agentic Design Pattern: A Decision-Tree Approach," 《Machine Learning Mastery》, May 15, 2026, machinelearningmastery.com/choosing-the-right-agentic-design-pattern-a-decision-tree-approach。本课程主轴上的决策树来自她。
• Yao et al., "ReAct: Synergizing Reasoning and Acting in Language Models" (2022)，最初的 ReAct 论文。
• Wang et al., "Voyager: An Open-Ended Embodied Agent with Large Language Models" (2023)，planning + execution 组合的早期示例。
• Shinn et al., "Reflexion: Language Agents with Verbal Reinforcement Learning" (2023)，reflection 模式的形式化。
• OpenAI, "The next evolution of the Agents SDK" (April 2026)，让这些模式可交付的 SDK update（model-native harness 加 native sandbox execution）。
• agent-building 课程（Panaversity Agent Factory）：agent loops 和 AI-native company 的 engine。
• eval-driven 课程（Panaversity Agent Factory）：eval-driven development 和 trace-to-eval 纪律。
• cloud deployment 课程（Panaversity Agent Factory）：在云端部署 OpenAI Agents SDK harness。

---

Agent Factory 路线中的 pattern-selection 速成课：5 个问题、5 种模式、失败信号，以及与部署、评测套件和 operational envelope（Inngest）的组合。锚点文章：Bala Priya C，Machine Learning Mastery，2026 年 5 月 15 日。它补上 agent design（agent loops 和 tools）与 deployment / eval 课程的生产纪律之间的 pattern-selection 缺口，并贯穿组合 operational envelope；通过映射表可迁移到任何 agentic 技术栈。

Flashcards Study Aid

测试你的理解

这是一个带门槛的自测，用来检查你刚学过的决策树、五种模式、失败信号，以及过度设计与设计不足的判断纪律。

Checking access...