智能体图工程：深度研究全集

LangGraph：LLM 智能体的状态机

概述

LangGraph 由 LangChain 于 2024 年初发布，是一个将状态化、多角色的 LLM 应用构建为图的框架。其核心抽象是 StateGraph（状态图）：一个有向图，其中节点是读写共享状态对象的 Python 函数（或 LLM 调用），边——包括条件边——决定节点之间的控制流。LangGraph 的诞生是为了解决当时主流抽象（基于 DAG 的链，即 LangChain Expression Language）的一个特定局限：DAG 无法表达循环，但最强大的智能体架构（ReAct 循环、反思、多智能体协商）本质上是循环的。

在 LangGraph 之前，构建一个能够循环的智能体——调用工具、观察结果、决定再调用另一个工具——要么需要写一个定制的 while 循环（没有持久化、没有可观测性、无法人工介入），要么使用根本无法表达循环的 DAG 框架。LangGraph 的洞见是将智能体建模为状态机：循环变成图中的环，智能体的记忆变成显式的状态模式（schema），控制流变成边。这使得智能体变得可检查、可恢复、可中断。

LangGraph 的影响在整个智能体生态中清晰可见。它的模式——带 reducer 的状态模式、条件路由、检查点、人机协同中断——已成为智能体工程的事实标准词汇。竞争框架（LlamaIndex Workflows、Pydantic AI、Mastra）都以 LangGraph 的"智能体之图"模型为参照来定义自己。

架构

LangGraph 的架构围绕四个核心概念组织：

状态（State）。 状态是一个类型化模式（TypedDict 或 Pydantic 模型），代表智能体的共享记忆。每个节点接收当前状态并返回部分更新。更新通过 reducer 合并到状态中——reducer 定义字段如何与其先前值组合。最常用的 reducer 是 add_messages，它将新消息追加到消息历史而非覆盖。状态模式是智能体的契约：它精确定义了节点之间流动的信息。

节点（Nodes）。 节点是一个 Python 函数 (state) -> partial_state。它可以是任何东西：LLM 调用、工具执行器、验证函数、人工审批门。节点是计算单元。每个节点读取状态、执行工作并发出更新。

边（Edges）。 边定义控制流：

• 普通边：无条件转移（节点 A 总是到节点 B）。
• 条件边：路由函数检查状态并返回下一个节点的名称。这就是智能体"决策"的方式——LLM 的输出（例如"调用工具 X"或"完成"）被路由器读取，路由器据此引导流程。
• 入口点：指定的起始节点。
• END：终止图的特殊汇点。

检查点（Checkpointing）。 每次节点执行（一个"超步"）后，LangGraph 将完整状态序列化到检查点存储（SQLite、Postgres、内存）。这赋予图：

• 持久化：运行可以被中断并从最近的检查点恢复。
• 时间旅行：可以重新加载任何先前的状态并从那里重新运行图。
• 人机协同：图可以在节点之前 interrupt（中断）、持久化状态、等待人工输入，然后恢复。
• 多轮记忆：thread_id 限定检查点的范围，因此对话历史可以跨调用持久化。

执行模型是基于超步的（受 Pregel/BSP 启发）：在每个超步中，可运行的节点执行，它们的更新通过 reducer 应用到状态，下一组节点由边决定。这使得执行在给定状态和路由函数的情况下是确定性的。

设计决策

决策 1：循环图 vs 仅 DAG（LangChain Expression Language）。

LangGraph 的奠基性决策是允许循环，而 LCEL 刻意禁止循环。

权衡：

• 循环优势：表达力。ReAct 循环（LLM → 工具 → LLM → ……直到完成）是一个循环。反思（生成 → 批评 → 重新生成）是一个循环。多智能体协商是一个循环。没有循环，这些模式需要笨拙的变通（展开循环，或退回到原生 Python）。
• 循环优势：忠实建模。智能体的实际控制流就是循环的。DAG 强迫程序员歪曲结构，使代码更难推理。
• 循环成本：终止不保证。循环图可能永远循环。LangGraph 用 recursion_limit（默认 25 个超步）缓解，超过则报错。
• 循环成本：静态分析更难。无法对循环图拓扑排序，因此某些优化（独立分支的并行调度）更复杂。

团队判断用户实际需要的智能体模式（循环、反思、多智能体）是循环的，禁止循环的框架会把用户推向原生 Python，失去框架的所有好处（持久化、可观测性、介入）。

决策 2：带 reducer 的显式状态模式 vs 隐式消息传递。

LangGraph 要求类型化状态模式和显式 reducer，而不是让节点传递任意数据。

权衡：

• 显式状态优势：状态是唯一真相来源。每个节点读写相同的模式。关于何处可用什么数据没有歧义。这使智能体可检查（可以打印任何超步的状态）和可恢复（状态可序列化）。
• 显式状态优势：reducer 使合并语义显式化。add_messages 追加；自定义 reducer 可以去重、求和或取最大值。没有 reducer，并发节点更新会有歧义的合并行为。
• 显式状态成本：样板代码。程序员必须预先定义模式和 reducer，即使是简单的智能体。
• 显式状态成本：刚性。改变状态模式需要更新所有触及它的节点。

团队选择显式状态，因为无状态是原生 while 循环智能体的第一大失败模式：智能体的记忆分散在局部变量中，无法持久化、恢复或调试。显式模式强迫程序员外化智能体的记忆。

决策 3：每超步后检查点 vs 手动持久化。

LangGraph 在每个节点后自动检查点完整状态，而不是让程序员手动保存状态。

权衡：

• 自动检查点优势：持久化、时间旅行和人机协同都免费获得。程序员不用考虑保存状态——它就是会发生。这是 interrupt()（暂停等待人工输入）变得简单的原因：状态已经持久化了。
• 自动检查点优势：正确性。手动持久化容易出错（忘记保存、保存不一致的状态）。自动检查点保证状态在超步边界总是一致的。
• 自动检查点成本：开销。每个节点后序列化完整状态增加延迟和存储，尤其对大状态（长消息历史）。
• 自动检查点成本：存储增长。长时间运行的智能体累积许多检查点。LangGraph 用检查点 TTL 和线程范围清理缓解。

团队判断解锁的能力（可恢复性、时间旅行、人机协同）是核心价值主张，开销对目标工作负载（几十个超步的智能体运行，而非数百万）可接受。

决策 4：条件边（路由函数）vs LLM 原生路由。

LangGraph 通过检查状态的显式路由函数来引导控制流，而不是让 LLM 直接选择下一个节点。

权衡：

• 路由函数优势：确定性和可测试性。路由器是纯函数 (state) -> node_name。可以单元测试。LLM 的角色是产生结构化输出（例如工具调用或"完成"令牌），路由器解释它。这将 LLM 的判断（做什么）与框架的控制流（如何路由）分离。
• 路由函数优势：安全。LLM 只能在路由器暴露的路由中选择。它不能跳到任意节点。这将智能体行为约束在设计的图内。
• 路由函数成本：间接层。程序员既要写 LLM 提示（产生可路由的输出），又要写路由器（解释它）。比"让 LLM 决定"更多代码。
• 路由函数成本：刚性。添加新路由需要修改路由函数。

团队选择路由函数，因为不受约束的 LLM 控制流不可靠——直接"决定"下一步的 LLM 倾向于幻觉出无效转移。路由函数使控制流显式且可验证。

模拟设计者思考

*我是 Harrison Chase，2023 年末，我看着用户用 LangChain 构建智能体。最强大的模式——ReAct，LLM 在循环中调用工具——是最难构建的。用户写原生 while 循环：while True: response = llm(messages); if done: break; result = tool(response); messages.append(result)。它能工作，但它是个黑盒。没有持久化。如果进程死亡，智能体的记忆就消失了。无法暂停等待人工批准。无法看到智能体在第 7 步在想什么。而且每个用户都略有不同地重新发明这个循环。*

*DAG 框架（LCEL）帮不上忙，因为循环是环，而 LCEL 禁止环。所以有一个空白：最强大的智能体模式没有一等公民的框架支持。这就是机会。*

*循环在结构上是什么？它是一个带环的图。LLM 节点路由到工具节点（继续）或 END（完成）。工具节点总是路由回 LLM。这是一个两节点循环，带条件出口。如果我能把它表示为图，我就得到图给我的一切：可视化、持久化、中断。*

*但什么的图？节点是函数。边是控制流。而流经图的东西——智能体的记忆——那就是状态。我需要一个显式状态对象，每个节点读写它。不是隐式消息传递，因为那样我无法持久化或检查它。类型化模式：class AgentState(TypedDict): messages: Annotated[list, add_messages]。add_messages reducer 说"追加，不覆盖"。这就是合并语义，显式化。*

*控制流：图如何知道要循环？条件边。路由函数读取状态——特别是最后一条消息——并决定：如果有工具调用，去 tools 节点；否则去 END。LLM 不直接选择节点。它产生工具调用（结构化输出），路由器解释它。这保持控制流确定且可测试。LLM 在结构内行使判断；结构约束 LLM。*

*现在是杀手级功能：检查点。每个节点后序列化状态。为什么每个节点？因为那样我可以从任何地方恢复。如果进程崩溃，重新加载最近的检查点并继续。如果人工需要批准工具调用，在工具节点之前 interrupt——状态已保存——等待输入，然后恢复。时间旅行：重新加载第 5 步的状态，尝试不同的分支。所有这些都来自"每超步后检查点"。*

*执行模型：超步，像 Pregel。每个超步，运行就绪的节点，通过 reducer 应用它们的更新，从边确定下一个节点。给定状态下确定性。这不是运行任意并行作业的工作流引擎——这是一个步进遍历图的状态机。并行性有限（超步内独立节点可并发），但语义干净。*

*赌注：智能体是状态机，这样对待它们的团队——显式状态、显式控制流、检查点持久化——将构建出可靠到足以用于生产的智能体。原生 while 循环是原型工具。LangGraph 是生产工具。图不仅是图表。它是运行时。*

关键启示与行业影响

LangGraph 最重要的贡献是概念性的：它确立了智能体是状态机，且状态机应该是显式的、类型化的、持久化的。在 LangGraph 之前，"智能体"意味着围绕 LLM 的 while 循环——不透明、无状态、不可恢复。LangGraph 之后，智能体工程的词汇（状态模式、条件边、检查点、中断）标准化了。这种重构使智能体可以作为工程制品来讨论，而不仅仅是演示。

每超步后检查点的决策被证明是整个"生产智能体"运动的基础。持久化使长时间运行、能在重启中存活的智能体成为可能。时间旅行使调试成为可能（"用不同的工具结果从第 5 步重放"）。人机协同使企业部署所需的审批工作流成为可能。没有自动检查点，这些都不存在。教训：持久化不是优化——它是使智能体可用于生产的能力。

条件边（路由函数）模式解决了智能体设计的根本张力：LLM 自主性 vs 工程控制。通过让 LLM 产生结构化决策（工具调用、分类），同时让确定性路由器解释它们，LangGraph 给工程师一种在不消除 LLM 判断的情况下约束智能体行为的方法。这种"LLM 在结构内决策"模式现在是生产智能体的默认。教训：不要让 LLM 控制控制流；让它控制数据，并确定性地基于该数据路由。

LangGraph 的主要批评——冗长和陡峭的学习曲线——是显式性的经典成本。要求状态模式、reducer 和路由函数比 while 循环更多代码。框架的回答是这种显式性正是买来可靠性的东西。持续的张力（与 Pydantic AI 和 Mastra 等主张更少仪式的更轻量框架的争论）是智能体工程的活跃辩论：多少结构才足够。

框架格局中的比较定位

LangGraph 在智能体框架格局中占据特定且可辩护的位置。对比 CrewAI，反差是显式性 vs 可读性：CrewAI 的角色/任务/流程模型对团队形状的管道更易上手，而 LangGraph 的显式状态机对定制拓扑提供更精细的控制，当控制流真正定制时是更好的选择。对比 OpenAI Agents SDK，反差是结构 vs 轻量：SDK 信任模型通过 handoff 路由并保持框架薄，而 LangGraph 将流程编码为显式图——前者更轻且随模型改进而能力增强，后者更可审计且更易约束。对比 LlamaIndex Workflows，反差是状态机 vs 数据流：Workflows 从事件契约推导拓扑（对管道自然），而 LangGraph 将其声明为节点和边（对控制流密集的智能体自然）。

这种定位揭示了一个更广泛的真理：各框架正从不同起点收敛到相同的能力集（状态、工具、持久化、人机协同、可观测性），持久的差异化因素是它们提供的心智模型。LangGraph 的心智模型——智能体作为显式、持久化、可中断的状态机——是主流选项中最面向控制的，这就是为什么它在审计性和精确流程控制是要求的场景（企业、受监管、复杂多步骤）占主导地位。它的冗长是那种控制的代价，而关于这个代价是否值得的持续辩论，本质上是应用于框架选择的工作流-智能体之辩。

Anthropic《构建有效的智能体》：工作流与智能体的分类学

概述

《构建有效的智能体》由 Anthropic 于 2024 年 12 月发布（作者 Erik Schluntz 和 Barry Zhang），是智能体工程领域最具影响力的设计文档。它不是框架，而是一套分类法和设计原则，重构了行业构建 LLM 系统的方式。其核心贡献是区分工作流（workflows，LLM 和工具通过预定义代码路径编排的系统）与智能体（agents，LLM 使用循环动态引导自身过程的系统）。文档的核心建议是：大多数成功的应用是工作流而非智能体，工程师应该采用能解决问题的最简单结构。

在这份文档之前，"智能体"一词被宽泛地用于任何涉及 LLM 调用工具的东西。由此产生的混乱导致团队为那些简单确定性管道就能更可靠解决的问题构建过度工程的自主智能体。Anthropic 的分类法给了这个领域共同的词汇：提示链、路由、并行化、编排者-工作者、评估者-优化者（五个工作流模式），以及自主智能体循环。它还提供了决策框架：从简单开始，测量，只有当复杂性可证明地改善结果时才增加。

该文档的影响是可衡量的：它成为几乎每个智能体框架文档的参照点，其模式（尤其是编排者-工作者和评估者-优化者）成为标准构建块。LangGraph、CrewAI、LlamaIndex 都将自己的抽象映射到 Anthropic 的分类法上。

架构

文档描述了五个工作流模式和一个智能体模式，每个都是不同的图拓扑：

1. 提示链（Prompt Chaining）。 一系列 LLM 调用，每一步处理前一步的输出。可选地在步骤之间加"门"（程序化检查）。图拓扑：线性路径。适用场景：任务可分解为固定的串行子任务（例如生成大纲 → 撰写每节 → 对照风格指南检查）。相比单个大提示的收益是每一步更简单、更可靠，门可以及早发现错误。

2. 路由（Routing）。 分类器 LLM 调用检查输入并引导到专门的后续提示/模型。图拓扑：从路由节点到 N 个专门分支的扇出。适用场景：不同类别的输入需要不同处理（例如客服查询路由到退款/账单/技术处理器）。路由分离关注点，让每个分支可优化（甚至使用不同模型——简单查询用便宜模型，难题用强模型）。

3. 并行化（Parallelization）。 多个 LLM 调用同时运行，然后聚合输出。两个子模式：切分（将任务拆分为独立的并行子任务）和投票（同一任务运行 N 次获得多样化输出）。图拓扑：扇出后扇入。适用场景：子任务独立（并行化提速）或多样性提高可靠性（投票增强鲁棒性）。

4. 编排者-工作者（Orchestrator-Workers）。 中央 LLM（编排者）动态将任务分解为子任务，将每个子任务委派给工作者 LLM，并综合结果。图拓扑：轮辐式，辐条动态创建。适用场景：子任务无法预先预测的复杂任务（例如触及多个文件的编码任务）。与并行化不同，子任务不是预定义的——编排者发明它们。

5. 评估者-优化者（Evaluator-Optimizer）。 一个 LLM 生成响应；另一个评估并返回反馈；生成者修订；循环直到评估者满意。图拓扑：带退出条件的双节点循环。适用场景：有明确评估标准且迭代修订可衡量地改善输出的场景（例如文学翻译，直译被精炼为自然散文）。

6. 自主智能体（The Autonomous Agent）。 循环中的 LLM：接收目标、使用工具、观察结果、决定下一个动作，迭代直到目标达成或需要人工输入。图拓扑：循环（ReAct 循环）。适用场景：无法预测所需步骤数、无法硬编码固定路径的开放性问题。文档警告：智能体是最昂贵、最易出错的模式，应保留给高价值、良好沙箱化的任务。

设计决策

决策 1：分类法优于框架。

Anthropic 发布概念分类法而非库。

权衡：

• 分类法优势：框架无关。这些模式无论你用 LangGraph、原生 API 调用还是自定义框架都适用。这使文档普遍适用、广泛采用——它不与任何人的工具竞争。
• 分类法优势：持久性。框架会过时；概念会持久。一年后，具体的框架推荐会过时，但工作流-智能体的区分仍是这个领域的词汇。
• 分类法成本：无可运行制品。读者无法 pip install 分类法。将模式转化为代码留给读者（或映射到分类法的框架）。
• 分类法成本：边界模糊。真实系统混合模式（编排者-工作者系统中每个工作者本身是智能体）。分类法是指导，不是严格分类。

团队选择分类法，因为这个领域的问题是概念混乱，而非缺乏工具。已经有很多框架；缺少的是对何时使用哪种结构的共同理解。

决策 2："从简单开始，只有测量证明时才增加复杂性"作为头条原则。

文档最强调的建议是使用可行的最简单结构，只有当智能体复杂性可证明地改善结果时才增加。

权衡：

• 简单优势：可靠性。每个增加的 LLM 调用和动态决策都是错误可能复合的点。确定性管道（提示链）比自主智能体可预测得多。文档主张复杂性应该由测量的改善来"赢得"。
• 简单优势：成本和延迟。每个 LLM 调用增加成本和延迟。智能体循环可能在一个精心设计的提示就足够的地方发起几十次调用。
• 简单成本：上限。某些任务确实需要动态、多步推理。过度应用"从简单开始"意味着错过智能体大放异彩的任务。文档通过定义智能体确实合适的场景（开放式、步骤不可预测的任务）来承认这一点。
• 简单成本：不够令人印象深刻。"使用提示链"不如"构建自主智能体"激动人心。这个建议逆炒作周期而行。

团队以简单性打头阵，因为他们从与客户的实际工作中观察到，最常见的失败模式是过度工程：团队为工作流就能解决的任务构建脆弱的自主智能体。这个原则是对炒作的矫正。

决策 3：将"工作流"与"智能体"分离为一等公民的区分。

文档坚持工作流-智能体的区分，工作流是预定义代码路径的编排，智能体是 LLM 引导的动态控制。

权衡：

• 区分优势：工程权衡的清晰性。工作流和智能体有根本不同的可靠性、成本和延迟画像。混为一谈导致错误的设计选择。这个区分让工程师推理："我需要动态控制，还是固定路径就够？"
• 区分优势：诚实的能力核算。把提示链称为"智能体"夸大了它的自主性。这个区分防止货物崇拜式编程——因为术语时髦就构建"智能体"，而实际需要的是工作流。
• 区分成本：实践中边界模糊。系统可以主要是工作流但有一个智能体子步骤。二元区分不能干净地捕捉这个谱系（尽管文档承认混合系统）。
• 区分成本：术语摩擦。领域里有些人更宽泛地使用"智能体"。文档的窄定义要求领域采用它的词汇。

团队做出这个区分，因为它是最有用的单一设计决策：它强迫工程师在构建最复杂选项之前问"我真的需要动态控制吗？"

决策 4：明确警告不要将智能体作为默认。

文档直白地陈述：智能体是最昂贵、最不可靠的模式，只应在更简单的模式失败且任务证明其成本合理时使用。

权衡：

• 警告优势：防止最昂贵的错误。循环中的自主智能体可能累积大额账单、采取不可预测的行动、以难以调试的方式失败。这个警告使团队免于昂贵地发现这一点。
• 警告优势：可信度。来自制造模型的公司，这个警告有分量——这不是竞争对手贬低智能体，而是模型制造者说"谨慎使用"。
• 警告成本：可能抑制合理的雄心。团队可能出于过度谨慎而对智能体能力投资不足。文档试图通过描述智能体真正擅长的领域来平衡。
• 警告成本：与商业利益的张力。Anthropic 卖 token；建议客户使用更少（通过更简单的模式）违背短期收入。这实际上增强了建议的可信度。

模拟设计者思考

*我是 Anthropic 的应用工程师，2024 年中，我花了一年帮助客户构建 LLM 系统。我不断看到同样的失败。一个团队说"我们在构建智能体"。他们把 LLM 和十几个工具连成循环。演示里能工作。然后在生产中它做了意想不到的事——调用错误的工具、循环四十次、在一个请求上花 200 美元——他们不知道为什么，因为控制流是 LLM 当时决定的一切。*

*问题是，这些有一半根本不需要智能体。客服分流系统？那是路由。报告生成器？那是带门的提示链。研究摘要器？那是并行化。他们伸手去拿最复杂的模式，因为"智能体"是他们听到的词，而不是因为任务需要动态控制。*

*所以缺少的是词汇。当有人说"智能体"，他们可能指六种不同结构中的任何一种，有完全不同的可靠性画像。我需要给它们命名。让我枚举我实际看到有效的模式：按顺序链接步骤。按输入类型路由。并行扇出。编排者委派给工作者。生成者被评估者精炼。以及真正的自主循环。前五个是工作流——代码定义路径。第六个是智能体——LLM 定义路径。*

*我想传达的关键洞见：工作流和智能体的区别在于谁控制流程。在工作流中，你，工程师，决定顺序。LLM 填充步骤，但路径是你的。在智能体中，LLM 决定路径。这一个区分解释了大部分的可靠性差异。你的工作流和你的代码一样可预测。你的智能体和 LLM 的判断一样可预测。*

*所以建议不言自明：不要放弃你不必须放弃的控制。如果任务有已知结构，就编码它。只有当结构真正无法预知时才使用智能体——当步骤数取决于 LLM 发现的东西时。即使那样，也要沙箱化、限制、监视它。*

*我应该把它构建成框架吗？不。一旦我发布库，它就变成"Anthropic 智能体框架"，与 LangGraph 和其他所有竞争，人们采用工具而不吸收判断。判断才是产品。这些模式足够简单，用原生 API 调用一个下午就能实现——这正是重点。我想让工程师内化何时使用每种结构，而不是导入一个类。所以：文档，而非库。五个工作流和智能体循环的图。决策规则：从最简单的事情开始，测量，只有当它可衡量地有帮助时才增加复杂性。*

*我想让所有人记住的一句话："找到最简单的可行方案，只有当复杂性可证明地改善结果时才增加。"这就是整份文档。其他都是阐述。*

关键启示与行业影响

该文档最持久的贡献是工作流-智能体的区分，它给了这个领域精确推理自主性的方式。在此之前，"智能体"是应用于一切的营销术语；在此之后，工程师可以问决定性的问题——"谁控制流程，代码还是 LLM？"——并做出明智的可靠性/成本权衡。这一个区分防止了无数过度工程的系统。教训：清晰地命名一个区分，往往比构建体现它的工具更有价值。

"从简单开始，只有测量证明时才增加复杂性"原则成为这个领域的奥卡姆剃刀。它是对智能体炒作的直接矫正，并被反复验证：用结构化工作流替代自主智能体的生产系统经常报告更低成本的更好可靠性。教训：智能体复杂性是需要证明的成本，而非需要最大化的能力。

五个工作流模式（链、路由、并行化、编排者-工作者、评估者-优化者）成为标准构建块。每个主要框架现在都将其抽象映射到这些模式上，它们出现在几乎每个智能体架构图中。值得注意的是，这些模式都是图——线性路径、扇出/扇入、轮辐式、循环——这强化了 LangGraph 确立的"图作为智能体结构"范式。教训：一小组可组合的图拓扑覆盖了绝大多数生产 LLM 系统。

文档对智能体的诚实警告——来自制造模型的公司——是可信技术传播的里程碑。它短期内让 Anthropic 一无所失（可以说增长了信任和长期采用），并确立了最可信的指导往往逆商业激励而行。教训：告诉客户何时不使用你最昂贵的能力，建立维持平台的信任。

分类法如何映射到具体框架

这个分类法持久的原因之一是它提供了跨碎片化框架格局的共同参照点——几乎每个框架的抽象都可以在工作流-智能体谱系上定位。LangGraph 的 StateGraph 可以表达所有五个工作流模式（链作为线性路径、路由作为条件边、并行化作为扇出、编排者-工作者作为动态轮辐、评估者-优化者作为双节点循环）以及完全自主的智能体循环；实际上它是整个分类法的通用引擎。CrewAI 的顺序流程直接映射到提示链，其层级流程映射到编排者-工作者。OpenAI Agents SDK 的 handoff 表达路由和委派，模型决定流程——把它放在靠近智能体的一端，尽管其护栏和结构化输出让工程师把特定部署拉回工作流一端。LlamaIndex Workflows 的事件驱动步骤自然表达链、并行化和智能体 RAG 的检索-评估循环。

这个映射不仅是分类学琐事；它是实用工具。当团队说"我们在构建智能体"，分类法让你问真正决定设计的澄清问题：你需要哪种模式？如果答案是"带门的固定序列"，那是提示链，你应该构建管道而非自主循环。如果是"路由到正确的专家"，那是路由，你需要分类器加分支。如果真的是"我们无法预测步骤"，那是智能体循环，你应该为其成本做预算并相应地防护。分类法将模糊的雄心转化为具体的拓扑，而具体的拓扑才是你真正可以工程化的东西。

这个分类法最持久的礼物也许是它给团队构建更简单东西的许可。通过将自主智能体命名为最昂贵和最不可靠的选项——并从卖 token 的平台口中说出——它使工作流合法化。无数本来会是脆弱自主智能体的生产系统变成了可靠的管道，因为团队有了这个论点的受尊敬框架。这就是真正有用想法的标志：它改变人们觉得自己被允许构建的东西。

ReAct：推理-行动循环作为原子智能体图

概述

ReAct（"Reasoning + Acting"，推理+行动）由 Yao 等人（普林斯顿/谷歌）在 2022 年论文《ReAct: Synergizing Reasoning and Acting in Language Models》中提出，是基础性的智能体模式：LLM 将自然语言推理轨迹（"思考"）与具体行动（工具调用/API 查询）交替进行，在每次行动后观察环境反馈并再次推理。它是几乎所有现代智能体赖以构建的原子单元——LangGraph、AutoGPT 以及每个使用工具的智能体最终实现的循环。

在 ReAct 之前，两个主导范式是分离的：纯推理方法（思维链，模型逐步思考但从不接触世界）和纯行动方法（RL 智能体或工具调用者，行动但不言语化推理）。思维链会幻觉出无法验证的事实；纯行动模型在没有计划时会盲目行动。ReAct 的洞见是推理和行动是互补的：推理帮助模型规划和解释（"我应该查找 X，因为……"），行动将推理锚定在真实证据上（"搜索返回了 Y，所以现在我知道了……"）。两者之间的循环使智能体既有目的性又有根据。

ReAct 的图结构是最简单的智能体循环：一个 LLM 节点路由到工具节点（行动）或输出（完成），工具节点总是路由回 LLM。这个双节点循环——思考 → 行动 → 观察 → 思考——是每个智能体框架泛化的模板。理解 ReAct 就是理解智能体工程的原子。

架构

ReAct 的架构是对三种元素类型的循环，全部存储在增长的上下文中：

轨迹（Trajectory）。 智能体维护交替元素的序列：

• 思考（Thought，推理）：关于模型相信、计划或结论的自然语言陈述。例如："我需要找到法国的首都，然后检查它的人口。"
• 行动（Action，行动）：对环境的结构化调用，从定义的行动空间中抽取。例如 search[capital of France] 或 lookup[Paris]。
• 观察（Observation，反馈）：环境对行动的响应。例如："巴黎是法国的首都和人口最多的城市。"

每次迭代将（思考、行动、观察）追加到轨迹。模型的下一个输出以到目前为止的整个轨迹为条件。

行动空间（Action Space）。 智能体可以采取的行动集合，由环境定义。在原论文的 HotpotQA 设置中：search[entity]、lookup[term]、finish[answer]。在现代工具使用智能体中，行动空间是可用工具的集合（每个都是带模式的函数）。finish（或"不再工具调用"）行动是循环的出口。

循环。 控制流：

1. LLM 读取任务+轨迹，生成思考和行动。
2. 如果行动是终止的（`finish`），返回答案。
3. 否则，对环境执行行动，获得观察。
4. 将（思考、行动、观察）追加到轨迹；回到 1。

作为图：一个 LLM 节点、一个条件边（有工具调用 → 工具节点；无工具调用 → END）、一个工具节点带固定边回到 LLM。这正是 LangGraph 快速入门实现的循环。

提示结构。 ReAct 通过少样本提示实现：提示包含（任务、思考-行动-观察轨迹）的示例，使模型学习交替格式。现代实现用原生函数调用（结构化工具调用）取代自由文本行动格式，但推理和行动的交替保持不变。

设计决策

决策 1：推理与行动交替 vs 先推理后行动（规划-然后-执行）。

ReAct 在每一步交替思考和行动，而不是先生成完整计划然后执行。

权衡：

• 交替优势：锚定。每个推理步骤可以纳入来自环境的新证据。如果搜索返回意外结果，下一个思考会适应。规划-然后-执行的智能体在看到任何证据之前就承诺计划，所以错误会复合（错误的早期假设毒害整个计划）。
• 交替优势：错误恢复。当行动失败或返回令人惊讶的输出时，推理轨迹可以注意到并调整路线（"那个搜索没用，让我尝试不同的查询"）。规划-然后-执行没有这种中途反馈。
• 交替成本：短视。逐步决策可能错过大局——智能体可能在没有连贯长期计划的情况下徘徊。（这激发了后来的混合方案，如"plan-and-solve + ReAct"和规划者-执行者模式。）
• 交替成本：更多 LLM 调用。每一步是以增长上下文为条件的独立生成，所以 token 成本随轨迹长度二次增长。

作者选择交替，因为他们的实验（HotpotQA、FEVER、ALFWorld、WebShop）显示它击败了纯思维链和纯行动，而且——关键地——推理轨迹使失败可解释。你可以阅读轨迹并看到智能体在哪里出错。

决策 2：将推理言语化为自然语言 vs 潜在/隐式推理。

ReAct 让模型用文字写出推理，而不是依赖模型内部的隐式推理。

权衡：

• 言语化优势：可解释性。思考轨迹是智能体推理的人类可读记录。这对调试（阅读轨迹，找到坏步骤）和信任（用户可以审计智能体为什么做某事） vô cùng 有价值。
• 言语化优势：自我引导。写出思考实际上改善了模型的下一个行动——言语化的推理成为引导后续生成的上下文的一部分。这是一种自我提示机制。
• 言语化成本：token 开销。思考消耗不直接推进任务的 token。
• 言语化成本：忠实性问题。陈述的思考可能不反映模型的实际"推理"（它是生成的合理化）。这是所有思维链方法的已知局限。

作者选择言语化，因为他们测量的协同效应特别来自言语推理与行动的交替——消融实验显示移除思考或行动中的任何一个都会降低性能。

决策 3：用少样本提示学习格式 vs 微调。

原始 ReAct 使用上下文中的少样本示例来教模型思考-行动-观察格式，而不是微调。

权衡：

• 少样本优势：无需训练。ReAct 与任何足够强大的 LLM 开箱即用。这使它立即可复现、广泛可采用。
• 少样本优势：灵活性。改变行动空间或任务只需改变示例——无需重新训练。
• 少样本成本：上下文长度。少样本示例消耗上下文窗口的很大一部分，留给轨迹的空间更少。
• 少样本成本：格式脆弱。模型必须仅从示例可靠地遵循格式；较弱的模型会破坏格式。（现代原生函数调用很大程度上解决了行动格式问题，推理模型已经内化了大部分"思考"行为。）

作者选择少样本，因为目标是演示一种提示范式，适用于任何模型，而不是训练专门的智能体。

决策 4：单一通用循环 vs 专门的子例程。

ReAct 对所有推理/行动使用一个统一的循环，而不是对不同子任务使用不同机制。

权衡：

• 统一循环优势：简单性和通用性。一个机制处理搜索、计算、导航、任何事——只要有相应的行动。这种通用性使 ReAct 成为通用的智能体原子。
• 统一循环优势：可组合性。因为循环是统一的，它可以嵌套（行动调用子智能体的智能体，每个运行自己的 ReAct 循环）——这是多智能体系统的基础。
• 统一循环成本：无专门化。有已知结构的任务（例如总是分解-然后-解决）不被利用；循环对每一步一视同仁。
• 统一循环成本：无界范围。没有结构，循环可能徘徊；论文强加了最大步骤限制。

模拟设计者思考

*我是 Shunyu Yao，2022 年，我在苦苦思索两个被所有人视为分离的研究线索。一方面，思维链：你提示模型"逐步思考"，它的数学和推理能力显著提升。另一方面，工具使用和具身智能体：调用 API 或导航环境的模型。思维链的人从不调用工具。工具的人从不解释自己。就好像这个领域把大脑劈成两半。*

*这是思维链让我困扰的地方：它会幻觉。模型"推理"出它从未见过的事实，而且听起来很自信。"法国的首都是……让我想想……巴黎"——巴黎没问题，但对一个冷僻的事实它会编造看似合理的东西。推理是无根据的。这是不看就思考。*

*这是纯行动智能体让我困扰的地方：它们没有方向。它们调用 search[...]，但用什么查询，为什么？没有计划或自我解释，每个行动都是猜测。它们盲目行动。它们行动而不思考。*

*如果解决方案是让它们同时做这两件事呢？思考，然后基于思考行动，然后让行动的结果为下一个思考提供信息。一个循环：思考 → 行动 → 观察 → 思考。思考规划和解释。行动锚定和验证。每个都修复另一个的弱点。思维链的幻觉被捕获，因为智能体可以查找事物。行动智能体的盲目行动被治愈，因为它在行动前解释计划。*

*让我检验这个假设。HotpotQA——需要查找多个实体的多跳问题。我给模型三个行动：search、lookup、finish。我用交替推理和行动的示例提示它："思考：我需要找到 X。行动：search[X]。观察：……思考：现在我知道 X 了，所以我需要 Y。行动：……"模型继续这个模式。*

*结果：ReAct 击败了 CoT（会幻觉）和纯行动（会盲目行动）。但我最关心的结果是错误分析。当 CoT 失败时，它以自信的错误答案失败——你看不出为什么。当 ReAct 失败时，我可以阅读轨迹："思考：搜索没有返回任何内容，也许我应该猜测"——就在那里，它放弃的那一刻。推理轨迹将失败从谜团变成可诊断的 bug。这是真正的贡献：一个你可以通过阅读来调试的智能体。*

*我还在 ALFWorld（具身任务）和 WebShop（网页导航）上运行它——CoT 甚至无法应用的领域，因为你必须行动。ReAct 在那里也能工作，因为这个循环是通用的：任何给你行动和观察的环境都适合。一个机制，所有领域。这种通用性将使它成为智能体工程的原子。*

*这个结构是一个图，尽管我不这么称呼它。一个决策节点（LLM）、一个分支（行动或完成）、一个反馈的工具节点。双节点循环。之后的每个智能体框架——LangGraph、AutoGPT、其余的——都是这个循环，被显式化，周围有更好的工具。我在画原子。其他人将构建分子。*

关键启示与行业影响

ReAct 最深刻的贡献是确立思考-行动-观察循环为通用智能体原语。每个现代智能体——从 LangGraph 的快速入门到自主编码智能体——都实现这个循环，无论多么精细。这个循环的力量在于它既最小（两个节点、一个循环）又完整（任何使用工具的智能体都可以表达为它的迭代）。教训：最有影响力的架构往往是捕获基本结构的最小架构。

锚定洞见——推理必须与观察交替以避免幻觉——预示了整个"将 LLM 锚定在真实数据中"的运动（RAG、工具使用、检索）。ReAct 表明，独自推理的 LLM 会编造；可以查找事物的 LLM 会自我纠正。这就是为什么工具使用成为默认能力而非专长。教训：智能体的可靠性受限于它获得真相的途径。

言语化推理的可解释性红利被低估了。因为 ReAct 写出思考，失败变得可读、可调试——这是规划-然后-执行和潜在推理智能体缺乏的属性。这直接催生了智能体可观测性工具类别（LangSmith、追踪仪表板），它们本质上是记录和显示 ReAct 轨迹。教训：使智能体的推理显式化，与认知功能一样是工程功能。

ReAct 的已知局限——短视（无长期规划）、二次 token 增长、格式脆弱——定义了随后的研究议程：规划者（增加长期结构）、反思（增加自我评估）、上下文管理（约束增长的轨迹）、原生函数调用（修复格式）。每个后续模式都可以读作对 ReAct 特定弱点的修复。教训：基础模式的价值包括它绘制的自身缺陷的精确地图。

ReAct 作为现代智能体框架的基底

很难夸大 ReAct 成为智能体工程基底的彻底程度。当 LangGraph 的快速入门构建"工具调用智能体"时，它构建的图就是 ReAct 循环：LLM 节点、以模型是否发出工具调用为键的条件边、工具节点和返回的边。当 OpenAI Agents SDK 的 Runner 循环"调用智能体、执行工具调用、重复"时，那就是 ReAct。当编码智能体编写代码、运行测试、阅读错误并修复时，那就是以测试套件为环境的 ReAct。这个模式如此基础，以至于现代框架很少命名它——它们只是实现它，因为它是工具使用能动性的不可约核心。

这种普遍性反映了这个模式的真实属性：它是闭合推理与锚定行动之间循环的最小结构。任何使用工具的智能体必须在某个层面上（1）决定做什么，（2）做，（3）观察结果，（4）再决定。ReAct 命名并结构化了恰好这四步，推理轨迹作为连接组织使循环连贯而非随机。框架在其上增加复杂性——持久化、规划、多智能体、护栏——但它们几乎都在单个智能体层面保留 ReAct 核心，因为它是展现有目的、有根据行为的最小单元。

这个模式的演变也追溯了这个领域的成熟。原始实现使用自由文本"Thought/Action/Observation"解析，这很脆弱。现代实现用原生函数调用（结构化、可靠）取代行动格式，并经常将推理压缩到模型的内部过程（如推理模型所做），但思考-行动-观察循环保持不变。这是真正基础想法的标志：它的表面细节被工程化掉，而它的结构变得承重。当你今天设计智能体时，你几乎肯定在设计 ReAct 循环——问题是你围绕它构建什么，本文集的其余部分很大程度上就是那个问题的答案。

OpenAI Swarm：Handoff 作为多智能体原语

概述

Swarm 由 OpenAI 于 2024 年 10 月作为实验性、教育性框架发布，引入了一个建立在两个原语之上的极简多智能体编排模型：例程（routines，智能体的指令集+工具，表达为系统提示和函数列表）和 handoff（一个智能体将对话控制权转移给另一个智能体的机制）。Swarm 的论点是：大多数多智能体协调可以归约为"一个智能体作为工具调用决定让另一个智能体接管"——不需要编排者、不需要消息总线、不需要图定义。

Swarm 明确不是生产框架（它被标记为"教育性"，调用之间无状态，后来被 OpenAI Agents SDK 取代）。但它的概念贡献是巨大的：它将 handoff 结晶为一等公民的多智能体原语，并证明了轻量级、函数调用原生的方法可以用几乎零框架表达复杂的多智能体模式（分诊、升级、专门委派）。"智能体即例程+控制权转移即工具调用"的模型直接影响了 OpenAI Agents SDK，并塑造了行业对智能体委派的思考方式。

关键洞见：在函数调用的世界里，"委派给另一个智能体"只是模型可以调用的另一个函数。当分诊智能体调用 transfer_to_billing_agent() 时，框架交换活动智能体（其系统提示和工具）并继续同一对话。多智能体系统变成一个动态图，其中边（handoff）由智能体在运行时自己选择。

架构

Swarm 的架构刻意微小——核心只有几百行：

智能体（例程）。 智能体由以下定义：

• instructions：系统提示（可以是字符串或上下文 → 字符串的函数，使指令动态化）。
• functions：智能体可用的工具。关键地，这个列表可以包含其他智能体（作为 handoff 目标）。

智能体不是带状态的类，也不是预定义图中的节点——它是一个配置："当这个智能体活动时，使用这个提示和这些工具。"

Handoff。 handoff 是返回值为另一个智能体的工具。当活动智能体调用它时，Swarm 的运行循环将活动智能体交换为目标并继续。对话历史被携带（可选地带输入过滤）。handoff 表达为普通函数调用，所以 LLM 使用与任何工具相同的函数调用机制决定何时委派。

运行循环。 Swarm 的执行是单一循环：

1. 通过聊天补全 API 调用活动智能体（其指令+函数+对话历史）。
2. 如果响应包含工具调用，执行它们。如果工具调用返回智能体（handoff），将其设为活动智能体。
3. 将结果追加到对话；循环直到响应没有工具调用（最终面向用户的消息）。

没有显式图、没有状态机、没有编排者。"图"是隐式和动态的：智能体是节点，handoff 是边，LLM 在运行时选择边。

上下文变量。 贯穿运行的键值对字典，可用于指令函数和工具函数。这是 Swarm 唯一的状态机制（除了对话历史）——刻意简单。

无状态性。 Swarm 本身在 run() 调用之间不保留状态。持久化是调用者的责任（将消息历史传回）。这保持框架最小，但将持久性推给用户。

设计决策

决策 1：handoff 作为工具调用 vs 路由的编排者。

Swarm 的定义性决策：委派表达为智能体调用返回另一个智能体的函数，而不是中央编排者决定下一个发言者。

权衡：

• handoff 优势：无需构建或维护中央协调器。路由逻辑存在于智能体的提示中（"如果用户询问账单，调用 transfer_to_billing"）。添加智能体只是向相关智能体添加 handoff 函数。系统通过累积扩展，而不是重新设计编排者。
• handoff 优势：利用原生函数调用。LLM 已经知道如何在函数之间选择；handoff 只是另一个函数。没有新机制、没有新失败模式。
• handoff 成本：分布式控制流。没有单一位置显示"系统的拓扑"。理解多智能体结构需要阅读每个智能体的提示。这使系统比显式图更难审计。
• handoff 成本：无界委派。智能体可以循环 handoff（A → B → A → ……），没有内置的终止保证。Swarm 依赖 LLM 的判断来避免循环。

团队选择 handoff，因为他们的目标是展示多智能体编排可以仅从函数调用原语中涌现——最小可能的框架。编排者模式（LangGraph 的 supervisor）更可控但更重；Swarm 演示了轻量级的极端。

决策 2：教育性/最小化 vs 生产完整。

Swarm 明确作为教育性、非生产框架发布。

权衡：

• 最小化优势：想法清晰。通过剥离持久化、流式基础设施、追踪、护栏等，Swarm 使核心概念（例程+handoff）明确无误。读者可以在一小时内理解整个框架。
• 最小化优势：低采用门槛。除 OpenAI SDK 外无依赖。任何人都可以立即运行并内化这个模式。
• 最小化成本：不能用于真实系统。无持久化、无内置错误处理、无可观测性。试图生产化 Swarm 的团队必须把所有东西加回来。
• 最小化成本：混淆。一些用户错过了"教育性"标签，在不支持的基础上构建。

团队选择教育性，因为价值是模式而非库。发布最小参考实现让想法传播，而没有维护负担（和虚假承诺）。这个模式后来毕业到生产级的 Agents SDK。

决策 3：运行之间无状态 vs 内置会话状态。

Swarm 在 run() 调用之间不保留状态；调用者管理对话历史。

权衡：

• 无状态优势：简单性和灵活性。框架对存储、会话或持久化没有意见。它与调用者选择的任何后端组合。
• 无状态优势：可预测性。每次运行是 (消息, 上下文) 的纯函数。易于测试和推理。
• 无状态成本：调用者负担。多轮对话需要调用者手动传递消息历史。容易出错（例如丢失 handoff 上下文）。
• 无状态成本：无内置可恢复性。崩溃的运行丢失一切，除非调用者持久化了。

团队选择无状态，以保持核心循环纯粹并避免强加持久化模型。这是经典的"机制，而非策略"决策——框架提供执行机制，将状态策略留给应用。

决策 4：动态指令（上下文的函数）vs 静态提示。

Swarm 允许智能体的 instructions 是接收上下文变量的函数，而不仅是静态字符串。

权衡：

• 动态优势：个性化和状态感知。分诊智能体的指令可以引用用户的层级、当前步骤、先前的决策——上下文中的任何内容。这使例程自适应，而无需增加框架机制。
• 动态优势：逻辑保留在 Python 中。与其将条件行为塞进提示文本，不如在代码中计算正确的指令。
• 动态成本：间接层。有效提示在智能体定义中不可见；你必须运行函数才能看到它。稍难审计。
• 动态成本：复杂性潜力。指令函数可能成为影子控制流系统。

团队包含动态指令，因为真实的分诊/路由行为几乎总是依赖运行时上下文，这是支持它的最便宜方式，而无需添加状态机。

模拟设计者思考

*我在 OpenAI 的应用团队，2024 年中，我看着客户构建多智能体系统。他们使用的框架很重：图定义、编排者节点、消息总线、状态模式。我不断注意到，底层模型在函数调用上已经变得如此擅长，以至于大部分脚手架在做模型可以原生完成的工作。*

*这是观察结果："委派给另一个智能体"到底是什么？这是一个决策。"这个账单问题不是我的；账单智能体应该处理它。"模型如何表达决策？函数调用。所以委派应该是函数调用。transfer_to_billing()。就这样。没有编排者。知道自己力不从心的智能体只是……交出对话。*

*那么智能体剥离到骨架是什么？系统提示和一组工具。这就是"例程"——打包的行为方式。当 handoff 发生时，我交换活动例程：新系统提示、新工具、同一对话。多智能体系统只是：哪个例程活动，以及到目前为止的对话。两个原语：例程和 handoff。其他一切都是脚手架。*

*让我用标准的多智能体模式检验这一点。分诊：带专家 handoff 的前门智能体。升级：带 transfer_to_human handoff 的支持智能体。专门委派：handoff 给写手的研究智能体。顺序处理：智能体 A 交给 B，B 交给 C。它们都归约为例程+handoff。拓扑没有在任何地方声明——它隐含在哪些智能体有到哪些智能体的 handoff 中。图是动态的，由模型在运行时选择。*

*现在，我应该把它构建成大框架吗？不——这是刻意的。一旦我添加持久化、追踪、护栏、部署，我就在基础设施上竞争，核心想法会被功能淹没。想法才是贡献：多智能体编排可以这么轻。所以我把它作为"教育性、实验性"发布——几百行、无依赖、完全可读。我想让每个工程师在一小时内读完整个东西，然后想"哦，就是这样。"*

*风险是真实的。有人会在上面构建生产，被无状态烧伤。我会清楚地标记：不用于生产。重点是教这个模式——例程和 handoff——这样当人们构建（或使用）真正的东西时，他们理解底层的原语。模式是持久的制品。库是一次性的证明。*

*更深层的赌注：随着模型改进，编排应该变得更轻而非更重。框架的工作收缩到"让模型路由"。如果我对，重的编排框架将被迫为它们添加的每一层辩护。Swarm 是我的论点：底线比行业认为的低得多。*

关键启示与行业影响

Swarm 最重要的贡献是确立 handoff 为一等公民的多智能体原语。在 Swarm 之前，多智能体系统通常围绕编排者（supervisor 节点、图、消息路由器）构建，由它决定控制流。Swarm 表明控制流可以是去中心化的——每个智能体使用与工具相同的函数调用决定何时让出发言权。这种"委派即工具调用"的模型被 OpenAI Agents SDK 采用，并影响了其他框架的 handoff 功能。教训：当模型足够好时，控制流可以是数据（函数调用）而非结构（图的边）。

"例程+handoff"的归约证明了多智能体编排实际需要的机制是多么少。通过展示分诊、升级和委派都归约为两个原语，Swarm 迫使行业重新审视其编排脚手架中有多少是本质的、多少是附带的。这给更重的框架施加了证明其复杂性合理性的压力，并给团队提供了以委派为中心的系统的轻量选项。教训：最小可行编排通常比框架暗示的小得多。

Swarm 刻意的"教育性、非生产"定位是想法优先发布策略的大师课。通过发布可读的、最小的参考而非完整框架，OpenAI 最大化了模式的传播，同时避免了生产工具的维护和责任义务。然后这个模式毕业到 Agents SDK，它在相同原语之上添加了生产层（追踪、护栏、handoff 上下文）。教训：有时最高杠杆的制品是带一次性实现的清晰想法。

Swarm 的主要局限——分布式、隐式的控制流难以审计且对委派循环无界——是去中心化编排的固有成本。它直接映射到工作流-智能体的张力：Swarm 处于完全智能体的极端（LLM 控制所有流程）。需要审计性和终止保证的团队被拉回显式图编排者（LangGraph supervisor）。教训：去中心化 handoff 用可控性换取轻量；根据任务需要多少控制来选择。

Swarm 在编排哲学辩论中的位置

Swarm 是一个立场的最纯粹表达，这个立场已成为智能体编排设计两极之一：控制流应该委派给模型。在 Swarm 的视图中，编排者是工程师为补偿模型路由能力不足而构建的结构——随着模型改进，那种补偿应该收缩。handoff 是那种委派的机制：模型作为例程函数调用决定另一个智能体何时接管。没有要定义的图，因为图是隐式的、动态的、由智能体在运行时选择的。这是"薄框架"哲学被推到逻辑结论。

对立的一极——由 LangGraph 和显式图框架代表——主张控制流太重要而不能委派：它应该是工程师定义、审计和约束的制品。这两极之间是大多数真实的设计工作。生产系统通常混合它们：确定性骨干（工作流）在特定、有界的点（路由步骤、handoff）有模型路由的决策。Swarm 的价值在于它清晰地定义了一极，使工程师能够有意识地而非默认地做委派-控制权衡。

Swarm 留下的最持久教训，除了 handoff 原语本身，是方法论上的：发布证明想法的最小东西，让想法自己传播。Swarm 是几百行可读代码，重构了整个行业对多智能体协调的思考，它的"教育性、非生产"诚实意味着它传播时没有可靠性承诺的负担。它证明的模式——例程加 handoff——比库活得更久，并毕业到生产工具。对任何构建智能体基础设施的人，教训是：清晰、最小、诚实范围的参考可以比重功能完整的框架更能推动领域，因为复利的是想法——而非代码。

CrewAI：基于角色的多智能体编排

概述

CrewAI 由 João Moura 创建并于 2024 年初发布，是一个围绕团队（crew）隐喻组织的多智能体编排框架：一组角色扮演的智能体（每个都有角色、目标和背景故事）、一组任务（带描述和预期输出的工作单元）、以及一个流程（process，任务排序的策略——顺序或层级）。CrewAI 的核心贡献是通过将多智能体系统建模为人们熟悉的人类结构——有角色、分工和工作流的团队——而非图或消息传递，使非专家也能理解。

CrewAI 出现时，多智能体框架要么高度抽象（AutoGen 的开放式对话），要么以图为中心（LangGraph 的显式状态机）。两者都需要系统思维才能用好。CrewAI 的赌注是："多个智能体协同工作"的主导心智模型是人类团队：收集信息的研究员、起草的写手、审阅的编辑。通过使角色、任务和流程成为原语，CrewAI 让产品工程师甚至非工程师能够以几十行代码声明式地组装多智能体管道。

该框架增长迅速（2024 年增长最快的开源智能体项目之一），成为"智能体即团队"架构的默认选择。其企业平台在开源核心之上扩展了部署、可观测性和可视化构建器。CrewAI 的影响可见于角色/目标/背景故事智能体定义模式在整个生态系统的广泛采用。

架构

CrewAI 的架构构建在四个核心抽象之上：

智能体（Agent）。 智能体由以下定义：

• role：其职位（"高级研究分析师"）
• goal：它试图实现的目标（"揭示 AI 领域的前沿进展"）
• backstory：锚定其角色和专业知识的叙事（"你是一位以综合复杂主题能力著称的资深分析师……"）
• tools：它可以使用的工具
• llm：支持它的模型（可以因智能体而异）

角色/目标/背景故事三元组被编译进智能体的系统提示。背景故事是 CrewAI 的独特创新——一个简短的叙事，使智能体的行为比单纯的角色字符串更一致、更符合领域。

任务（Task）。 任务是工作单元：

• description：做什么
• expected_output：好的结果是什么样子
• agent：分配的智能体（或让流程分配）
• context：此任务消费其输出的其他任务

任务是数据流的边：任务的 context 声明它依赖上游任务的输出。这就是 CrewAI 表达管道结构的方式——不是作为图的边，而是作为任务依赖。

流程（Process）。 流程是编排策略：

• sequential（顺序）：任务按列表顺序执行，每个任务接收前一个任务的输出作为上下文。最简单也最常见。
• hierarchical（层级）：管理者智能体（自动创建）接收任务，将每个任务委派给它判断最合适的团队成员，并验证结果。管理者动态地做路由。

流程是"谁决定顺序"的旋钮：顺序 = 开发者决定；层级 = LLM 管理者决定。

团队（Crew）。 团队将智能体+任务+流程绑定为可运行单元。crew.kickoff() 执行流程，产生最终输出（可选地通过 Pydantic output_pydantic 产生结构化结果）。

底层上，每个智能体是 ReAct 风格的循环（CrewAI 最初构建在 LangChain 的智能体执行器上）：智能体推理、调用工具、观察，并迭代直到产生任务的预期输出。所以 CrewAI 团队是 ReAct 循环的图，其中图结构由任务依赖和流程给出。

设计决策

决策 1：角色/目标/背景故事角色 vs 纯指令提示。

CrewAI 通过角色三元组（角色、目标、背景故事）定义智能体，而不是单一指令字符串。

权衡：

• 角色优势：行为一致性。背景故事给模型一个稳定的身份去扮演，经验上产生比简短指令更聚焦、更符合领域的行为。"在顶级咨询公司工作 20 年的资深市场分析师"表现得比"你是做市场分析的有帮助助手"更像分析师。
• 角色优势：对人类的可读性。非工程师（产品经理、领域专家）可以阅读和编写角色/目标/背景故事定义。这大幅降低了构建多智能体系统的门槛，并使团队可被理解领域的人审查。
• 角色成本：提示膨胀。背景故事在每次调用时消耗 token。
• 角色成本：过度扮演风险。精心设计的角色可能使智能体冗长或戏剧化，而非精确。调整背景故事长度/语气成为真正的提示工程任务。

团队选择角色，因为他们的目标用户组装智能体是为了镜像人类团队角色，而角色三元组是表达这一点的最自然方式。背景故事特别解决了"通用助手"失败模式——所有智能体听起来和行为都相同。

决策 2：以任务为中心的数据流（上下文依赖）vs 显式图的边。

CrewAI 将管道表达为带 context（上游任务引用）的任务，而不是声明图中的节点和边。

权衡：

• 以任务为中心优势：声明式和熟悉。"任务 B 使用任务 A 的输出"是项目经理描述工作的方式。无需图论。数据流结构从任务列表+上下文引用中涌现。
• 以任务为中心优势：分离工作与接线。开发者描述每个任务产生什么；CrewAI 传递输出。这比手动接线节点之间的状态更不容易出错。
• 以任务为中心成本：不如通用图表达力强。任意拓扑（复杂分支、动态循环）比在 LangGraph 中更难表达。顺序/层级流程覆盖常见情况，但不是全部。
• 以任务为中心成本：隐式控制流。实际执行顺序从流程+任务列表派生，这可能让习惯显式控制流的开发者感到惊讶。

团队选择以任务为中心的流，因为他们的研究显示绝大多数真实多智能体用例是线性管道或管理者委派的工作——不是任意图。为常见情况优化使框架大幅简化。

决策 3：顺序+层级流程 vs 单一通用编排者。

CrewAI 提供两个内置流程（顺序、层级），而不是一个通用编排机制。

权衡：

• 双流程优势：以最小概念覆盖主导模式。顺序处理管道（研究 → 写作 → 编辑）。层级处理委派（管理者路由任务）。大多数团队使用其中之一。
• 双流程优势：层级流程提供动态路由，而开发者无需编写编排者——管理者智能体自动生成并使用团队的角色进行委派。这使"supervisor 模式"一行代码即可访问（process=Process.hierarchical）。
• 双流程成本：刚性。既不是纯管道也不是纯委派的工作流（例如有一个动态分支的管道）需要变通（嵌套团队、自定义任务）。
• 双流程成本：层级不可预测性。自动生成的管理者的委派决策可能令人惊讶，且难以精确约束。

团队选择两个命名流程，因为它们映射到人们已经理解的两种管理风格（"流水线"和"管理者委派"），使框架的行为可预测和可解释。

决策 4：将智能体构建为 ReAct 循环（最初在 LangChain 上）vs 自定义智能体运行时。

CrewAI 的智能体是 ReAct 风格的工具循环；该框架最初使用 LangChain 的智能体机制组合它们。

权衡：

• ReAct 优势：经过验证的智能体原语。带工具的思考-行动-观察循环是充分理解的工具使用智能体原子。CrewAI 免费获得可靠的单智能体行为，并专注于多智能体层的创新。
• ReAct 优势：工具生态系统。最初构建在 LangChain 上，CrewAI 继承了大型工具库，加速了早期采用。
• ReAct 成本：依赖风险。依赖 LangChain 内部意味着 CrewAI 受其变动影响；CrewAI 后来迁移到自己更精简的智能体执行器以减少这一点。
• ReAct 成本：每智能体 token 成本。每个智能体运行自己的推理循环，所以 3 智能体团队可能发起许多 LLM 调用。CrewAI 用每智能体迭代上限和缓存缓解。

团队选择组合经过验证的智能体原语，而不是重新发明单智能体执行，将精力集中在编排层（角色、任务、流程）——他们真正的差异化。

模拟设计者思考

*我是 João Moura，2023 年末，我一直在用多智能体系统构建。我尝试的每个框架都让我像系统工程师一样思考：定义节点、接线、管理消息状态。它能工作，但有摩擦。我注意到一件事：当我向产品人员解释我在构建什么时，我从不说"条件边路由到工具节点"。我说"我有一个研究员智能体查找信息，然后交给写手智能体"。每个人都立即理解团队隐喻。框架让我用图思考，但人类用角色思考。*

*所以问题是：如果框架的原语就是团队隐喻本身呢？智能体不是节点——它是带角色（"高级研究分析师"）、目标（"找到最新的 AI 进展"）和背景故事（"你在顶级咨询公司花了 20 年综合趋势"）的队友。工作单元不是图计算——它是带描述和预期输出的任务。工作流动的方式不是拓扑——它是流程：流水线（顺序）或委派的管理者（层级）。*

*让我具体说明背景故事，因为它是不明显的部分。如果我只说 role="分析师"，模型给我通用的分析师输出。但如果我给它背景故事——关于它是谁以及为什么擅长这个的小叙事——输出变得更锐利、更有主见、更符合领域。背景故事是角色锚点。这是提示工程，但打包成非提示工程师也能编写的声明式字段。这就是整个设计哲学：把有效的提示工程动作变成声明式字段。*

*数据流：写手如何获得研究员的输出？不是我接线。写手的任务声明 context=[research_task]。就这样。"这个任务使用那个任务的输出。"项目经理能读懂。框架自动传递输出。图隐含在任务依赖中——我从不画图就得到 DAG。*

*编排：两个流程，因为那是团队实际工作的两种方式。顺序：流水线——研究、然后写作、然后编辑。层级：管理者看着任务和团队决定谁做什么——那是 supervisor 模式，但我自动生成管理者，所以开发者写零编排代码。大多数真实用例是这两者之一。我不会构建通用图引擎并让每个人都为需要它的 5% 情况学习它。*

*底层上，每个智能体是 ReAct 循环——思考、使用工具、观察、重复。我不重新发明那个；它是经过验证的原子。我的创新是上面的层：ReAct 循环如何组织成团队。我最初构建在 LangChain 上以免费获得工具，尽管我后来将智能体执行器收归内部以掌控自己的命运。*

*赌注：下一百万智能体构建者不是系统工程师。他们是产品工程师和领域专家，用角色和任务思考，而不是节点和边。说他们语言的框架赢得采用竞赛。CrewAI 就是那个框架。团队读起来像项目计划，这正是重点。*

关键启示与行业影响

CrewAI 最重要的贡献是证明角色/团队隐喻是真正有效的抽象，而不仅仅是营销面纱。角色/目标/背景故事模式产生比纯提示更一致的智能体行为，并使多智能体系统对非系统工程师可读。这大幅扩展了能够构建智能体系统的人群——可以说是 CrewAI 最大的市场影响。教训：与人们已经在思考问题的方式匹配的抽象，比他们必须学习的更强大抽象更有价值。

背景故事字段验证了角色锚定作为实用提示工程技术。简短的叙事身份使智能体更聚焦和符合领域，而 CrewAI 将其打包为声明式字段（而非临时提示文本）使其可复现和可审查。教训：有效的提示工程动作应该被提升为结构化、声明式的 API 字段。

以任务为中心的数据流（上下文依赖）证明了大多数生产多智能体系统是管道而非任意图。通过优化线性/管理者委派的常见情况并隐藏图，CrewAI 实现了比通用图框架大得多的简单性——以牺牲不寻常拓扑的表达力为代价。这是"工作流而非智能体"原则的具体实例：大多数团队需要结构化管道，而非通用编排引擎。教训：为人们实际使用的拓扑构建。

CrewAI 的轨迹——开源核心加带部署和可观测性的企业平台——反映了智能体框架新兴的商业模式：编排原语是开放的，而生产关注点（运行、监控、治理团队）是商业层。其主要技术批评（对非管道拓扑不如 LangGraph 灵活、层级流程不可预测性）定义了其适当用途：团队形状的、管道或委派的工作流。教训：框架对其不适用场景的诚实与对其适用场景同样有价值。

团队隐喻作为工程抽象

CrewAI 最深刻的洞见是：最好的抽象往往是用户头脑中已经存在的那个。当产品经理想"我需要一个研究员、一个写手和一个编辑"时，那是多智能体系统的完整且正确的心智模型——而 CrewAI 是让那个心智模型直接翻译成代码的框架，无需绕道图论或消息传递语义。这不仅是表面的便利；它是构建和——关键地——审查成本的实质性降低。团队定义读起来像项目计划，这意味着理解工作的领域专家可以审查智能体配置——这对于图定义是不成立的，只有系统工程师才能读懂。

这种可读性对正确性有二级效应。当抽象匹配问题时，意图和实现之间的不匹配变得可见。如果你的意思是"编辑审查写手的输出"，但任务接线说编辑在写手之前运行，理解团队隐喻的读者会发现它——流水线明显颠倒了。在不太可读的表示中，同样的错误隐藏在接线中。使结构可被非专家审查的抽象是真正的安全属性，CrewAI 的团队隐喻比任何基于图的替代方案更有效地提供它。

隐喻的诚实局限是它继承了所模仿事物的约束。真实团队是管道或管理者委派的工作；它们很少是带动态循环的任意图。CrewAI 的顺序和层级流程漂亮地覆盖团队形状的情况，在其余情况上 strained。这不是缺陷，而是范围声明：框架为人类协作的结构优化，正是那种优化使它快速使用和易于信任。框架设计的教训是：刻意的、充分沟通的局限——"我们做团队形状的工作流，而且做得非常好"——比服务所有人但都平庸的通用能力更有价值。

Microsoft AutoGen：从对话式智能体到基于 Actor 的运行时

概述

AutoGen 由微软研究院于 2023 年 9 月发布，是一个多智能体框架，其架构经历了智能体框架历史上最重大的重新设计之一。原始版本（v0.2）将多智能体系统建模为对话：智能体（如著名的 AssistantAgent 和 UserProxyAgent）在群聊中交换消息，对话本身就是计算。重写版本（v0.4，2025 年 1 月发布）用以对话为中心的核心的异步、事件驱动、基于 actor 的运行时取代，其中智能体是处理消息并发出事件的 actor，编排通过团队和终止条件表达。

v0.2 → v0.4 的重新设计本身就是智能体图工程中最有启发性的案例研究：它记录了一个研究团队对对话抽象局限的认识，以及为什么他们转向 actor 模型。v0.2 的对话模型对演示和研究很出色（智能体相互"交谈"直观且可检查），但在生产中碰壁：同步轮流无法扩展，群聊编排难以精确控制，状态管理是临时的。v0.4 的 actor 模型提供异步并发、显式消息传递、分布式部署和更清晰的编排原语——代价是失去一些对话的简单性。

AutoGen 的影响广泛：它普及了"智能体即对话参与者"范式，将群聊编排模式贡献给领域词汇，其 v0.4 架构是事件驱动智能体运行时的参考设计。

架构

v0.2（对话模型）。 原始架构：

• ConversableAgent：基类——可以发送和接收消息的智能体。子类：AssistantAgent（LLM 支持的助手）、UserProxyAgent（代表人类行动，可以执行代码和调用工具）。
• 双智能体聊天：agentA.initiate_chat(agentB) 开始来回对话。智能体交替发送消息，直到终止条件（最大回复数、"TERMINATE" 令牌、函数）。
• GroupChat：共享对话中的多个智能体。GroupChatManager 每轮选择下一个发言者（轮流、随机或 LLM 选择）。这是多智能体编排机制。
• 代码执行：AutoGen 的独特功能——智能体可以在沙箱执行器中编写和运行代码（带代码执行后端的 UserProxyAgent），实现"写代码 → 运行 → 观察错误 → 修复"循环。

v0.2 的计算就是消息历史。没有独立的状态对象；对话记录是共享状态，控制流是轮流协议。

v0.4（actor 模型）。 重写的架构有四层：

• Core（actor 运行时）：智能体是带 on_messages() 处理器的 actor。它们通过异步消息传递（直接消息或发布/订阅主题）通信。运行时可以在进程内运行，或跨进程/机器分布式运行。这一层语言无关（Python 和 .NET）。
• AgentChat：在 actor 核心之上重建熟悉的对话体验（AssistantAgent、UserProxyAgent、initiate_chat）的高级 API——保留 v0.2 的人体工程学。
• Teams：编排原语。团队是一组智能体+终止条件+（可选）选择器。RoundRobinGroupChat、SelectorGroupChat（LLM 选择下一个发言者）、Swarm（基于 handoff）。团队本身可组合——团队可以嵌套在另一个团队内。
• 终止条件：显式、可组合的停止规则（MaxMessageTermination、TextMentionTermination、TokenUsageTermination，用 | 和 & 组合）。这取代了 v0.2 的临时终止。

关键转变：在 v0.4 中，基本单元是处理消息并可能发出消息/事件的 actor，编排是对这些 actor 的团队策略。图是消息传递拓扑，变得显式和异步。

设计决策

决策 1（v0.2）：对话即计算 vs 显式状态/工作流对象。

原始 AutoGen 使消息历史成为全部状态，没有独立的工作流或状态模式。

权衡：

• 对话优势：直观和可检查。"智能体交谈"是任何人都能理解和调试的东西——你阅读记录。这使 AutoGen 对研究和演示非常出色，并推动了其快速早期采用。
• 对话优势：灵活性。任何交互模式都可以从对话中涌现；无需预定义结构。智能体可以自发地委派、纠正、协商。
• 对话成本：控制不精确。很难保证特定序列或强制某步骤恰好发生一次——对话由 LLM 选择和群聊管理者的启发式引导。
• 对话成本：状态无结构。一切都存在于记录中，所以提取结构化结果或精确恢复很笨拙。

v0.2 团队选择对话，因为他们的目标是研究涌现的多智能体行为——开放的对话模型正是重点。

决策 2（v0.4）：actor 模型 vs 保留对话核心。

v0.4 重新设计用异步 actor 运行时取代对话核心，将对话保留为高级便利层。

权衡：

• actor 优势：并发和规模。actor 是异步和独立的；许多可以同时处理消息。v0.2 的同步轮流（一次一个发言者）是吞吐墙。
• actor 优势：分布式。actor 运行时可以跨进程和机器（消息传递是自然边界）。v0.2 是单进程。
• actor 优势：精确编排。团队+显式终止条件给工程师对流程的确定性控制，同时在需要时仍允许 LLM 驱动的选择（SelectorGroupChat）。
• actor 成本：复杂性。actor/事件模型比"两个智能体聊天"更多概念。团队通过保持 AgentChat 层熟悉来缓解。
• actor 成本：迁移痛苦。v0.2 → v0.4 的 API 断裂迫使用户重写。团队通过长期过渡和兼容的 AgentChat API 管理这一点。

v0.4 团队选择 actor 模型，因为生产用户需要并发、分布式和精确控制——对话核心无法提供的东西，除非根本性改变。

决策 3（v0.4）：可组合终止条件 vs 临时停止。

v0.4 引入终止条件作为一等公民、可组合的对象。

权衡：

• 可组合优势：显式停止。MaxMessageTermination(10) | TextMentionTermination("APPROVE") 精确陈述团队何时停止。这是可审计和可测试的——相对 v0.2 依赖 LLM 发出 "TERMINATE" 是巨大的可靠性胜利。
• 可组合优势：条件代数。|（或）和 &（与）让工程师声明式地构建精确的停止逻辑。
• 可组合成本：多一个概念。开发者必须显式思考终止（尽管这可以说是功能而非成本——强制的终止思考防止失控循环）。

团队使终止成为一等公民，因为失控/无界对话是 v0.2 的头号生产抱怨。

决策 4：代码执行作为核心能力。

AutoGen（两个版本）将智能体在沙箱中执行代码视为一等公民功能，而非事后添加。

权衡：

• 代码执行优势：强大的行动空间。编写和运行代码让智能体比纯文本推理更可靠地解决计算任务（数据分析、数学、文件操作）。写-运行-观察-修复循环是最有效的智能体模式之一。
• 代码执行优势：锚定。代码执行给出具体、可验证的观察（代码运行了，产生 X，或报错 Y）。
• 代码执行成本：安全面。执行 LLM 生成的代码需要沙箱化（Docker、受限执行器）。AutoGen 在执行器隔离上大量投资。
• 代码执行成本：环境依赖。代码执行需要运行时环境，使部署复杂化。

团队使代码执行成为核心，因为他们的研究显示它大幅扩展了智能体能可靠完成的事情——它将智能体从文本生成器变成有真实效果通道的解决问题者。

模拟设计者思考

*我在微软研究院的 AutoGen 团队，这是两个设计的故事，因为我们必须在从第一个设计中学习后构建第二个。*

*2023 年。我们想研究多个 LLM 智能体协作时会发生什么。协作最自然的媒介是什么？对话。人类通过对话协调。所以我们使智能体可对话：它们发送消息、接收消息，整个系统是聊天。两个智能体——助手和可以运行代码的"用户代理"——来回交谈。助手写代码，用户代理运行它，把错误粘贴回来，助手修复它。看着很神奇，而且检查起来很简单：记录就是计算。我们添加带管理者选择发言者的 GroupChat，突然五个智能体在辩论问题。研究社区喜欢它。采用爆炸。*

*但然后生产用户到来，裂缝显现。"如何让智能体 B 总是在智能体 A 之后运行，恰好一次？"——难；对话由 LLM 引导。"如何并发运行一千个？"——轮流是同步的，一次一个发言者。"如何跨机器分布？"——单进程、单共享记录。"如何可靠地停止它？"——我们指望模型打印 TERMINATE。对开放研究完美的对话模型，对工程系统是束缚。记录即状态意味着没有可控制的结构、无可利用的并发、无可分布的边界。*

*所以我们回到第一性原理。剥离聊天隐喻，多智能体系统是什么？是一组通过交换消息协调的独立计算实体。这就是 actor 模型——Hewitt 1973 年的想法，在 Erlang 和 Akka 中为恰好这个场景验证过：并发、分布式、消息传递系统。智能体是 actor：它有处理器、处理消息、可以发送消息。默认异步。位置无关。运行时并发调度它们。这是生产用户需要的基底。*

*但我们不能抛弃使 AutoGen 受人喜爱的人体工程学。所以我们分层：底部是 actor 核心（能力、并发、分布式），顶部是 AgentChat 层，归还 AssistantAgent 和 initiate_chat——对话作为便利，而非约束。我们正确重建编排：团队是 actor 集合加策略。想要确定性用 RoundRobin。想要 LLM 选择发言者用 SelectorGroupChat。handoff 用 Swarm。终止——这是我最自豪的——成为可组合代数：MaxMessageTermination(10) | TextMentionTermination("DONE")。你声明团队何时停止。不再指望模型说再见。*

*我们活出来的教训：使系统直观（对话）的隐喻和使其生产级（actor）的基底是不同的东西。我们需要第一个来发现这个领域，需要第二个来服务它。v0.4 是我们承认智能体框架的核心应该是无聊的、经过验证的并发模型——魔法应该是上面的一层，而非基础。*

关键启示与行业影响

AutoGen 的 v0.2 → v0.4 重新设计是研究抽象与生产基底之间差距的领域最佳记录教训。对话模型对探索涌现的多智能体行为是理想的（直观、灵活、可检查），但无法提供生产要求的并发、分布式和精确控制。团队的解决方案——经过验证的 actor 模型核心加对话作为人体工程学层——是分离框架基底与用户体验的参考模式。教训：使系统易于发现的抽象，很少是使其生产级的抽象。

这次重新设计验证了 actor 模型作为智能体运行时合适基础。智能体作为异步、消息传递、位置无关的 actor，干净地映射到并发、分布式智能体系统的需求——并借鉴了数十年经过验证的工程（Erlang、Akka）。这影响了其他框架认真对待异步/事件驱动设计。教训：智能体编排是并发问题，而并发有成熟的文献。

AutoGen 的可组合终止条件通过将停止变为显式、声明式、可测试的关注点，解决了对话智能体最常见的生产失败——失控循环。这将终止从实现细节提升为一等公民设计元素。教训：智能体系统的停止条件值得与行为同样多的设计关注。

AutoGen 的代码执行能力确立"智能体编写和运行代码"为主流智能体模式，证明真实的效果通道（执行 → 观察 → 修复）大幅扩展了智能体在计算任务上的可靠性。教训：给智能体一个可验证的作用于世界的方式（而非仅描述行动），是能力的阶跃式提升。

actor 模型基础与智能体系统的未来

actor 模型基础也使 AutoGen 很好地定位在长时间运行、分布式智能体系统的新兴时代。随着智能体从单请求助手转向跨机器、带间歇连接、协作数小时或数天的持久工作者，actor 模型提供的属性（位置透明、独立失败、基于消息的协调）变得不仅方便而且必要。AutoGen 对这一基底的早期投资——诞生于其第一代艰苦教训——是前瞻性的资产：从一开始就将智能体视为并发、分布式 actor 的框架，将比必须将并发性追溯改造到对话核心的框架老得更好。v0.4 重新设计，回顾起来，与其说是重写不如说是重建——其架构是从自己第一个版本中学习的案例研究。

LlamaIndex Workflows：事件驱动的智能体 DAG

概述

LlamaIndex Workflows 由 LlamaIndex（Run-Llama）于 2024 年中发布，是一个构建在事件驱动、基于步骤的 DAG 模型之上的智能体编排框架。Workflow 是一组步骤（steps）——用 @step 装饰的 Python 函数——每个步骤消费特定类型的事件并发出事件。框架的运行时是事件总线：当步骤发出事件时，每个声明该事件作为输入的步骤变得有资格运行。计算是一个有向无环图，其边是事件类型，从步骤的签名自动发现，而不是显式声明。

Workflows 来自一个核心产品是数据编排（为 LLM 索引和检索文档）的团队。他们进入智能体领域受其传统影响：他们将智能体控制流视为数据流问题，并应用流处理和 ETL 系统熟悉的事件驱动模式。结果是一个对智能体 RAG 特别自然的模型——多步检索管道，其中每个阶段（查询转换、检索、重排序、评估、可能重新检索）发出触发下一阶段的事件。

Workflows 的独特贡献是：(1) 从事件类型推导控制流（无显式边声明），(2) 在同一模型中一等公民支持 DAG 管道和循环智能体循环，(3) 从事件图自然产生的可视化和步骤调试故事。它通过提供显式状态机图的轻量级、事件中心替代方案与 LangGraph 竞争。

架构

步骤（Step）。 步骤是用 @step 装饰的方法。其签名声明输入和输出：

@step
async def retrieve(self, ev: QueryEvent) -> RetrieveResultEvent:
    ...

步骤接收事件（或多个事件）并返回事件（或 None）。类型注解就是接线：运行时看到"RetrieveResultEvent 在这里产生"和"其他某步骤消费 RetrieveResultEvent"，并连接它们。

事件（Event）。 事件是在步骤之间携带状态的类型化数据对象（Pydantic 模型或 dataclass）。事件既是边又是数据：当步骤返回 RetrieveResultEvent 时，运行时将其投递给签名接受它的每个步骤。

事件总线/运行时。 Workflow 运行时：

1. 通过向接受它的步骤发送 `StartEvent`（携带初始输入）开始。
2. 维护 (步骤, 事件) 对的队列。当步骤的输入事件满足时，步骤运行（异步）。
3. 收集发出的事件并分发给消费者步骤。
4. 当步骤返回 `StopEvent`（携带最终结果）且没有待处理工作时终止。

独立步骤并发运行（运行时是异步的）。整体结构是事件类型上的 DAG——但因为步骤可以发出先前步骤消费的事件，循环（智能体循环）也可表达。

上下文（Context）。 每运行的 Context 对象提供跨步骤状态（键值存储），所以步骤可以共享不自然是事件的数据。这用可变便签本补充事件传递。

人机协同。 步骤可以 await ctx.wait_for_event(...) 或使用 HumanResponseEvent 模式：工作流暂停（可序列化上下文）、等待外部输入并恢复。事件驱动模型使暂停自然——工作流只是"等待尚未到达的事件"。

可视化和调试。 因为图从事件类型派生，LlamaIndex 可以自动绘制工作流 DAG（通过 Arize Phoenix 等集成），让你检查/单步执行每个事件转换。

设计决策

决策 1：从事件类型推导控制流 vs 显式声明边。

Workflows 从步骤的事件签名推导图，而不是要求开发者声明边。

权衡：

• 推导接线优势：更少样板、更少错误。你从不写"连接节点 A 到节点 B"——你只声明 A 发出 XEvent、B 消费 XEvent。接线不会偏离数据流，因为它就是数据流。
• 推导接线优势：重构安全。只要事件契约成立，重命名/重构步骤是安全的；运行时重新推导图。
• 推导接线成本：间接可读性。要理解拓扑，你必须跨步骤签名追踪事件类型，而不是阅读边列表。对复杂工作流，这可能比显式图更难。
• 推导接线成本：意外耦合。恰好共享事件类型的两个步骤被连接，这可能令人惊讶。通过使用不同、命名良好的事件类型缓解。

团队选择推导接线，因为它匹配数据流工程师的思维方式（来自 ETL/流处理世界），并消除整类"声明的边与实际数据不匹配"的 bug。

决策 2：支持循环的事件驱动 DAG vs 严格 DAG。

Workflows 以 DAG 为先，但允许循环（步骤发出上游步骤消费的事件），使智能体循环成为可能。

权衡：

• DAG+循环优势：管道和智能体一个模型。线性 RAG 管道和循环 ReAct 智能体都可表达为工作流。团队不必构建两个系统。
• DAG+循环优势：智能体 RAG 是原生的。旗舰用例——检索、评估相关性、不足则循环回去重新检索——是带一个刻意循环的 DAG。Workflows 直接表达这一点。
• DAG+循环成本：终止风险。循环可能永远循环；运行时提供 timeout 和步骤数防护，但开发者必须设计出口。
• DAG+循环成本：静态分析更难。纯 DAG 分析简单；允许循环使可视化和推理复杂化。

团队允许循环，因为他们的核心用户（RAG 工程师）需要检索-评估-重试循环，禁止循环会把最重要的模式推出框架。

决策 3：事件作为类型化 Pydantic 对象 vs 无类型字典。

Workflows 要求事件是带模式的类型化对象。

权衡：

• 类型化优势：接线推导依赖类型——类型化事件使基于签名的接线成为可能。类型还给出验证（格式错误的事件尽早失败）和 IDE 支持。
• 类型化优势：自文档化数据流。事件模式精确记录跨越每条边的数据。
• 类型化成本：仪式。每条边需要事件类，比传递字典更多代码。
• 类型化成本：刚性。改变事件模式需要一起更新生产者和消费者（尽管这也是安全功能）。

团队选择类型化事件，因为整个模型依赖类型推导的接线——无类型事件会使设计崩溃。

决策 4：异步优先运行时 vs 同步执行。

Workflow 运行时是异步的；独立步骤并发运行。

权衡：

• 异步优势：吞吐。可以并行运行的步骤（例如同时从三个索引检索）自动如此。对 I/O 密集的智能体工作（LLM 调用、检索），这是巨大的胜利。
• 异步优势：自然暂停。人机协同和长时间等待只是"等待事件"——异步使挂起便宜和干净。
• 异步成本：简单情况的复杂性。线性管道从异步中一无所获，但支付 async/def 仪式。
• 异步成本：并发 bug。跨并发步骤的共享可变状态（通过 Context）需要小心。

团队选择异步，因为智能体工作负载由并发 I/O（多个 LLM/检索调用）主导，而事件总线模型自然映射到异步运行时。

模拟设计者思考

*我在 LlamaIndex 团队，2024 年，我们的用户两年来一直在用我们构建 RAG 管道。管道变得越来越智能——查询重写、多索引检索、相关性评估、重新检索。我们现有的"查询管道"抽象线性地链接步骤，但这些新的智能体管道分支和循环。查询扇出到三个检索器，结果合并，评估者决定"不够，回去"。那不是链。那是带循环的图。我们需要新的编排模型。*

*我们知道什么？我们是数据编排公司。我们的用户用数据流思考：这个阶段产生文档集，那个阶段消费它。我们知道的最干净的数据流模型是事件驱动：阶段发出事件，关心该事件的人做出反应。像消息总线。所以让我们使工作流成为事件总线。步骤是说"给我一个 QueryEvent，我给你一个 RetrieveResultEvent"的函数。运行时观察类型并将它们连接起来。开发者从不画边——边由数据契约暗示。*

*这有美丽的结果：接线不会说谎。在独立于数据声明边的框架中，边可能偏离代码实际传递的东西。这里，边就是数据类型。如果步骤 B 消费 RetrieveResultEvent，它就连接到产生它的任何东西。自由重构；图自己重新推导。*

*现在是循环。检索-评估-重试循环是智能体 RAG 的核心。我的评估者步骤消费 RetrieveResultEvent 并发出 SufficientEvent（继续）或再次 QueryEvent（重试）。等等——QueryEvent 被检索步骤消费，那是上游。所以我通过事件总线创建了循环。允许吗？如果允许，一个模型覆盖直管道和循环智能体。我允许它，带超时使其不能永远旋转。DAG 是常见情况；循环是使智能体成为可能的逃生通道。*

*状态：大多数数据作为事件流动，但有些东西是环境的——运行计数器、标志、累积的上下文。我添加 Context 对象，每运行的键值便签本。数据流用事件，环境状态用 Context。干净分离。*

*并发性随事件总线免费而来：如果三个步骤就绪（它们的事件已到达），全部运行，异步。我的用户的管道从多个来源检索；现在默认并行。人机协同只是"等待人类将产生的事件的步骤"。暂停、序列化上下文、事件到达时恢复。事件模型使挂起自然。*

*赌注：RAG 工程师——我们的人——如果智能体看起来像他们已经在做的数据流，将最快采用智能体。不是要学习的状态机，不是要编写的对话。只是步骤和事件，他们一直以来构建管道的方式。智能体是恰好循环的数据流。*

关键启示与行业影响

LlamaIndex Workflows 最独特的贡献是从数据契约推导控制流：从步骤的事件类型签名推导编排图。这消除整类"声明的拓扑与实际数据流不匹配"的 bug，并使重构安全。这是数据流/流处理思维导入智能体编排的直接成果，并在 RAG 工程社区引起强烈共鸣。教训：当你的用户已经用数据流思考时，使控制流成为数据流的投影。

该框架验证了单一事件驱动模型可以跨越线性管道和循环智能体循环。检索-评估-重试循环——标准智能体 RAG 模式——只是带一个刻意循环的 DAG，与直管道在同一模型中可表达。这种统一视图（管道和智能体是一个谱系上的点）强化了行业远离严格工作流-智能体二分的趋势。教训：管道/智能体的区分是谱系，好的框架跨越它。

Workflows 的类型化事件设计展示了强约束（事件必须是类型化对象）如何实现强大功能（签名推导的接线）。定义事件类的仪式是自接线、自文档化、重构安全编排的代价。教训：精心选择的约束可以是功能生成器。

异步优先、事件总线运行时使并发步骤执行和自然人机协同暂停从架构中产生，而不是后来添加。这证明智能体框架受益于构建在经过验证的并发隐喻（事件总线/actor）之上，而非定制执行循环。教训：从并发文献借鉴运行时模型；不要重新发明。

事件驱动模型与智能体组合的未来

随着智能体系统从单个工作流成长为协作智能体网络，事件驱动模型显示其前瞻性优势。事件是独立拥有的智能体之间的自然接口：一个智能体发出事件，另一个做出反应，两者都不需要知道对方的内部——只需要共享的事件契约。这种松耦合正是大型、演进的多智能体系统所需要的，因为它让你添加、替换和扩展智能体而无需重新接线中央图。LlamaIndex Workflows 体现的"工作流即事件总线"模式，微观上是消息传递多智能体系统的架构——它暗示随着智能体组合成熟，这个领域可能收敛到事件契约作为智能体之间的标准接缝，就像 API 成为服务之间的标准接缝一样。

这一轨迹也突出了事件模型的治理优势。当步骤之间（最终智能体之间）的每次交互都是类型化、记录的事件时，系统的整个协调面在构造上就是可观察和可审计的。你不需要检测工作流来看它的数据流——数据流就是检测。对于构建必须被解释和治理的智能体系统的团队，这个属性价值巨大，并主张在拓扑允许的地方采用事件中心设计。

平衡的观点是事件驱动和状态机模型是互补而非竞争的：状态机在控制流是主要关注点且必须紧密约束的地方出色，而事件驱动设计在数据流和松耦合是主要关注点的地方出色。成熟的智能体工程师将两者都放入工具箱，根据系统性质选择——或混合它们，安全关键核心用状态机，可插拔外围用事件驱动阶段。LlamaIndex Workflows 的持久贡献是使事件驱动的那一半工具箱成为一等公民、符合习惯、并对已经用数据流思考的工程师可访问。

Pydantic AI：类型安全的智能体工程

概述

Pydantic AI 由 Pydantic 团队（Python 主导数据验证库的创建者）于 2024 年末发布，是一个将 Pydantic 成功的原则——严格类型、验证和开发者人体工程学——应用于 LLM 智能体的智能体框架。其核心论点是：智能体的可靠性问题很大程度上是*类型安全*问题，而为 Python API 解决数据验证的工具（Pydantic 模型、静态类型、依赖注入）可以为智能体解决这些问题。

Pydantic AI 通过刻意做得比竞争对手少来进入拥挤的领域。它不是多智能体编排框架，不是图引擎，不是工作流构建器。它是构建单个、类型良好、可靠智能体的框架——带结构化输出（Pydantic 模型）、类型安全工具定义、提供工具和上下文的依赖注入系统、带验证的流式传输和模型无关支持（OpenAI、Anthropic、Gemini、Groq、Mistral 等）。赌注是：大多数生产智能体需求是"一个智能体，做一件事，正确且可预测"，框架应该使这一点坚不可摧，而不是增加编排复杂性。

该框架的设计反映了对智能体框架格局的特定批评：框架如此专注于多智能体编排，以至于忽视了使单个智能体的输入、输出和工具安全、可验证的基本功。Pydantic AI 的回答是将智能体的契约——它接受什么、返回什么、有什么工具——视为类型化、经过验证的接口，就像设计良好的 API 一样。

架构

智能体（Agent）。 Agent 由两个泛型类型参数化：Agent[Deps, OutputType]——依赖类型和输出类型。这使智能体的契约成为其静态类型的一部分：

agent = Agent('openai:gpt-4o', output_type=CityInfo, deps_type=WeatherDeps)

类型参数意味着 IDE 和 mypy 知道智能体返回什么、需要什么依赖——不匹配在类型检查时捕获，而非运行时。

结构化输出。 output_type 是 Pydantic 模型（或模型的联合）。智能体被约束产生符合该模式的输出——通过模型的结构化输出/工具调用机制——结果由 Pydantic 验证。如果模型的输出验证失败，Pydantic AI 可以将验证错误反馈给模型重试。这将"LLM 返回了 JSON"变成"LLM 返回了*经过验证的* CityInfo"。

工具（Tools）。 工具是用 @agent.tool 装饰的 Python 函数。其参数和返回类型是类型化的；框架从类型提示生成工具模式，并在进入时验证参数、在出去时验证结果。从模型收到坏参数的工具得到干净的验证错误，而非崩溃。

依赖注入。 deps_type 是传递给运行并注入工具和动态系统提示的类型化对象。这是框架对"工具如何获得数据库连接/用户上下文/配置？"的回答——工具声明 RunContext[Deps] 参数并接收类型化依赖，而不是全局变量或闭包。这使工具可测试（注入假依赖）并使智能体的需求显式。

系统提示函数。 系统提示可以是静态字符串或函数 (RunContext, ...) -> str，从依赖动态组合提示。可以注册多个提示函数并连接。

运行循环。 底层上，智能体运行 ReAct 风格的循环：调用模型 → 如果请求工具，运行它们（经过验证）→ 反馈结果 → 重复直到模型产生最终输出 → 针对 output_type 验证输出 → 返回类型化 RunResult。循环有 max_retries 限制。

流式传输。 流式传输以独特设计支持：你可以流式传输最终结构化输出（token 到达时的部分 Pydantic 模型验证）和流式传输工具调用事件，与非流式相同的类型安全。

模型无关性。 薄的 Model 抽象包装提供者。切换模型是改变字符串（'openai:gpt-4o' → 'anthropic:claude-sonnet'）。框架规范化跨提供者的工具调用和结构化输出差异。

设计决策

决策 1：单智能体聚焦 vs 多智能体编排。

Pydantic AI 刻意不提供多智能体编排（核心中没有 supervisor、没有图、没有 handoff）。

权衡：

• 单智能体优势：深度优于广度。通过聚焦一个智能体，团队可以使每个方面（类型、验证、重试、流式、测试）出色，而不是将精力分散在大多数用户不需要的编排功能上。
• 单智能体优势：可组合性。类型良好的单智能体是干净的构建块。多智能体系统可以通过在其他智能体的工具内调用智能体来组合——框架保持简单，用户在其上构建复杂系统。
• 单智能体成本：不是一站式商店。想要内置编排的团队必须看别处（或手动组合）。团队接受这一点，主张编排通常在普通代码中做得更好。
• 单智能体成本：市场定位风险。在痴迷多智能体的领域，单智能体框架可能被忽视。

团队选择单智能体，因为他们的研究显示主导的生产需求是可靠的单智能体，而且大多数"多智能体"系统更好地表达为在普通代码中组合的几个类型良好的智能体。

决策 2：智能体上的泛型类型参数 vs 无类型智能体。

Agent[Deps, OutputType] 使契约成为静态类型。

权衡：

• 类型化优势：编译时安全。传递错误的依赖或误用输出类型被 mypy/IDE 捕获。这是应用于智能体的 Pydantic 哲学：将错误从运行时转移到类型检查时。
• 类型化优势：自文档化。类型签名显式陈述智能体的契约——它需要什么、返回什么。
• 类型化成本：泛型类型复杂性。Python 泛型可能令人困惑；一些用户觉得 Agent[Deps, OutputType] 令人生畏。
• 类型化成本：与动态使用的摩擦。高度动态的场景（运行时选择输出类型）与静态模型斗争。

团队选择泛型，因为类型安全是整个价值主张——稀释它会使框架与竞争对手无法区分。

决策 3：工具/上下文的依赖注入 vs 全局变量或闭包。

工具接收类型化的 RunContext[Deps]，而不是伸手去拿全局状态。

权衡：

• DI 优势：可测试性。在测试中，你注入假依赖（内存数据库、打桩的 API）。无需猴子补丁全局变量。这是框架用户引用采用的第一大原因。
• DI 优势：显式需求。依赖类型精确记录智能体需要从环境获得什么。工具不能秘密依赖环境状态。
• DI 成本：仪式。定义依赖类型并将其贯穿比闭包更多代码。
• DI 成本：学习曲线。DI 对一些 Python 开发者是不太熟悉的模式。

团队选择 DI，因为它是"如何测试接触世界的代码"的标准解决方案，而可测试性是核心生产需求。

决策 4：带验证错误重试的验证结构化输出 vs 尽力 JSON。

智能体必须产生针对 Pydantic 模式验证的输出，失败时带错误反馈重试。

权衡：

• 验证优势：可靠性。下游代码收到保证有效的对象，而非可能有效的字典。这消除大类"LLM 返回了略错的 JSON"失败。
• 验证优势：自我纠正。将验证错误反馈给模型让它修复自己的输出——便宜、有效的修复循环。
• 验证成本：失败时的延迟。验证失败花费额外的模型调用。
• 验证成本：模式刚性。输出必须适合模式；真正新颖的输出受约束。（通过多形状结果的联合输出类型缓解。）

团队选择验证输出，因为不可靠的结构化输出是他们从用户那里听到的最常见生产痛点。

模拟设计者思考

*我在 Pydantic 团队，我们花了多年使 Python 数据安全。Pydantic 的存在是因为"API 返回了字典，我希望它有正确的字段"不是工程基础。我们在边界验证，我们使类型真实，我们在边缘捕获错误而不是在业务逻辑深处。现在我看着智能体世界恰好建立在我们花了十年 discredit 的基础上："LLM 返回了一些 JSON，让我们 .get() 过去并祈祷。"*

*所以这是我的假设：大多数智能体不可靠不是模型问题，是类型安全问题。模型通常接近。但周围的系统把它的输出视为无类型 blob，把它的工具视为未验证函数，把它的上下文视为环境全局。每一个都是错误可以隐藏的地方。我知道如何修复每一个，因为 Pydantic 已经做到了。*

*从输出开始。智能体应该返回 Pydantic 模型，而非字符串。我设置 output_type=CityInfo，框架强制模型产生 CityInfo——通过结构化输出——并验证它。如果验证失败，我把错误交还给模型并说"修复它"。现在智能体的返回值像类型良好的 API 响应一样可信。契约是真实的。*

*接下来是工具。工具是带类型化参数的函数。我从类型提示生成模式——没有手写 JSON 模式会不同步。当模型用坏参数调用工具时，Pydantic 验证它们并返回模型可以学习的干净错误，而不是堆栈跟踪。工具边界是安全的。*

*现在是难题：工具如何获得数据库连接？业余答案是全局或闭包。我们从十年 API 代码知道的答案是依赖注入。我给智能体 deps_type——持有它需要从环境获得的一切的类型化对象——工具声明 RunContext[Deps] 来接收它。在生产中，你注入真实数据库。在测试中，你注入假的。突然智能体可测试了，而可测试性是演示和系统的分界线。*

*我使整个东西静态类型化：Agent[Deps, OutputType]。你的 IDE 知道智能体返回什么。如果你传递错误的依赖，mypy 捕获你。智能体的契约在其类型签名中，就像好函数的契约在其签名中一样。*

*我不构建什么？图引擎。Supervisor。Handoff。这个领域痴迷于编排十个智能体，但我看生产，发现大多数团队需要一个智能体，做一件事，正确地。当他们确实需要多个智能体时，最干净的编排通常是在普通代码中调用类型良好的智能体——我的框架使其安全。我宁愿钉住单智能体，而不是平庸化十个功能。*

*赌注：随着智能体进入生产，赢的团队将是那些像对待软件一样对待它们的团队——类型化契约、验证边界、依赖注入、测试。不是那些有最精致编排的团队。Pydantic AI 是智能体工程应该继承我们从 API 工程学到的一切的论点。*

关键启示与行业影响

Pydantic AI 的核心贡献是确立智能体可靠性很大程度上是类型安全和验证问题。通过将 API 工程的成熟技术——验证的结构化输出、类型化工具模式、依赖注入、静态类型——应用于智能体，它表明"智能体不可靠"的很大一部分实际上意味着"智能体的边界未经验证"。这种重构影响整个领域转向结构化输出和类型化工具作为默认。教训：在增加更多模型能力或更多编排之前，验证你的边界。

依赖注入系统使智能体真正可测试，这是生产采用的先决条件。通过给工具类型化的 RunContext 而非环境全局，Pydantic AI 让团队用假依赖单元测试智能体——将智能体开发从提示-祈祷变成普通软件工程。教训：可测试性不是可有可无；它是区分演示和系统的功能。

单智能体聚焦是得到回报的逆向赌注：当竞争对手竞相添加多智能体功能时，Pydantic AI 通过擅长最常见的生产需求——一个可靠的智能体——赢得采用。它的论点——多智能体系统通常更好地由普通代码中组合的类型良好单智能体表达——引起务实团队的共鸣。教训：在编排多个之前掌握原子单元。

带重试的验证输出循环（将验证错误反馈给模型）演示了便宜、有效的自我纠正机制，将模式违反变成可恢复事件而非失败。这种模式——验证作为反馈信号——是更广泛原则的具体实例：结构化约束提高智能体可靠性。教训：模型可以看到并修复的模式，比完美的提示更有价值。

类型安全作为智能体可靠性战略

Pydantic AI 的核心论点——智能体不可靠的很大一部分是类型安全问题——值得仔细展开，因为它重构了团队应该在哪里投资可靠性努力。当智能体"失败"时，失败往往不是模型推理糟糕；而是模型周围的系统太宽容。输出是可能有也可能没有正确键的字典。工具参数是模型恰好产生的任何东西。上下文是测试无法控制的环境全局状态。每一个宽容的边界都是错误可以进入和隐藏的地方。Pydantic AI 的贡献是使每一个边界严格和经过验证：输出必须符合模式，工具参数在入口检查，依赖被注入和类型化。这种强化之后，剩下的失败是真正的模型失败——而那些是你只能通过更好的提示、更好的模型或更好的评估来修复的。

这是一个强大的诊断镜头：如果你的智能体不可靠，首先问多少不可靠是模型的，多少是你自己宽容管道的。团队经常惊讶地发现相当大的比例——有时是大部分——是管道。模型产生了几乎正确的结构化输出，代码解析错了；工具收到了微妙错误的参数；测试无法重现因为上下文每次运行都不同。修复管道比改进模型更便宜、更确定，而且完全在工程师控制之内。

更广泛的教训将 Pydantic AI 与软件工程最深刻的传统联系起来：使非法状态不可表示，使无效输入无法静默通过。智能体边界——非确定性模型与确定性代码相遇的地方——正是这种纪律回报最高的地方，因为那是输入最不可信的地方。Pydantic AI 的持久贡献可能与其说是框架本身，不如说是将智能体的契约应该像其他 API 一样严格类型化的想法正常化——因为它就是 API，而它的调用者是你将拥有的最不可靠的客户端。

Supervisor 模式：多智能体系统的中央协调

概述

Supervisor 模式是部署最广泛的多智能体编排拓扑：一个中央 supervisor 智能体（带路由提示的 LLM）接收任务，决定哪个专门的工作者（worker）智能体应该处理它（或接下来处理），委派、收集结果，并重复直到任务完成。它是 Anthropic"编排者-工作者"工作流的多智能体实例，也是"我如何协调几个专门智能体？"问题的标准答案。

该模式的吸引力在于它将控制流集中在一个地方——supervisor——使系统的行为可审计、终止可控，同时将实际工作委派给每个都可以简单、聚焦、独立可测试的智能体。它直接镜像人类组织结构（经理委派给专家），使其对利益相关者可读，并自然映射到真实工作流（研究经理协调搜索者、分析师和写手）。

Supervisor 模式是一种图拓扑：supervisor 是枢纽节点，工作者是辐条节点，每条边都是 supervisor→工作者或工作者→supervisor。没有工作者-工作者边——所有协调通过枢纽流动。这种星型拓扑是该模式的定义性结构属性，也是其优势（中央控制）和弱点（枢纽瓶颈、supervisor 质量上限）的来源。

架构

Supervisor 节点。 supervisor 是带以下内容的 LLM 调用：

• 描述可用工作者及其能力的系统提示（"你有这些团队成员：researcher（查找信息）、coder（编写代码）、writer（生成散文）……"）。
• 发出路由决策的机制——通常是结构化输出或工具调用：{"next": "researcher"} 或 transfer_to_researcher() 调用，加上可选的给工作者的指令/上下文。
• 终止决策：任务完成时 {"next": "FINISH"}。

工作者节点。 每个工作者是一个智能体（通常是带自己工具和聚焦系统提示的 ReAct 循环）。工作者彼此不知道；它们从 supervisor 接收任务/上下文，做它们的工作，并返回结果。工作者可以像单个 LLM 调用一样简单，也可以像子图一样复杂。

控制循环。 执行是一个循环：

1. Supervisor 读取对话/状态并选择下一个工作者（或 FINISH）。
2. 选定的工作者运行，产生追加到共享状态的结果。
3. 控制权返回 supervisor。
4. 重复直到 supervisor 发出 FINISH（或达到最大迭代上限）。

作为图：supervisor ⇄ 每个工作者，supervisor 是唯一决策点。在 LangGraph 中，这用 supervisor 的条件边（基于其 next 输出路由）和每个工作者回到 supervisor 的固定边实现。

共享状态。 所有智能体读写共享状态（消息历史或结构化状态对象）。Supervisor 看到完整历史（所以它可以做出明智的路由决策）；工作者通常看到历史或过滤视图。

变体。

• 带工具调用工作者的 Supervisor：supervisor 像调用工具一样调用工作者（常见的 LangGraph/OpenAI-SDK 实现）。
• 层级 Supervisor：supervisor 的 supervisor——顶层 supervisor 委派给中层 supervisor，每个管理自己的工作团队。这将模式扩展到大型团队。
• Supervisor + swarm 混合：supervisor 处理宏观路由，工作者可以为微观协调直接 handoff。

设计决策

决策 1：中央 supervisor vs 去中心化对等智能体。

该模式将所有协调通过中央 supervisor 路由，而不是让智能体直接对话。

权衡：

• 中央优势：可审计的控制流。每个委派决策通过一个节点。你可以记录、检查和约束每个路由选择。这就是为什么该模式在受监管/企业环境占主导。
• 中央优势：终止控制。Supervisor（加上最大迭代上限）决定何时停止。没有智能体无限相互委派的风险。
• 中央优势：工作者简单。工作者不需要协调逻辑——它们只做自己的工作。这使每个工作者简单且独立可测试。
• 中央成本：枢纽瓶颈。每次交互需要 supervisor LLM 调用，增加延迟和成本。Supervisor 在一切的关键路径上。
• 中央成本：Supervisor 质量上限。系统只与 supervisor 的路由决策一样好。错误路由的 supervisor（把编码任务发给 researcher）降低整个系统，其提示随团队增长难以正确。

该模式选择中央化，因为对生产多智能体系统，控制和可审计性通常比原始效率更值得。

决策 2：工作者作为不透明智能体 vs 工作者作为工具。

Supervisor 可以将工作者作为自主智能体（运行自己的循环）或简单工具调用（单个函数）调用。

权衡：

• 智能体工作者优势：能力。每个工作者可以是带自己工具和多步推理的完整 ReAct 智能体。这对复杂子任务是必要的（"researcher"搜索、阅读和综合）。
• 智能体工作者成本：无界子执行。工作者智能体本身可以循环多次，使 supervisor 的成本/延迟预测困难。用每工作者迭代上限缓解。
• 工具工作者优势：可预测性。工具调用是一次函数调用——有界的成本和延迟。
• 工具工作者成本：能力较弱。工具不能做开放的多步工作。

实践中，该模式支持两者：简单能力是工具，复杂能力是子智能体。Supervisor 的接口（路由决策）两种方式相同。

决策 3：完全共享状态 vs 过滤的每工作者视图。

每个工作者是看到整个对话历史还是过滤子集。

权衡：

• 完全状态优势：上下文。工作者有完整信息，减少"researcher 不知道 coder 已经做了什么"的错误。
• 完全状态成本：上下文污染和长度。无关历史膨胀每个工作者的上下文（成本、延迟和注意力稀释）。工作者可能被无关的先前工作分心。
• 过滤视图优势：聚焦和效率。每个工作者只获得相关的（其任务+必要上下文）。更便宜、更聚焦。
• 过滤视图成本：信息丢失。过度过滤可能隐藏工作者需要的上下文。Supervisor 必须决定传递什么，这本身是路由质量问题。

生产实现通常给工作者摘要或过滤视图，supervisor 持有完全状态。这在上下文质量和成本之间平衡。

决策 4：LLM 选择路由 vs 确定性路由规则。

Supervisor 的路由决策可以是纯 LLM 判断，或由确定性规则引导/约束。

权衡：

• LLM 路由优势：灵活性。Supervisor 适应新颖任务和模糊请求，基于理解而非关键词选择工作者。
• LLM 路由成本：不可预测性。相同输入可以不同路由。难以保证行为。通过将选择约束到固定工作者集合（结构化输出）并添加护栏来缓解。
• 规则路由优势：确定性。已知请求类型总是相同路由。可测试和可预测。
• 规则路由成本：脆弱。规则在 LLM 能处理的新颖或模糊输入上失败。

常见的生产答案：约束到固定工作者集合的 LLM 路由（所以它不能发明路由），有时对明显情况有确定性预路由。这在有界、可审计的空间内获得灵活性。

模拟设计者思考

*我是智能体工程师，被要求构建一个研究主题、分析数据并撰写报告的系统。我可以给一个智能体所有工具和一个巨大的提示。但我学到，带十个工具和五段提示的单个智能体会困惑——它忘记自己在做哪个工作，它的提示一团糟。所以我想要专家：researcher、analyst、writer。问题是：谁协调它们？*

*选项一：让它们 peer-to-peer 对话。Researcher 交给 analyst，analyst 交给 writer。听起来优雅。但我立即看到问题。谁决定 analyst 完成、轮到 writer 了？我猜是 analyst——但 analyst 是 LLM，有时它过早交接，或交回去，或与 researcher 永远循环。当生产中出错时，我会阅读三个智能体的记录试图找到谁做了坏决策。去中心化协调难以构建、难以约束、难以调试。*

*选项二：老板。一个 supervisor 智能体，其唯一工作是协调。它读取任务，决定"我们首先需要研究"，派 researcher 工作，获得结果，决定"现在分析"，依此类推，直到它决定"我们完成了，这是报告"。每个决策流过一个节点。这就是真实组织的运作方式——你不会让组织结构图涌现，你有经理。它给了我生产恰好需要的东西：一个记录每个路由决策的地方、一个强制"10 轮后停止"的地方、一个路由出错时调整的提示。*

*所以 supervisor 的提示是我最重要的制品。它列出工作者和每个的用途。它说：检查状态，选择下一个工作者或 FINISH。我使它发出结构化选择——{"next": "researcher"}——所以它字面上不能路由到不存在的工作者。路由集合由我的模式约束。LLM 在我构建的笼子里行使判断。*

*每个工作者设计上简单。Researcher 不知道 analyst 存在。它获得任务（"查找关于 X 的信息"），用搜索工具做 ReAct 循环，返回结果。如果 researcher 坏了，我可以隔离测试——给它任务，检查输出。Supervisor 是唯一知道整个计划的地方。复杂性集中在我能管理的地方。*

*循环：supervisor → 工作者 → supervisor → 工作者 → …… → FINISH。它是 supervisor 在中心的星型图。我添加硬上限——比如 15 个 supervisor 轮次——因为即使提示良好的 supervisor 也可能犹豫不决，我不会发布无界循环。上限是我的保险单。*

*当团队增长到五六个以上工作者，supervisor 的提示变得笨拙时，我会添加一层：顶层 supervisor 委派给"研究 supervisor"和"写作 supervisor"，每个管理自己的工作团队。层级。再次镜像真实组织的扩展方式。但我从扁平开始，因为每层监督都是关键路径上的另一个 LLM 调用和另一个要维护的提示。*

*我在做的权衡，我自觉地做：我在每跳支付 supervisor 调用——额外延迟、额外成本——换取控制、可审计性和可调试性。对于错误委派花费真金白银或真实信任的生产系统，这是正确的权衡。Supervisor 模式不是最便宜的多智能体设计。它是最可治理的。而可治理性才是生产真正要求的。*

关键启示与行业影响

Supervisor 模式的主导地位确立中央协调是生产多智能体系统的默认拓扑。其星型图——所有控制通过一个枢纽——用吞吐量和成本换取可审计性、终止控制和可调试性，这些是企业实际采购的属性。教训：在生产多智能体系统中，可治理性胜过优雅。

该模式证明将协调复杂性集中在一个地方（supervisor）同时保持工作者简单和隔离是合理的分解。每个工作者变得独立可测试，supervisor 的路由提示成为单一调整面。这镜像微服务的洞见：清晰的所有权边界降低系统级复杂性。教训：集中难题（协调），简化其他一切。

Supervisor 的路由决策——LLM 从约束的下一步集合中选择——结晶了"LLM 在结构内决策"的设计原则。通过将路由编码为固定模式（结构化输出/工具调用），工程师在确定性保证内获得 LLM 灵活性。这种模式现在在智能体系统之外无处不在，出现在任何需要动态但安全控制流的智能体中。教训：给 LLM 菜单，而非开放领域。

该模式的已知失败模式——随团队增长的 supervisor 错误路由、枢纽延迟、supervisor 提示变成上帝提示——定义了其扩展极限，并激发了层级 supervisor 扩展。这是通用原则的具体实例：每个编排拓扑都有一个其协调节点成为瓶颈的规模，层级是标准补救。教训：为 supervisor 需要老板做计划。

Supervisor 模式何时是（和不是）正确选择

Supervisor 模式的流行可能导致过度应用，所以值得清楚陈述其选择标准。当你有多个真正不同的能力必须协调、协调逻辑不平凡（正确的工作者取决于任务的演进状态）、且可审计性和终止控制重要时——这是大多数生产环境——它是正确选择。当带多个工具的单个智能体就足够时（给单智能体任务添加 supervisor 只是增加路由调用和要维护的提示）、当工作流是固定管道时（用提示链——supervisor 增加你不需要的动态路由）、或当延迟关键且每个额外跳转是你无法支付的成本时，它是错误选择。

有用的启发式：当路由决策足够困难以至于你想要有能力的模型来做它，且错误路由的后果足够受 containment 以至于上限和日志使其可接受时，supervisor 才值得。如果路由显而易见，就硬编码。如果路由不可能正确，没有 supervisor 能救你——先修复工作者边界。Supervisor 是协调者，不是奇迹工作者；它放大工作者的质量和它们边界的清晰度，它不能替代任何一个。

该模式的演变也指向其可能的未来。随着模型路由能力改进，supervisor 的决策变得更可靠，这推动更多系统走向 supervisor/handoff 一端，远离手工编排。但可审计性需求同时增长——受监管行业需要解释每个委派——这拉回显式、记录、约束的路由。解决方案是我们已经看到出现的模式：选择真实但有界的 supervisor（固定工作者集合、记录的理由、硬上限），结合模型灵活性和工程问责。这种混合——笼子里的动态——是中央协调的持久形式，也是 supervisor 模式对该领域最重要的遗产。

反思与 Reflexion：自我批评循环

概述

反思（Reflection，Shinn 等人，2023，《Reflexion: Language Agents with Verbal Reinforcement Learning》）是 LLM 评估自己的输出并用该评估改进下一次尝试的智能体模式。核心结构是一个循环：生成器（generator）产生答案或行动；评估器（evaluator，相同或不同的 LLM）根据标准批评它；批评反馈给生成器，生成器产生修订的尝试；重复直到满意。Reflexion 通过将智能体的自我反思存储在情景记忆（episodic memory）中扩展了这一点，该记忆跨尝试甚至跨任务情节持久化，因此智能体在运行内"从错误中学习"，而无需任何权重更新。

反思是经过最稳健验证的智能体模式之一：原始论文显示在编码（HumanEval）、推理（AlfWorld、HotpotQA）和数学基准上有巨大收益，后续工作（Self-Refine、CRITIC 和 Anthropic 的"评估者-优化者"工作流）确认迭代自我批评可靠地改善具有可验证或定义明确标准的任务的输出质量。它是冻结 LLM 可用的"从经验中学习"的最小形式：由于推理时无法微调，你改为在上下文中积累言语化的教训。

作为图，反思是双节点循环——生成 → 评估 → （如果未完成）生成——评估器的裁决作为条件边。它是 Anthropic 评估者-优化者工作流的原子实例，也是更大智能体系统中的构建块（运行测试并修复的编码智能体、起草并修订的写作智能体）。

架构

生成器。 给定任务和累积上下文（先前尝试+批评）产生候选输出（代码、答案、计划）的 LLM。

评估器。 对生成器的输出产生质量信号。两种形式：

• 外部评估器：确定性检查器——测试套件（代码）、验证器、评分器。这是最强的形式：反馈是真相。
• 自我评估器（LLM 批评）：LLM（相同或独立）根据标准批评输出（"这正确吗？完整吗？是否处理了任务？"）。比真相弱，但适用于任何地方。

反思。 关于出了什么问题以及如何修复的自然语言总结。Reflexion 的关键动作是使这种反思*言语化并存储*："我失败是因为没有处理 X 为空的边缘情况；下次我应该在处理前检查空输入。"这比单纯的分数更有用，因为它给生成器可操作的指导。

情景记忆。 跨尝试积累反思的缓冲区（在上下文中）。每次新尝试，生成器看到任务+所有先前反思。这是"言语强化学习"：奖励信号（成功/失败）被转换为语言（反思）并用于偏置未来行为——全部无需梯度更新。

循环。

1. 生成器产生尝试 N（以任务+反思 1..N-1 的记忆为条件）。
2. 评估器评分/检查。
3. 如果通过（或达到最大尝试），返回。
4. 否则，产生关于失败的反思并追加到记忆；回到 1。

作为图：生成 ⇄ 评估，评估→生成边携带反思，评估器通过时有退出边。

滑动窗口/摘要。 因为记忆增长，Reflexion 限制它（保留最后 K 个反思，或摘要旧的）以适应上下文窗口。

设计决策

决策 1：言语化反思 vs 标量奖励（RL）。

Reflexion 将奖励信号转换为自然语言反思，而不是使用数值奖励和基于梯度的 RL。

权衡：

• 言语化优势：无需训练。与任何冻结 LLM 在推理时工作。LLM 上的 RL 昂贵且缓慢；言语反思只是提示。
• 言语化优势：可操作指导。反思（"处理空输入情况"）告诉生成器改变什么。标量奖励（0.3）对如何改变一无所知。
• 言语化优势：可解释性。你可以阅读智能体的自我诊断——对调试和信任 vô cùng 有价值。
• 言语化成本：反思质量受 LLM 自我评估能力限制。模型可以产生自信但错误的反思。
• 言语化成本：上下文增长。反思消耗上下文；长范围需要限制/摘要。

作者选择言语反思，因为它以零训练基础设施实现了 RL 式的"从试错中学习"——大幅简化使该模式立即可用。

决策 2：独立评估器 vs 同一模型的自我评估。

批评来自生成它的同一 LLM，还是独立的评估器。

权衡：

• 独立优势：减少自我偏见。评估自己输出的模型倾向于宽容（谄媚问题）。独立评估器（不同提示、不同模型或确定性检查器）给出更诚实的批评。
• 独立优势：专门化。评估器可以专门为批评提示/微调，或是更便宜/更快的模型。
• 独立成本：额外调用。每次迭代 LLM 调用翻倍。
• 同模型优势：便宜和简单。一个模型，交替生成/批评角色。
• 同模型成本：较弱批评。犯错误的模型通常无法从同一角度看到它。

最强的 Reflexion 结果在可能时使用外部评估器（代码的单元测试）。一般教训：优先真相评估；真相不可用时使用独立 LLM 评估器；同模型自我批评是最弱但最便宜的选项。

决策 3：跨尝试的情景记忆 vs 无状态重试。

Reflexion 跨尝试（和情节）存储反思，而不是每次尝试从头开始。

权衡：

• 记忆优势：累积学习。智能体避免重复同样的错误，因为它"记住"反思。这使重复尝试有成效而非随机。
• 记忆优势：跨情节迁移。Reflexion 显示一个任务情节的反思改善同一任务后续情节的表现——一种上下文内学习形式。
• 记忆成本：上下文管理。记忆必须限制（滑动窗口、摘要），否则溢出。
• 记忆成本：陈旧/误导反思。错误的反思可能持续存在并误导后续尝试。

作者选择记忆，因为它是将"重试"变成"学习"的机制。没有它，反思只是多了几步的重新生成。

决策 4：迭代直到验证器通过 vs 固定精炼次数。

循环是由评估器裁决控制（好时停止）还是固定迭代次数。

权衡：

• 验证器控制优势：效率和质量。输出好时立即停止（不过度精炼），坏时继续（不精炼不足）。需要可靠的评估器。
• 验证器控制成本：依赖评估器质量。坏评估器过早停止（接受坏输出）或永不停止。需要最大尝试上限作为后盾。
• 固定次数优势：可预测的成本/延迟。恰好 N 次迭代，总是。
• 固定次数成本：简单情况浪费迭代，困难情况服务不足。

生产系统使用带硬上限的验证器控制循环：评估器通过时停止，或 K 次尝试后停止，以先到者为准。这在适应难度的同时约束成本。

模拟设计者思考

*我是 Noah Shinn，2022 年，我在思考人类如何变得擅长事情。我们不只是盲目重试。我们失败，我们思考为什么，我们形成教训——"我 rushing 了边缘情况"——我们把那个教训带入下一次尝试。教训是语言。这是我们告诉自己的句子。现在看 LLM 智能体：它任务失败，我们……用相同提示重启并希望。它犯同样的错误。它没有机制把教训带向前，因为我们从不给它一个。*

*这是我在其下工作的约束：推理时我无法微调模型。权重是冻结的。所以"学习"不能在权重中发生。但模型读取它的上下文。所以学习可以在上下文中发生。如果我把教训写下来——作为文字——并把那些文字放入下一次尝试的上下文，模型的行为改变。这就是整个技巧：言语强化。奖励变成一个句子。*

*所以循环：尝试、评估、反思、重试。尝试是智能体做任务。评估告诉我它是否工作——对代码，我运行测试，那是真相，那是最好的情况。对推理，我可能使用启发式或另一个 LLM。反思是关键制品：不是"你得了 10 分中的 0 分"，而是"你失败是因为你假设列表非空；检查空列表"。我让模型写出自己的诊断，用文字，我保存它。*

*然后我构建记忆。每个反思进入缓冲区。下一次尝试，提示是：这是任务，这是你从过去失败中学到的。模型阅读自己的错误历史，然后——显著地——停止犯它们。这不是梯度下降。这是读你自己的日记。但在功能上，在基准上，它朝同一方向移动：HumanEval 用 GPT-4 从 80% 跳到 91%。这是来自句子的真实收益。*

*现在，模型的自我反思总是对的吗？不。它可以写出自信的错误诊断。这是诚实的局限。反思只与模型的自我评估一样好，这就是为什么我更喜欢真正的评估器（测试）而非模型给自己评分，也是为什么没有真相时独立批评模型有帮助。模式是合理的；反思质量是要观察的变量。*

*我必须限制记忆——最后几个反思的滑动窗口，或摘要——否则长任务的上下文溢出。我限制尝试次数，因为五次反思都不能解决的模型可能需要不同的方法，而非第六次。*

*我想留下的想法：一个在运行内改进的智能体，无需训练，通过将经验转换为语言。循环——生成、评估、反思、记住——是你可以在冻结模型上构建的最小学习系统。每个运行测试并修复的编码智能体、每个起草并修订的写作智能体，都是这个循环，穿着生产服装。*

关键启示与行业影响

反思确立冻结 LLM 可以通过将结果转换为存储在上下文中的言语教训在运行内"从经验中学习"。这种"言语强化学习"重构了无需训练的可能性，使试错改进成为标准智能体能力。教训：当你无法更新权重时，更新上下文——语言是记忆基底。

该模式的最强结果来自真相评估器（代码的单元测试），确立了从业者现在遵循的评估质量层级：确定性验证器 > 独立 LLM 评估器 > 同模型自我批评。这直接影响了行业对"给智能体检查工作的方式"（测试套件、linter、验证器）作为最高杠杆可靠性投资的强调。教训：有真正验证器的智能体比有更好提示的智能体可靠得多。

反思的评估者-优化者循环成为 Anthropic 五个标准工作流模式之一，也是生产系统的标准构建块（起草-修订写作、生成-测试-修复编码、提议-批评规划）。其跨领域（代码、推理、翻译）的稳健性使其成为单次输出不够好时首先尝试的默认模式。教训：带批评的迭代精炼是最便宜、最通用的可用质量改进。

该模式的诚实局限——自我批评质量受模型自我评估能力限制，可以产生自信的错误反思——是反对将反思视为灵丹妙药的警告。它在评估外部或标准清晰时效果最好；对没有好评估器的任务，反思可能原地打转。教训：反思放大好的评估器；它不能替代评估器。

现代智能体栈中的反思

在当代智能体系统中，反思很少作为独立模式出现；它被编织进更大架构的织物中，识别其化身是有用的。运行测试套件并修复失败的编码智能体是带真相评估器的反思。在执行前批评自己计划的规划智能体是应用于计划层面而非输出层面的反思。带专门批评者或审查者智能体的多智能体系统是外化的反思——评估器分离到自己的节点，以避免单模型的自我评估偏见。生产团队为写作、翻译和分析构建的评估者-优化者工作流是反思结构与调整到领域量表的评估器。该模式跨这些形式的持久性确认它捕获了根本的东西：改善冻结模型输出的最便宜方式是让它通过批评的镜头看自己的工作。

这种普遍性也阐明了反思与本集其他实践的关系。反思是运行时改进机制——它使单次运行更好。评估（evals 纪律）是开发时改进机制——它使系统跨运行更好。它们是互补的：你为 evals 构建的评估器通常可以用作反思循环的运行时批评者，你的反思循环无法修复的失败成为你最有价值的 eval 示例。连接这两个循环的团队——运行时自我纠正反馈到开发时评估——从两者获得复合改进。

反思的诚实前沿是自我评估的质量。随着任务变得更加开放，"模型能做任务"和"模型能可靠判断它是否做好了任务"之间的差距扩大，那个差距是反思停滞的地方。该领域的回应——更强的外部验证器、独立批评模型、过程监督——本质上是对循环的评估者一半的投资。生成器将随模型继续改进；评估器是你必须刻意工程化的部分。这是 Reflexion 的持久教训：循环只与其批评之眼一样强大。

规划者-执行者模式：将思考与执行分离

概述

规划者-执行者模式（也称 plan-and-execute、plan-and-solve）将智能体分为两个截然不同的角色：规划者（planner）在采取任何行动之前将高级目标分解为有序的具体步骤列表，执行者（executor）逐步执行这些步骤。在执行之后（或定期），计划可以根据学到的内容进行修订——重新规划步骤更新剩余步骤。这种"决定做什么"与"实际去做"的分离是复杂、多步骤智能体任务最古老、最有效的结构之一。

该模式解决了纯 ReAct 的根本弱点：逐步交替推理是短视的。ReAct 智能体一次决定一个行动，这对短范围有效，但在长任务上会漂移——它失去对整体目标的视线、徘徊，或无法正确排序依赖。规划者-执行者模式通过前置全局结构（计划）然后局部执行来修复这一点。它镜像人类处理复杂项目的方式：先概述，然后按概述工作，在学习中修订。

该模式的智识根源在经典 AI 规划（STRIPS 式任务分解）和"思维树"/"Plan-and-Solve"提示研究，后者显示显式分解改善 LLM 在多步推理上的表现。作为图，它是一个小循环：计划 → 执行步骤 → （需要时重新规划）→ 下一步骤 → …… → 完成，计划作为规划者和执行者都读写的持久状态对象。

架构

计划（状态对象）。 存储在智能体状态中的显式、有序步骤列表。每个步骤是具体、可操作的指令（"搜索公司 2023 年收入"、"提取收入数字"、"与 2022 年比较"）。计划是共享制品：规划者编写它，执行者读取它，重新规划者修订它。使计划成为一等公民状态对象（而非隐含在对话中）是该模式的定义性结构选择。

规划者。 LLM 调用（通常带聚焦分解的提示），接收目标并产生初始计划。好的规划者提示鼓励：分解为最小有用步骤、按依赖排序、在定义的终点停止。规划者不执行——它只产生结构。

执行者。 从计划中取当前步骤并执行——通常是带工具的 ReAct 子智能体（搜索、代码、计算）。它返回步骤结果，记录在状态中（通常是 (步骤, 结果) 对的 past_steps 列表）。执行者一次聚焦一个步骤，所以其上下文保持小、注意力不分心。

重新规划者。 一个或多个步骤之后，LLM 审查目标+已完成步骤+结果，并决定：剩余计划仍然有效吗？如果新信息使后续步骤无效（例如搜索揭示前提是错误的），重新规划者重写剩余步骤。这使该模式尽管有前期规划仍保持适应性。

控制循环。

1. 规划者产生初始计划。
2. 执行者运行第一步；记录结果。
3. 重新规划者检查：完成？（所有步骤完成 → 返回答案）或修订剩余计划。
4. 循环 2-3 直到完成（或达到上限）。

作为图：计划节点 → 执行节点 → 重新规划节点，重新规划节点路由回执行（继续）或 END（完成）。计划贯穿始终存在于状态中。

设计决策

决策 1：前期规划 vs 完全交替（ReAct）推理。

该模式在执行前承诺全局计划，而不是在当下决定每一步。

权衡：

• 前期优势：全局连贯性。计划捕获整体结构和依赖，防止长任务上逐步推理的漂移和短视。每一步在整个任务的上下文中选择。
• 前期优势：效率。规划者做一次调用来构造整个任务，而不是每一步重新推导"下一步该做什么"。执行者的每步决策便宜，因为步骤已经选好。
• 前期优势：可检查性和控制。计划是可审查的制品。人类（或验证器）可以在执行前检查计划——对高风险任务有价值。
• 前期成本：规划错误。错误的计划（基于不完整信息）可能使整个执行走上错误路径。通过重新规划缓解，但初始计划仍偏置执行。
• 前期成本：陈旧。世界可能在规划和执行之间变化。重新规划解决这个问题，但增加调用。

该模式选择前期规划，因为其目标任务（多步研究、报告、复杂工作流）有足够的结构使全局计划值得——不像 ReAct 灵活性获胜的高度反应性任务。

决策 2：状态中的显式计划对象 vs 对话中隐含的计划。

计划存储为结构化状态字段，而不仅是消息历史中的散文。

权衡：

• 显式优势：引用可靠性。执行者总是知道"当前步骤"，重新规划者总是知道"剩余步骤"，因为它们是结构化字段，而不是从散文中提取的东西。这消除整类"智能体忘记计划"的错误。
• 显式优势：机器可检查。你可以验证计划（非空、步骤是字符串、数量有界）、跟踪进度（M 之 N 完成）并强制完成。
• 显式成本：模式刚性。计划必须适合模式（步骤列表）。带分支或应急的丰富计划不适合扁平列表。
• 显式成本：仪式。比自由形式推理更多状态管理。

该模式使用显式计划对象，因为全部价值在于计划是可靠、可跟踪的制品——散文计划太容易被智能体丢失或误读。

决策 3：步骤后重新规划 vs 执行完整计划不修订。

该模式包含基于执行结果修订剩余计划的重新规划者。

权衡：

• 重新规划优势：适应性。修复静态规划的主要弱点——当执行揭示计划错误时，重新规划者调整路线。这使该模式稳健而非脆弱。
• 重新规划优势：纳入学习。早期步骤的结果（例如"API 没有返回数据"）为后续步骤提供信息（"使用不同的来源"）。
• 重新规划成本：额外 LLM 调用。每次重新规划是一次调用，增加成本/延迟。
• 重新规划成本：不稳定风险。过度热心的重新规划者可能抖动（每步重写计划，永不收敛）。通过仅在需要时或每 K 步重新规划缓解。

该模式包含重新规划，因为无修订的计划只与规划者的预见一样好，而这对真实任务是不可靠的。重新规划是使规划可行的反馈循环。

决策 4：执行者作为 ReAct 子智能体 vs 每步单个工具调用。

每个计划步骤由有能力的子智能体（带自己的工具循环）执行，而不是单个预定行动。

权衡：

• 子智能体优势：步骤稳健性。像"找到 2023 年收入"这样的步骤本身可能需要几个行动（搜索、精炼查询、提取）。ReAct 执行者处理这种内部复杂性，而不负担规划者。
• 子智能体优势：关注点分离。规划者决定做什么，执行者决定如何做。每个在其抽象的自然层面操作。
• 子智能体成本：无界子执行。执行者可以内部循环；需要自己的迭代上限。
• 子智能体成本：成本。每一步可能发起多个 LLM 调用。

该模式使用子智能体执行者，因为真实步骤很少是一个行动；给执行者自己的循环使计划保持正确的粒度（粗），同时在局部处理细粒度行动选择。

模拟设计者思考

*我在构建研究智能体，我看着纯 ReAct 在长任务上失败。我要求它"研究 X 市场的竞争格局并撰写报告"。它开始很好——搜索公司、阅读页面。但十步之后，它在追逐关于某公司 CEO 的切线，完全失去了报告的线索。它在真空中决定每一步，而真空没有结构。智能体每步聪明，每任务愚蠢。*

*问题很清楚：没有人告诉它整个任务的形状。所以让我添加一个唯一工作是形状的人。规划者。在一个行动之前，规划者看目标并写出步骤：识别主要参与者、研究每个、在关键维度上比较、起草报告、事实核查。现在执行有了脊柱。智能体不再从一无所有中问"下一步？"——它问"第 3 步是什么？"*

*我使计划成为真实对象——状态中的列表——因为如果它只是聊天中的散文，智能体会改述它、忘记它或重新解释它。我可以计数、跟踪和验证的列表。第 2 步，共 6 步，完成。这是工程，不是感觉。*

*但在任何行动之前制定的计划是假设。规划者不知道第一次公司搜索会揭示市场已经整合，现在只有三个参与者。所以我添加重新规划者：每步之后（或每几步），它读取目标、已完成步骤、结果和剩余计划，并问"其余的还正确吗？"如果结果改变了世界，它重写剩余步骤。现在我有两者的最佳：计划的连贯性和反馈的适应性。*

*执行者是自己的小智能体。我交给它"第 2 步：研究公司 A"，它做自己的搜索-阅读-提取循环，直到步骤完成。它不需要知道第 5 步。这种分离是整个设计：规划者在粗层面思考整体，执行者在细层面思考一步。两者都不被要求同时做两件事，这就是为什么两者都把工作做好。*

*循环：计划 → 执行步骤 → 重新规划 → 执行步骤 → …… → 重新规划者看到所有步骤完成并产生最终答案。这是小循环，但贯穿其中的计划对象给长任务结构。我限制步骤和重新规划，因为即使是好的结构也可能抖动。*

*我在做的权衡：我花费一个大的规划调用（和定期的重新规划调用）来购买全局连贯性。对两步任务，那是浪费——直接用 ReAct。对二十步任务，那是报告和切线的区别。规划者-执行者模式是这个问题的答案：我如何给逐步推理者以整体的感觉？你先写下整体，你让它在修改中学习写作。*

关键启示与行业影响

规划者-执行者模式确立将"决定结构"与"执行步骤"分离是长范围智能体任务的强有力分解。它通过前置全局结构直接解决 ReAct 的短视，仍然是复杂、多步骤工作（研究智能体、报告生成器、带任务列表的编码智能体）的默认架构。教训：长范围连贯性需要显式、持久的计划——它不会从逐步推理中涌现。

显式计划对象成为使智能体工作可检查和可控的模板。因为计划是结构化、可审查的制品，人类可以在执行前批准它（自然的人机协同检查点）、验证器可以检查它、进度可以跟踪。这使该模式自然适合需要监督的企业环境。教训：智能体和人类都能阅读的制品是协调点。

重新规划确立计划是要修订的假设，而非要遵循的承诺。计划-执行-重新规划循环是更广泛智能体工程主题的具体实例：结合前期结构与反馈驱动的纠正。纯规划是脆弱的；纯反应是短视的；两者之间的循环是可行的综合。教训：像你对的一样规划，像你可能错的一样重新规划。

该模式的已知成本——简单任务的规划开销、偏置执行的规划错误、重新规划者抖动——定义了其适当范围：它在足够长、足够结构化的任务上值得，使全局计划有帮助。对短或高度反应性任务，更简单的模式（ReAct、提示链）更好。教训：使编排复杂性与任务范围匹配。

计划作为智能体的工作记忆和契约

规划者-执行者模式一个被低估的属性是计划对象同时扮演两个角色：它是智能体对任务的工作记忆，也是规划阶段和执行阶段之间的契约。作为工作记忆，它解决真实的认知问题——LLM 不擅长在许多工具调用中记住二十步结构，计划外化那个结构，使没有步骤丢失或重复。作为契约，它使执行者的工作定义明确：它不必从展开的对话推断下一步做什么；它读取下一步。这种双重角色是该模式在长任务上比纯 ReAct 连贯得多的原因——计划既是记忆辅助又是规范。

这种双重角色也解释了为什么计划应该是结构化对象而非散文。散文计划（"首先我做 X，然后可能 Y……"）对什么完成、什么下一步、什么被放弃是模糊的。结构化计划（带状态的有序列表）是明确的：第 3 步，共 7 步，完成。结构使重新规划者可靠地做它的工作（它可以准确看到哪些步骤剩余），并让人类或监视器跟踪进度。结构的投资在触及计划的每个下游操作中回报。

该模式最重要的设计含义是它强制的抽象层面分离。规划者在目标和子目标层面推理任务；执行者在行动层面推理单个步骤。两者都不被要求同时持有两个层面，那种分离是该模式稳健性的来源——它匹配最优秀人类表演者的工作方式（架构整体，然后聚焦一片），它保持每个 LLM 调用的上下文小、注意力不分心。当智能体似乎"失去线索"时，补救方法几乎总是恢复这种分离：重新建立整体（计划）并缩小焦点（当前步骤）。规划者-执行者模式是那种补救方法的制度化。

智能体 RAG：检索-评估-纠正循环

概述

智能体 RAG 是检索增强生成从固定管道（查询 → 检索 → 生成）演进为评估自身检索并采取纠正行动的智能体循环。三篇里程碑论文定义了这个领域：Self-RAG（Asai 等人，2023）训练模型发出特殊的反思 token，决定何时检索以及检索内容是否相关和被支持；纠正 RAG（CRAG）（Yan 等人，2024）添加显式的检索评估步骤，对检索到的文档评分，并在检索不佳时触发网络搜索回退或文档精炼；自适应 RAG（Jeong 等人，2024）根据查询复杂性将每个查询路由到适当的策略（无检索、单步或多步）。它们共同确立了智能体 RAG 的核心洞见：检索不是智能体做的一次性预处理步骤，而是它做出、评估和修订的决策。

动机是朴素 RAG 充分记录的失败模式：检索质量是可变的，以坏检索文档为条件的生成器产生自信的错误答案（"垃圾进，圣旨出"）。固定管道无法注意到检索失败。智能体 RAG 闭合这个循环：检索后，智能体评估文档是否真正回答了查询，如果没有，它重写查询、搜索网络、过滤文档或分解问题——然后再试。这个检索-评估-纠正循环是带刻意循环的图，它是部署最多的智能体模式之一（LangGraph 的官方教程以 CRAG 和自适应 RAG 为标准示例）。

作为图，最简单的智能体 RAG（CRAG）是：检索 → 文档评分 → （相关？→ 生成；否则 → 重写查询/网络搜索 → 重新检索）→ 生成评分 → （被支持？→ 完成；否则 → 重新生成）。以评估结果为键的条件边使它成为智能体而非管道。

架构

检索-评估-纠正循环（CRAG）。 核心循环：

1. 检索：从向量存储获取查询的 top-k 文档。
2. 文档评分：LLM 评估器对每个文档的查询相关性评分。
3. 纠正：

- 全部/部分相关 → 可选地精炼/压缩文档，继续生成。

- 都不相关 → 触发查询重写（转换查询以获得更好的检索）和/或网络搜索回退（从更广泛的来源检索），然后重新检索。

1. 生成：以（可能纠正过的）文档为条件产生答案。
2. 生成评分：评估器检查答案是否锚定在文档中（幻觉检查）以及是否真正回答了问题。
3. 修复：如果生成不被支持或不响应，重新生成（可能用重写的查询）。

Self-RAG 的反思 token。 Self-RAG 采用不同的机制：生成器本身被训练发出像 [Retrieve]（我应该检索吗？）、[IsREL]（这个文档相关吗？）、[IsSUP]（我的输出被支持吗？）、[IsUSE]（它有用吗？）这样的 token。模型将检索决策和自我评估与生成交替。这通过微调将评估器内化到生成器中，而不是使用独立的评估器调用。

自适应 RAG 的查询路由器。 自适应 RAG 添加前端分类器，将每个查询路由到策略：

• 简单事实查询 → 无检索或单步 RAG。
• 复杂多跳查询 → 迭代、多步检索器（分解 → 每子问题检索 → 聚合）。

这避免在不需要智能体循环的查询上花费它们——成本/延迟优化，也减少失败面。

状态。 图的状态携带：查询、检索到的文档、相关性评分、（可能重写的）查询、生成和支持评分。每个评估器将其裁决写入状态，条件边读取那些裁决。

设计决策

决策 1：评估检索 vs 信任检索器（朴素 RAG）。

智能体 RAG 在检索后添加显式的相关性评分步骤，而不是假设 top-k 文档是好的。

权衡：

• 评估优势：捕获检索失败。坏 RAG 答案的第一大原因是坏检索。检测"这些文档都没有回答查询"的评分器防止生成器被毒害。这一个添加显著提高答案可靠性。
• 评估优势：启用纠正。一旦你知道检索失败，你可以做些什么（重写、网络搜索）。没有评估，就没有纠正的触发。
• 评估成本：每次检索额外 LLM 调用（评分器）。增加延迟和成本。
• 评估成本：评分器错误。坏评分器可能拒绝好文档（损害召回）或接受坏文档（原来的问题）。评分器本身需要好。

该模式添加评估，因为检索是 RAG 中最弱、最可变的环节，而未监控的弱环节决定系统可靠性。

决策 2：纠正行动（重写+网络回退）vs 只是重新检索。

当检索失败时，CRAG 重写查询和/或回退到网络搜索，而不是简单地重新运行相同的检索。

权衡：

• 重写优势：原始查询可能是问题（模糊、措辞不当，或与语料库使用不同的词汇）。重写将其转换为检索器可以处理的形式。重新检索相同查询返回相同的坏结果——这是疯狂的定义。
• 网络回退优势：本地语料库可能根本没有答案。网络搜索扩大来源池。这是智能体"走出去"获取信息——真正的智能体动作。
• 重写/回退成本：更多调用和延迟。每个纠正行动是额外的工作。
• 回退成本：网络结果比精选语料库更嘈杂、更不可信。引入新的质量变量。

CRAG 选择纠正行动，因为无变化的重新检索是徒劳的——纠正必须改变某些东西（查询或来源）才有成功的机会。

决策 3：评分生成（锚定性检查）vs 信任生成器。

智能体 RAG 评估最终答案是否真正被文档支持，捕获幻觉。

权衡：

• 锚定检查优势：即使有好的文档，生成器也可能幻觉（添加不支持的声明）或忽略问题。支持评分器捕获这一点并触发重新生成。这是可靠性故事的第二半（检索质量+生成忠实性）。
• 锚定检查优势：自我纠正。将"你的答案不被文档支持"反馈给生成器改善重试。
• 锚定检查成本：另一个 LLM 调用。
• 锚定检查成本：过度严格的评分可能拒绝有效答案（生成器改述，评分器说"不支持"）。

该模式评分生成，因为 RAG 的承诺是"锚定答案"，而未验证的生成器即使在完美检索下也可能打破那个承诺。

决策 4：按查询复杂性路由（自适应 RAG）vs 所有查询一个循环。

自适应 RAG 分类查询复杂性并路由到适当策略，而不是每个查询都运行完整的智能体循环。

权衡：

• 路由优势：成本/延迟效率。简单事实查询不需要多步检索-评估-纠正循环。将其路由到单步 RAG（或无检索）节省调用和时间。
• 路由优势：减少失败面。每个智能体步骤都是可能出错的地方。更简单的查询使用更少的步骤，所以更少的失败点。
• 路由成本：路由器可能误分类（将复杂查询发送到简单路径，或反之）。路由器质量重要。
• 路由成本：更多系统复杂性（维护多个策略+路由器）。

自适应 RAG 路由，因为一刀切的循环对简单查询是浪费，对困难查询是力量不足——如果路由器体面，将策略与复杂性匹配严格更好。

模拟设计者思考

*我在为公司内部知识库构建 RAG 系统，我不断撞上同一堵墙。有人问"我们企业合同的退款政策是什么？"检索器拉出三个文档。两个关于消费者退款。一个模糊相关。生成器阅读它们并产生自信、精炼、错误的答案。用户信任它，因为它引用了来源。这比没有答案更糟。*

*一旦你看到，根本原因很明显：我的管道是开环的。检索、生成、完成。没有东西检查检索是否工作。这就像厨师抓起第一个抽屉里的任何东西就煮，从不品尝。人类研究员不这样工作——他们检索，看他们得到了什么，如果是垃圾，他们改述问题或去不同的来源。我的管道没有"看你得到了什么"的步骤。*

*所以我添加一个。检索后，评分器："这些文档回答了查询吗？"这是整个系统中最重要的单行。如果答案是肯定的，继续。如果不——这里是它成为智能体的地方——做不同的事情。不只是重新运行相同的搜索；那返回相同的垃圾。重写查询（也许用户的措辞与语料库的词汇不匹配）。或者，如果语料库根本没有，去网络。然后再检索。我把管道变成了带质量门的循环。*

*我不止于检索。即使有好的文档，我的生成器也可能漂移——它添加源中没有的看似合理的细节，或回答略有不同的问题。所以我在生成后添加第二个门："这个答案被这些文档支持吗，它回答了问题吗？"如果不，带那个反馈重新生成。两个门：一个用于检索质量，一个用于生成忠实性。RAG 失败的两种方式，每个都有检测器和纠正。*

*现在，我会让每个查询都通过这整个循环吗？不。"公司哪一年成立？"不需要评分器和重写——检索一次、生成、完成。对其运行完整循环是三次浪费的调用和三次破坏的机会。所以我在前面添加路由器：这个查询有多难？简单 → 单步。复杂 → 完整智能体循环。使机制与任务匹配。*

*我构建的图：检索 → 评分 → 分支（相关：生成；不相关：重写/网络搜索 → 重新检索）→ 生成评分 → 分支（支持：完成；不支持：重新生成）。两个循环、两个质量门、一个复杂性路由器。它不再是管道。它是一个对自己的检索质量和自己的输出负责的智能体。*

*我会交给任何构建 RAG 的人的教训：检索器有时会失败，生成器有时会幻觉。这些是常数。唯一的问题是你的系统是否注意到。闭合循环。*

关键启示与行业影响

智能体 RAG 确立检索是要评估和修订的决策，而非要信任的预处理步骤。检索-评估-纠正循环直接解决 RAG 的核心失败模式（未监控的检索质量），现在是生产 RAG 的标准架构。教训：任何最弱环节可变的管道都需要那个环节上的质量门。

双门设计——一个用于检索相关性，一个用于生成锚定性——精确映射到 RAG 的两种失败模式（坏检索、不忠实生成），并给从业者具体的可靠性检查清单。这种分解（将"我们获得了好上下文吗"问题与"我们是否忠实使用它"问题分开）现在是标准 RAG 评估实践。教训：分别命名和监控每个失败模式；单一端到端指标隐藏了东西在哪里坏。

自适应 RAG 的复杂性路由以具体、可衡量的方式演示了"使机制与任务匹配"原则：不要在不需要智能体循环的查询上花费它们。这是更广泛工作流-智能体教训的 RAG 实例，它很重要，因为每个智能体步骤增加成本、延迟和失败面。教训：最好的智能体系统将简单工作路由远离智能体。

该模式对评分器质量的依赖是其诚实的局限——弱评分器可能拒绝好文档或接受坏文档，纠正机制（重写、网络回退）引入自己的噪声。这激发了行业对检索评估（更好的评分器、重排序器、混合搜索）作为最高杠杆 RAG 改进的投资。教训：评估-纠正循环只与其评估器一样好。

智能体 RAG 作为该领域通往智能体的入门

有一个原因智能体 RAG 是大多数团队构建和发布的第一个智能体：它将充分理解的基础模式（检索增强生成）与有界、高价值的智能体扩展（评估和纠正检索）结合，在一个质量门相对容易定义的领域（答案锚定吗？它回答了问题吗？）。检索-评估-纠正循环是解决真实、可衡量问题的最小智能体，它在低风险环境中教授每个更雄心勃勃的智能体将需要的教训：智能体的工作是监控自己的弱环节、纠正必须改变某些东西、输出值得自己的门、并非每个请求都需要完整的机制。在智能体 RAG 上内化这些教训的团队，对他们接下来构建的多智能体和长范围系统准备得好得多。

该模式还以微缩形式演示了本集的整个哲学：将智能体构造为带显式质量门的图，让模型在该结构内行使判断，并使控制流可审计。智能体 RAG 图足够简单，可以装在一个人脑中——检索、评分、分支、生成、评分、分支——但它包含智能体设计的所有基本动作。它是生产智能体的"hello world"，不是因为它简单，而是因为它完整：一个已经体现该领域正在收敛的纪律的最小系统。

智能体 RAG 的前沿是它与更广泛智能体栈的集成——检索作为更大智能体调用的工具、纠正循环作为多智能体系统中的子图、评估门馈入团队的 eval 和监控实践。随着这些集成成熟，"RAG 系统"和"智能体"之间的边界将继续模糊，因为检索只是智能体做的事情之一——而智能体 RAG 开创的质量门控、自我纠正方法是可靠地做任何这些事情之一的模板。它留下的一般教训是：无论你的智能体的弱环节是什么，构建注意到并修复它的循环。

Microsoft GraphRAG：用于全局问题的知识图谱索引

概述

GraphRAG 由微软研究院于 2024 年发布，是一种检索增强生成方法，它从语料库构建知识图谱（使用 LLM 提取实体和关系），将该图聚类为社区（通过 Leiden 算法），为每个社区生成摘要，然后通过组合这些层级摘要来回答查询。其标志性贡献是使全局问题——关于整个语料库的查询（"所有文档中的主要主题是什么？"——成为可能，这是传统向量 RAG 根本无法回答的，因为向量检索只浮现局部、相似度匹配的块，永远无法"看到"整体。

GraphRAG 解决的问题是众所周知的：朴素 RAG 对针对性问题（"文档 X 对 Y 说了什么？"）非常出色，但对需要跨整个语料库聚合的意义构建问题无能为力。你无法用相似度搜索检索"10,000 篇文档的主要主题"——没有单个块包含那个答案。GraphRAG 的洞见是在索引时预计算语料库的全局结构（作为图+社区摘要），这样全局问题可以通过阅读少量高级摘要来回答，而不是整个语料库。

GraphRAG 在特定意义上是"为智能体的图工程"：索引管道本身是多步 LLM 工作流（提取 → 聚类 → 摘要），查询端可以由决定咨询哪些社区摘要的智能体驱动。它位于知识图谱、RAG 和智能体管道的交叉点，并引发了"图+LLM"系统的浪潮。

架构

索引管道（多步 LLM 工作流）。

1. 将语料库分块为文本单元。
2. 提取实体和关系：LLM 阅读每个块并发出 (实体, 类型, 描述) 和 (实体_a, 实体_b, 关系, 描述) 元组。这在语料库上构建知识图谱。
3. 构建图：实体成为节点（带描述），关系成为边（带描述和权重）。
4. 检测社区：Leiden 算法将图聚类为层级社区（密集连接实体的组）。层级有多个级别（粗 → 细）。
5. 社区摘要：LLM 为每个级别上的每个社区编写摘要（"这个社区以 X 为中心，涉及 Y 和 Z，关键主题是……"）。这些摘要是预计算的"全局视图"。

全局搜索（回答意义构建问题）。

1. 选择社区级别（宽问题用粗，窄问题用细）。
2. 将相关社区摘要作为上下文馈送给 LLM（这是一个小的、可管理的集合——不是整个语料库）。
3. LLM 从摘要综合答案，通常通过 map-reduce（从每个摘要批次回答，然后组合）。

局部搜索（回答具体问题）。

1. 检索相关实体（通过对实体描述的向量相似度）。
2. 扩展到它们的图邻域（相关实体、关系、社区摘要）。
3. 生成锚定在这个结构化邻域的答案——比原始块更丰富，因为它包含关系上下文。

图作为索引。 知识图谱+社区摘要就是索引。向量嵌入可能用于实体查找，但主要结构是图。这与向量 RAG 相反，后者嵌入索引是主要的。

设计决策

决策 1：LLM 提取的知识图谱 vs 仅嵌入索引。

GraphRAG 花费索引努力构建显式知识图谱（通过 LLM 提取），而不是仅依赖向量嵌入。

权衡：

• 图优势：捕获关系。嵌入捕获相似性（块 A 像块 B），但不捕获关系（实体 X 导致事件 Y，人 A 为组织 B 工作）。图使关系成为一等公民，这正是许多问题实际关于的。
• 图优势：启用全局结构。图可以聚类为社区，揭示语料库的主题组织——嵌入单独无法提供的东西。
• 图成本：昂贵的索引。整个语料库上的 LLM 提取比嵌入它昂贵得多。对大语料库，索引成本是真正的障碍。
• 图成本：提取错误。LLM 可能提取错误的实体/关系，那些错误被烙进索引。

GraphRAG 选择图，因为其目标问题（全局意义构建、关系查询）正是嵌入无法回答的——索引成本买来否则无法获得的能力。

决策 2：社区摘要（预计算）vs 查询时聚合。

GraphRAG 在索引时预计算社区摘要，而不是在查询时尝试聚合语料库。

权衡：

• 预计算优势：全局问题变得可回答。你无法在查询时阅读 10,000 篇文档（上下文限制），但你可以阅读 50 个社区摘要。摘要是整个语料库的有损但可处理的压缩，计算一次。
• 预计算优势：查询时效率。回答全局查询只是"阅读相关摘要"——相对语料库大小快速且便宜。
• 预计算成本：索引成本和延迟。在每个级别摘要每个社区是大的 LLM 工作负载，随着语料库变化索引变得陈旧（需要重新索引）。
• 预计算成本：有损压缩。摘要可能遗漏特定查询需要的细节。摘要的质量限定全局答案的质量。

GraphRAG 预计算，因为全局意义构建能力没有预计算的全语料库视图是不可能的——这是核心价值主张，无法即时完成。

决策 3：层级社区（Leiden）vs 扁平聚类。

GraphRAG 使用 Leiden 算法，产生社区层级（粗到细），而不是单一扁平聚类。

权衡：

• 层级优势：多粒度。宽问题（"语料库的主要主题"）使用粗社区；窄问题使用细的。层级让系统将粒度与问题匹配。
• 层级优势：稳健性。Leiden 为大图设计并保证良好连接的社区；它是来自网络科学的经过验证的算法。
• 层级成本：更多摘要要生成（每个级别），更高的索引成本。
• 层级成本：在查询时选择正确级别本身是一个决策（通常由路由器或通过尝试多个级别处理）。

GraphRAG 选择层级，因为意义构建问题有不同粒度，单一扁平聚类会强制所有问题用一个粒度。

决策 4：LLM 驱动提取 vs 经典 NLP/NER 管道。

GraphRAG 使用 LLM（而非传统 NER/关系提取）构建图。

权衡：

• LLM 优势：开放领域提取。LLM 在任何领域无需训练即可提取实体和关系，并产生丰富的自然语言描述（不仅是标签）。这使 GraphRAG 领域无关。
• LLM 优势：关系质量。LLM 捕获经典管道遗漏的细微关系（"X 是 Y 的子公司"、"A 批评了 B 的方法"）。
• LLM 成本：非确定性和成本。LLM 提取昂贵且可能跨运行不一致。
• LLM 成本：更难验证。提取的图比基于规则的系统的图更难审计。

GraphRAG 选择 LLM 提取，因为它提供的丰富性和领域无关性使结果图对开放意义构建有用。

模拟设计者思考

*我在微软研究院的 GraphRAG 团队，一个客户问了我们 RAG 系统无法回答的问题。他们有 10,000 份内部报告，他们问："今年客户反馈的顶级主题是什么？"我们的向量 RAG 检索了一些相似的块并给出了困惑的答案——因为答案不在任何块中。它是整个语料库的属性。相似性搜索找到针；这个问题在问关于干草堆的事。我们意识到：这类问题——意义构建、"大局是什么"——正是高管问的，而 RAG 在结构上无法回答。*

*为什么不能？因为检索给你局部视图。Top-k 块，每个与查询相似。没有块说"顶级主题是 A、B、C"——那是聚合。要回答，你必须阅读一切。你无法将 10,000 篇文档放入上下文窗口。死胡同——除非你预计算大局。*

*那么你如何预计算语料库的"大局"？你需要结构。什么组织语料库？其中的实体及其关联方式。如果报告 1 提到"极光项目"，报告 400 提到"极光项目"，它们连接到相同的人和相同的问题，那就是主题。所以我们提取知识图谱：LLM 阅读每个块并提取实体和关系。现在语料库是图，主题是那个图的密集区域。*

*现在我们使用网络科学的技巧：社区检测。Leiden 算法找到密集连接实体的簇——而且它层级地找到它们，从粗到细。每个社区是一个主题或子主题。这里是关键动作：我们让 LLM 摘要每个社区。"这个社区关于极光项目的供应链延迟，涉及这些人和这些供应商。"现在我们有一组摘要，合起来以任何我们想要的粒度描述整个语料库。*

*全局问题变得简单："今年的顶级主题？"→ 阅读粗社区摘要 → 综合。我们把不可能的问题（阅读一切）变成了可处理的问题（阅读五十个摘要）。成本在索引时支付——提取图、聚类、摘要——所以查询时便宜。*

*对具体问题我们保留局部搜索：找到相关实体，遍历它们的图邻域，并用那个关系上下文回答——这比原始块更丰富，因为它包含事物如何连接。*

*诚实的权衡：索引昂贵。我们在整个语料库上运行 LLM，两次（提取，然后摘要）。对每天变化的语料库，重新索引是真实成本。摘要是有损的——如果提取器错过了实体，它是不可见的。我们接受这一点，因为替代方案——根本没有全局能力——对我们的目标用户更糟。我们用索引成本换取据我们所知任何数量的查询时聪明都无法恢复的能力。*

*我想留下的想法：检索不只是找到相似的文本。它是为被问的问题在语料库上构建使正确信息可达的结构。对局部问题，那个结构是嵌入索引。对全局问题，它是带摘要的图。使索引与问题匹配。*

关键启示与行业影响

GraphRAG 的定义性贡献是通过将语料库的结构预计算为带社区摘要的知识图谱，使全局意义构建问题可回答。它命名并解决了从业者感受到但未形式化的失败模式（向量 RAG 无法回答"全语料库"问题），并确立"全局搜索 vs 局部搜索"为标准 RAG 设计区分。教训：正确的索引取决于问题类别；相似性搜索是局部工具。

该系统展示了将经典网络科学（Leiden 社区检测、层级聚类）导入 LLM 系统的力量。图结构是 LLM 构建的，但组织是算法的——LLM 处理语义提取、算法处理结构的有益分工。教训：不要让 LLM 做好的算法做得更好更便宜的事。

GraphRAG 使索引成本-能力权衡显式化并置于 RAG 设计讨论的中心。构建图索引比嵌入昂贵得多，该框架迫使团队问他们的问题组合是否证明其合理性。这种对成本的诚实是其影响力的一部分——团队现在在成本/能力前沿评估 RAG 架构，而不是假设"更多检索更好"。教训：预计算以索引成本购买能力；花在查询时方法无法达到的地方。

该模式的局限——昂贵和缓慢的索引、有损摘要、烙进索引的提取错误、语料库变化下的陈旧——定义了其适当用途：全局意义构建重要且语料库足够稳定使重新索引负担得起的语料库。对快速变化或纯局部查询的工作负载，向量 RAG 仍然更合适。教训：强大的索引只有在其重建成本配得上问题的要求时才值得。

GraphRAG 与检索的智能体未来

GraphRAG 的索引管道本身是智能体工作流——在语料库上自主运行的多步 LLM 管道（分块、提取、聚类、摘要）——这种自指结构指向该领域的未来。随着索引成为智能体过程，"构建索引"和"运行智能体"之间的界限模糊：改善查询时智能体的相同评估和纠正技术（智能体 RAG 的检索-评估-纠正循环）可以改善索引时提取（提取、对照源验证、纠正）。将索引视为要评估和优化的智能体管道——而非一次性批处理作业——的团队将构建质量可衡量地更高的知识结构，那种质量复合到每个下游查询中。

该模式还以解决"向量 vs 图"辩论大部分的方式阐明了两个主导检索结构——向量和图——之间的分工。向量便宜且大规模地回答相似性问题；图回答向量在结构上无法回答的关系和全局问题。成熟的检索栈两者都用，将每个查询路由到可以回答它的结构：局部相似性问题到向量索引，关系和意义构建问题到图。GraphRAG 的持久贡献是使那个谱系的全局端具体和可部署，在此过程中它给检索架构师提供了问题空间的完整地图，而非单一工具。

诚实的警告——GraphRAG 的索引成本和陈旧性使其不适合快速变化的语料库——不是缺陷，而是 sharpen 设计指导的边界条件。它精确告诉你何时采用它：稳定的、高价值的语料库，全局意义构建问题足够频繁以摊销索引投资。在那个范围内，它是变革性的；在外面，向量加好的重排序器仍然是务实的选择。知道范围是工程知识；GraphRAG 比它之前的任何检索系统更清晰地绘制了它的边界。

人机协同智能体：中断、审批与监督

概述

人机协同（Human-in-the-loop，HITL）是在指定点暂停智能体自主执行以征求人工输入——批准、纠正、补充信息或引导决策——然后再继续的智能体工程实践。它是使高风险智能体行动处于人类控制之下的主要机制，并已成为一等公民的框架功能（LangGraph 的 interrupt()、OpenAI Agents SDK 的审批钩子、Temporal 的 signal/wait 原语），而非临时添加。HITL 是智能体图与组织结构相遇的地方：机器的计划成为人类的决策的时刻。

HITL 的需求源于一个基本事实：智能体采取有后果的行动（发送邮件、执行交易、修改数据、发布内容），而它们的判断是会出错的。对低风险行动，自主没问题；对高风险行动，未经审查的智能体行动是不可接受的风险。HITL 在风险恰好要求的地方——不可逆行动之前——插入人工检查点，同时让运行的其余部分保持自主。做得好，它是团队可以部署的智能体与只能演示的智能体之间的区别。

作为图，HITL 是中断点：执行暂停的节点（或边），当前状态被持久化，控制权返回给调用者（人类），并且——当人类响应时——图从持久化状态恢复，人类的输入被纳入。中断是条件为"人类已提供输入"的条件边，它需要检查点才能完全可实现。

架构

中断点。 智能体图中执行暂停的指定位置。常见放置：

• 高风险工具调用之前（批准/拒绝/编辑行动）。
• 状态变更之前（确认更改）。
• 智能体不确定时（它检测到低置信度并请求引导）。
• 收集缺失信息（智能体需要人类提供的事实）。

暂停机制。 当中断触发时：

1. 当前状态被检查点（序列化到持久存储）。
2. 执行停止；待处理的行动及其上下文浮现给人类（通过 UI、API、Slack 等）。
3. 运行不再消耗计算——它是等待输入的持久化记录。

恢复机制。 当人类响应时（批准/拒绝/编辑/提供输入）：

1. 人类的响应写入状态（作为特殊事件或状态字段）。
2. 图以相同的 thread/run ID 重新调用；它重新加载检查点。
3. 执行从中断点继续，人类的输入对下一个节点可用。

在 LangGraph 中这是 interrupt(value)（暂停，向调用者返回 value）+ Command(resume=...)（带人类输入继续）。在 Temporal 中是等待 signal 的工作流。共同结构：持久化、暂停、等待、恢复。

审批策略。 不是每个行动都需要审批。生产系统定义策略：哪些工具调用需要审批（按工具名、按参数、按估计影响）、谁可以批准、以及超时（没有人响应会发生什么）。策略层位于智能体和中断机制之间，决定何时触发。

编辑并继续。 强大的 HITL 变体：人类不仅批准/拒绝，还编辑智能体提议的行动（更改邮件收件人、修复 SQL），甚至编辑智能体的计划/状态，智能体从纠正后的状态继续。这使人类成为协作者而非门卫。

时间旅行和重放。 因为状态被检查点，HITL 系统通常支持回退到早期检查点并以不同方式恢复——从同一点探索替代分支。这对纠正（撤销坏步骤）和调试都有价值。

设计决策

决策 1：在行动边界中断 vs 持续人工监控。

HITL 在特定高风险点暂停，而不是要求人类观看整个运行。

权衡：

• 边界中断优势：可扩展的监督。人类无法观看每个运行的每一步，但可以批准少数有后果的行动。只在高风险边界中断使监督在生产规模可行。
• 边界中断优势：保留自主性。智能体在检查点之间自由运行，所以你在风险低的地方获得自主的速度/效率。
• 边界中断成本：需要知道风险在哪里。如果有风险的行动不被中断点覆盖，它在无审查下运行。审批策略必须随工具演进而维护。
• 边界中断成本：检查点的延迟。运行阻塞在人类响应时间上，可能是几分钟到几小时。

该模式使用边界中断，因为它们将人类注意力恰好集中在重要的地方，使监督既有效又可负担。

决策 2：持久化并暂停 vs 保持进程存活。

在中断时，状态被序列化且进程被释放，而不是让进程在内存中等待。

权衡：

• 持久化优势：资源效率。等待人类的运行可能空闲数小时。持久化并释放进程意味着不持有计算。这在规模上至关重要（数千个待审批）。
• 持久化优势：持久性。待处理运行在重启、部署和崩溃中存活。人类可以明天批准，运行正确恢复。
• 持久化成本：序列化复杂性。完整状态（包括任何进行中的上下文）必须可序列化。这约束了状态中可存在的内容（无打开的文件句柄、活动连接）。
• 持久化成本：恢复开销。重新加载和重建上下文需要一些工作。

该模式持久化，因为人类响应时间不可预测且长——让进程受制于人类的可用性是浪费和脆弱的。（这就是 HITL 与检查点紧密耦合的原因：没有持久化，中断不切实际。）

决策 3：审批策略作为配置 vs 硬编码中断。

哪些行动需要审批表达为策略（配置/规则），而非硬编码到图中。

权衡：

• 策略优势：适应性。随着工具和风险容忍度变化，你更新策略而无需重新部署图。不同环境（开发 vs 生产）可以有不同的策略。
• 策略优势：可审计。策略是精确陈述哪些行动被门控的可审查制品——对合规有用。
• 策略成本：策略管理开销。必须有人维护和审查策略；陈旧策略要么过度门控（烦人）要么门控不足（危险）。
• 策略成本：策略绕过风险。如果新工具添加时未更新策略，它在无门控下运行。需要纪律（新工具默认拒绝缓解这一点）。

该模式使用策略，因为高风险行动的集合随时间变化且因环境而异——将其烙进图使其脆弱。

决策 4：编辑并继续 vs 仅批准/拒绝。

HITL 可以让人类编辑提议的行动/状态，而不仅是批准或拒绝。

权衡：

• 编辑优势：协作。人类就地修复小问题（调整参数、纠正收件人），而不是拒绝并迫使智能体重试——更快、更少浪费。
• 编辑优势：精确利用人类判断。人类在不确定点精确应用他们的知识。
• 编辑成本：更复杂的 UI/状态处理。系统必须接受任意状态编辑并连贯地恢复。
• 编辑成本：人为错误。坏的人为编辑可能破坏运行；智能体必须处理不一致的输入。

该模式支持编辑并继续，因为真实的监督很少是二元的——人类想要纠正而非仅仅门控，纠正保留已完成的工作。

模拟设计者思考

*我在部署一个处理客户退款的智能体。测试中它很棒：阅读工单、检查政策、计算金额、处理退款。然后我的经理问了阻止每个智能体部署的问题："它错了会怎样？"因为它有时会错。它会误读政策，或工单模糊，或计算错误金额。而行动——将真金白银退还给客户——是不可逆的。一个 95% 正确且未经审查的智能体不是我可以发布的系统。它是带退款按钮的轮盘赌。*

*天真的修复是让人类审查一切。但那违背了目的——如果人类处理每个退款，为什么要有智能体？另一个天真的修复是自主发布并希望。两者都不工作。我需要的是选择性监督：风险低时智能体独自运行，风险高时人类恰好介入。*

*所以我定义风险。干净历史客户的 5 美元退款？低风险——让它运行。500 美元退款，或被标记账户的客户，或与政策不干净匹配的退款？高风险——暂停。我将其编码为审批策略：哪些行动、在哪些条件下需要人类。这是配置而非代码，因为阈值会随着我们学习而变化。*

*现在是机制。当智能体到达高风险行动时，我不能只让它"等待"——人类可能在十秒或两天内响应。所以我持久化整个状态并停止进程。运行成为记录："待审批，这是提议的行动，这是上下文。"等待时它不花一分钱。它在部署中存活。当人类响应——批准、拒绝或"批准但将金额改为 480 美元"——我重新加载状态，应用他们的输入，并恢复。智能体恰好从它离开的地方继续，人类的决定编织进它的上下文。*

*"编辑"选项比我预期的更重要。早期只有批准/拒绝，审查者不断拒绝边界退款只是为了修复金额——智能体会重试、重新计算，经常再次出错，审查者再次拒绝。浪费。当我让审查者直接编辑金额并继续时，循环坍缩为一次交互。人类不想当门卫；他们想当纠正者。*

*因为每个中断持久化检查点，我免费获得时间旅行：我可以将运行回退到坏步骤之前并以不同方式恢复。这在调试中救了我们无数次。*

*我落地的原则：自主和监督不是对立面；它们按风险分配。低风险 → 完全自主（那是智能体发挥作用的地方）。高风险 → 人工检查点（那是你保护下行风险的地方）。工程师的工作是正确绘制风险边界，并使检查点机制如此便宜——持久化、暂停、恢复——以至于你可以负担得起把它放在风险要求的每个地方。能发布的智能体不是从不需要人类的那个。它是确切知道何时询问的那个。*

关键启示与行业影响

人机协同确立可部署的智能体不是完全自主的那个，而是在正确时刻暂停的那个。通过将人类监督集中在高风险行动边界，HITL 使智能体部署在受监管和高后果领域（金融、医疗、面向客户的行动）可行——它是将"演示中工作"转换为"批准生产"的机制。教训：监督是要工程化的设计功能，而非要移除的限制。

持久化-暂停-恢复机制（由检查点实现）使人类响应时间从系统阻塞者变成非事件。因为待处理运行只是持久化记录，系统可以跨数小时或数天便宜地持有数千个审批，在重启和部署中存活。这种智能体执行与人类可用性的解耦是任何人类不即时响应的场景下智能体的先决条件。教训：只有当暂停的运行零成本且在任何事情中存活时，中断才是可行的。

审批策略层（可配置、环境特定、可审计的门控规则）成为在智能体系统中表达组织风险容忍度的标准方式。它使风险边界成为一等公民、可审查的制品——对合规重要——新工具默认拒绝成为公认的安全实践。教训：被门控行动的集合是策略，策略必须显式且被维护。

编辑并继续将人类角色从守门人重构为协作者，可衡量地减少了浪费的拒绝-重试循环。它证明最有价值的人类输入通常是不确定点的微小纠正，而非二元裁决。教训：让人类修复，而非仅仅批准。

风险边界作为设计制品

HITL 系统中最重要的工程制品不是中断机制——那是充分发展的基础设施——而是风险边界：需要人工审查的行动与自由运行的行动的显式、被维护的定义。这个边界是系统风险容忍度编码的地方，其质量决定部署是安全的（每个有后果的行动被门控）和可用的（没有多到人类在橡皮图章或工作流停滞的程度的门）。画好它需要同时理解行动空间（智能体能做什么，每个的爆炸半径是多少？）和人类能力（审查者实际能处理多少审批？）。因此边界是对安全性和吞吐量的联合优化，它值得与任何核心组件同样的设计关注。

这个框架也阐明了常见的失败模式：将 HITL 视为二元属性（"智能体有人类监督"）而非渐进策略。实际上，监督是按行动和按上下文分配的——5 美元退款自由运行，500 美元退款需要审批，被标记账户的 500 美元退款需要高级审查者。HITL 做对的团队构建表达这些渐进的策略引擎（并默认拒绝新工具直到它们被分类），他们将策略视为随事件审查和能力改进演进的活文档。中断是机制；策略是智能。

展望未来，随着智能体证明可靠，风险边界将移动。一旦错误率被测量和有界，曾经需要审批的行动可以自动批准——earned autonomy 的过程，智能体的记录（本身是本集其他地方描述的追踪和 eval 实践的产物）为它买来更多自由。因此成熟的 HITL 系统不是静态门，而是动态信任模型：它从保守开始，持续测量，并在证据支持的地方扩展自主。中断机制使这种演进安全——因为每次扩展都是可逆的，每个有后果的行动原则上保持可审查。这是人-智能体协作的持久形态：不是固定的皮带，而是 earned trust 的棘轮。

Temporal 用于 LLM 智能体：持久执行作为智能体运行时

概述

Temporal 是一个持久执行平台——最初为可靠的微服务编排构建——已成为生产 LLM 智能体的重要运行时。其核心保证：工作流代码恰好运行一次直至完成，通过持久记录工作流进度（事件溯源）并在恢复时重放，在进程崩溃、机器故障、网络分区甚至数据中心丢失中存活。当团队开始构建必须运行数分钟到数天、进行外部调用且永不丢失进度的智能体时，他们发现 Temporal 的模型——长时间运行、容错、有状态的执行——正是生产智能体所需要的。

这种契合是结构性的。智能体是长时间运行的进程，交替进行 LLM 调用、工具调用、等待（等待人类、等待速率限制、等待异步结果）和分支逻辑。每一个都是朴素实现在失败时丢失工作的点：在 40 次工具调用后崩溃的内存中智能体从头开始。Temporal 使每一步持久：每个 LLM 调用和工具调用的结果被记录，所以第 41 步的崩溃重放第 1-40 步（从记录，而非重新执行）并在第 41 步继续。这种"免费从你离开的地方重启"是智能体团队花费巨大努力手工构建的属性——而 Temporal 将其作为基础设施提供。

Temporal 的智能体故事不是智能体框架（它没有 ReAct 循环或工具抽象）；它是持久性和编排基底。团队用它将智能体逻辑（LangGraph 图、自定义循环、多智能体协调）包装在持久工作流中，添加重试、超时、人类 signal 和可观测性。它被运行生产智能体的团队采用——包括高调部署——标志着"智能体工程"与"分布式系统工程"的融合。

架构

工作流（Workflow）。 Temporal 工作流是执行被持久记录的函数。代码用普通语言（Go、Python、TypeScript、Java、.NET）编写，但它在 Temporal 运行时下执行，该运行时对每个有意义的操作进行事件溯源。工作流可以运行任意长时间（数天、数月），在普通变量中持有状态，并在任何基础设施故障中存活。智能体的控制循环自然映射到工作流。

活动（Activity）。 活动是带副作用的函数——LLM 调用、工具执行、API 请求、数据库写入。活动是重试和超时的单元：Temporal 用可配置策略（退避、最大尝试次数）重试失败的活动，强制超时，并记录其结果。因为活动结果被持久化，工作流在崩溃后从不重新运行已完成的活动——它从记录的结果重放。这是智能体的关键持久性属性：昂贵的 LLM 调用或有副作用的工具调用恰好发生一次。

事件溯源与重放。 工作流的历史是事件的追加日志（活动已调度、活动已完成、计时器已触发、signal 已接收……）。在失败时，Temporal 对照这个历史重新执行工作流代码：每个记录的事件被重放（返回存储的结果），直到代码到达失败点，然后继续实时运行。工作流代码必须是确定性的（无未播种的随机性、活动外无直接 I/O），这样重放遵循相同路径。

Signal 和查询。 signal 是到运行中工作流的异步消息（例如人类的批准、用户的新指令）——工作流可以等待 signal，这就是人机协同的实现方式。查询是对工作流状态的同步读取（例如"智能体在哪一步？"）。这些给外部系统（UI、人类、其他服务）到运行中智能体的类型化接口。

计时器和调度。 Temporal 提供在重启中存活的持久计时器（睡眠 2 小时、每 30 秒轮询）——用于速率限制退避、计划智能体运行和长等待。

子工作流。 工作流可以产生子工作流——这自然适合多智能体系统，协调者工作流产生每智能体子工作流，每个持久且可独立恢复。

设计决策

决策 1：持久执行（事件溯源+重放）vs 基于检查点的恢复。

Temporal 持久化完整事件历史并重放代码，而不是让开发者定义检查点和恢复逻辑。

权衡：

• 持久优势：恢复自动且细粒度。每个活动结果都是事实上的检查点。崩溃不丢失任何东西，不需要开发者编写的恢复代码。手工构建的检查点是常见 bug 来源（忘记保存、恢复不一致）；Temporal 消除这个类别。
• 持久优势：恰好一次副作用。通过适当的活动设计（需要时幂等），有副作用的工具调用在重试/重放时不重复——当工具移动金钱或变更数据时至关重要。
• 持久成本：确定性约束。工作流代码必须确定性（重放安全），这是真正的编程纪律。非确定性导致重放错误。这让习惯普通代码的开发者惊讶。
• 持久成本：历史增长。长工作流累积大历史；Temporal 用历史压缩/continue-as-new 管理，但这是真正的运维考虑。

Temporal 选择持久执行，因为它使容错成为平台的属性，而非每个开发者重新实现（通常不正确）的功能。

决策 2：活动作为副作用边界 vs 工作流代码中的任意 I/O。

所有副作用（LLM 调用、工具、I/O）必须通过活动；工作流代码是纯编排。

权衡：

• 边界优势：可重放性。因为副作用限于活动（其结果被记录），工作流逻辑可以安全重放。这种分离是整个模型工作的原因。
• 边界优势：每调用策略。每个活动获得自己的重试、超时和心跳配置——LLM 调用获得与数据库写入不同的重试语义。
• 边界成本：仪式。每个外部调用必须包装为活动，比内联代码更多结构。
• 边界成本：心智模型转变。开发者必须思考"编排 vs 效果"——普通代码不要求的纪律。

Temporal 强制边界，因为它是启用持久重放的架构决策；没有它，恢复不可能。

决策 3：代码优先工作流（真实编程语言）vs 声明式工作流定义。

Temporal 工作流用真实代码（带循环、条件、函数）编写，而非 YAML/JSON 状态机。

权衡：

• 代码优势：完全表达力。智能体的控制流——循环、动态分支、递归、错误处理——在代码中自然，在声明式模式中笨拙或不可能。智能体是动态的；代码匹配。
• 代码优势：可测试性和工具。工作流使用语言的测试、调试和重构工具。
• 代码成本：确定性要求（上述）——代码的自由必须被纪律约束。
• 代码成本：不太可视化。代码工作流比图更难可视化（通过显示事件历史的 Temporal 可观测性 UI 缓解）。

Temporal 选择代码，因为智能体逻辑本质上是程序性的，声明式工作流语言一直无法捕获所需的动态性。

决策 4：用 signal 接收人类输入 vs 轮询/外部状态。

人类输入作为 signal 到达工作流，工作流阻塞等待，而不是工作流轮询数据库。

权衡：

• signal 优势：干净的阻塞语义。工作流 await signal——无轮询循环、无浪费的工作，等待是持久的（重启中存活）。
• signal 优势：类型化接口。signal 是类型化消息，使人类/系统接口显式。
• signal 成本：需要 Temporal 接口。外部系统必须通过 Temporal API 发送 signal，而非只写入共享存储。

Temporal 使用 signal，因为它们使等待既持久又显式——工作流的代码直接读出"等待人类批准"。

模拟设计者思考

*我为构建智能体的团队运行基础设施，我这周第三次看着我们的支持智能体死去。它是好智能体：阅读工单、跨五个系统调查、起草响应、应用修复。二十分钟的工作，四十次工具调用。然后部署推出，进程重启，然后——噗——运行消失了。工单被重新拾取。四十次工具调用，浪费。它已经做出的副作用？半应用。现在有人必须清理。我们正在构建比 cron 作业更不可靠的"智能体"。*

*问题不是 LLM。是我们在假设进程短暂的世界里运行二十分钟的、有状态的、有副作用的进程。每次部署、每次崩溃、每次 OOM 都杀死从未记录的工作。所以我们开始手工构建：每步后将状态检查点到 Redis、编写恢复逻辑、给工具添加幂等键、构建待处理运行队列。三周后我们构建了……工作流引擎的坏的、有 bug 的版本。这是已解决的问题。我们只是不知道它有名字。*

*名字是持久执行，工具是 Temporal。这是模型：我的智能体控制循环成为工作流——普通代码，循环和所有。每个 LLM 调用、每个工具调用成为活动。Temporal 将每个活动的结果记录在追加历史中。现在当进程在第 41 步死去时，Temporal 重启工作流代码并重放：第 1-40 步立即返回其记录的结果（无重新执行、无重新计费、无重复副作用），第 41 步真实运行。我的智能体恰好从它死去的地方恢复。我写了零恢复代码。*

*纪律是真实的：我的工作流代码必须确定性，因为它被重放。工作流中无 random()（放入活动）。不直接读时钟。所有副作用通过活动。这是约束，但它是买来保证的约束。回报是复合的：不稳定 LLM 调用的带退避重试？活动配置。"等待人类批准最多 3 天"？await wait_for_signal()——持久，一切中存活。"智能体现在在做什么？"对工作流的查询。计划运行、速率限制等待、每子智能体子工作流——全部持久，全部同一模型。*

*说服我的是失败故事。之前：崩溃是数据丢失和清理工作。现在：崩溃是不可见的。运行继续。我们智能体的可靠性不再依赖任何单个进程、任何单台机器、任何单次部署的可靠性。我们把持久性问题从我们的代码（我们在那里做得很糟）转移到平台（那里是整个产品）。*

*我会给任何在生产中运行智能体的团队的教训：你的智能体是分布式系统，无论你是否喜欢。它进行远程调用、持有状态、运行数分钟，且必须在失败中存活。停止手工滚动持久性，采用已经存在的四十年分布式系统工程。LLM 是新颖的部分。执行模型不应该是。*

关键启示与行业影响

Temporal 对智能体的采用确立持久执行是长时间运行智能体工作负载的生产基底。它证明困扰生产智能体的可靠性问题（重启丢失工作、重复副作用、手工检查点 bug）是已解决的分布式系统问题的实例——采用持久执行平台消除整个类别。教训：生产中的智能体是分布式系统；给它分布式系统的保证。

事件溯源+重放模型使细粒度、自动恢复成为默认：每个活动结果都是检查点，恢复不需要开发者编写的恢复逻辑。这是"使困难的事情成为平台属性"的具体实例，它提高了团队对智能体基础设施期望的门槛。教训：你必须构建的恢复是你将构建错误的恢复；使其成为基础设施。

活动边界（副作用隔离，每个有自己的重试/超时策略）给智能体团队处理 LLM 调用 vs 工具调用 vs 人类等待的异构可靠性需求的原则性方式——以及通过幂等实现恰好一次副作用。这种纪律（将编排与效果分离）影响了 Temporal 之外的智能体框架设计。教训：隔离副作用；它们是不得运行两次的部分。

Temporal 的确定性要求是其诚实成本——令新来者惊讶的真正编程纪律——其 signal/查询模型成为运行中智能体的人机协同和外部可观测性的干净标准。更广泛的教训：智能体工程与分布式系统工程的融合不是可选的；将智能体视为短暂脚本的团队将在生产中付出代价。

智能体工程与分布式系统的融合

Temporal 对智能体的采用标志着该领域成熟的重要时刻：认识到生产智能体首先是分布式系统。它进行远程调用（到 LLM API、到工具、到数据库），跨这些调用持有状态，运行数分钟或数小时，且必须在任何长时间运行进程中不可避免的失败中存活。这些属性中的每一个都是经典分布式系统关注点，有数十年积累的工程智慧——然而第一代智能体框架在很大程度上忽视了那种智慧，将智能体视为短暂脚本，让团队艰难地重新发现持久性、幂等性和恢复。Temporal 的到来标志着那种重新发明的结束：智能体执行的困难问题是已解决的问题，解决方案是站在解决它们的 인프라 之上。

这种融合有具体的课程。幂等性——确保有副作用的工具调用不被应用两次——不再是异国情调的关注点，而是智能体工具的例行设计要求，就像任何分布式事务一样。不稳定 LLM 调用的带退避重试被配置而非编码。长等待（等待人类、等待异步结果）是持久挂起，而非忙循环或持有的进程。从失败中恢复是平台属性而非功能。内化这个课程的团队停止发生整类生产事故——丢失的运行、重复的退款、卡住的等待——因为基底使那些事故在结构上不可能。

诚实的反面是持久执行强加编程模型（确定性工作流、活动边界），这是要学习的真正纪律，对短暂、低风险的智能体可能感觉沉重。不是每个智能体都需要 Temporal——运行数秒且重试便宜的两步工具调用助手不需要。判断调用关于运行的持续时间、其副作用和丢失它的成本：运行越长、后果越大、重启越昂贵，持久性投资越值得。对重要的智能体——运行数分钟、接触真实系统、不得丢失工作的——答案越来越清楚：像对待它们所是的分布式系统一样对待它们，让四十年工程学做保活工作。

LangSmith：智能体系统的可观测性与评估

概述

LangSmith 是 LangChain 用于观察、调试、测试和监控 LLM 应用与智能体的平台。其核心原语是追踪（trace）：智能体运行所做一切的层级记录——每个 LLM 调用（输入、输出、token、延迟）、每个工具调用、图的每一步——组织为"运行"（run）的树。LangSmith 对智能体工程的贡献是使智能体的执行*可见*：将"LLM 在循环中决定了事情"的不透明过程变成可检查、可重放、可评估的制品。它是"我的智能体为什么那样做？"问题的标准答案。

LangSmith 解决的问题是根本性的：智能体的行为由提示、模型输出、工具结果和控制流的相互作用决定——这些在最终答案中都不可见。当智能体失败时，失败很少在代码中（代码是简单循环）；它在*数据*中——坏的工具结果、被误解的指令、第 7 步的错误路由决策。没有追踪，调试智能体意味着添加 print 语句并重新运行（因为 LLM 是非确定性的，可能无法复现失败）。LangSmith 自动记录每次运行，所以失败可以事后被完整详细地检查。

LangSmith 从调试扩展到完整的开发生命周期：示例输入的数据集（datasets）、针对数据集运行智能体新版本的实验（experiments）、为输出打分的评估器（evaluators，LLM 评判、启发式、人工）、以及生产运行的监控（monitoring）。这使智能体改进成为有度量的迭代过程——改变提示、运行实验、比较分数——而非基于感觉的提示调整。

架构

运行与追踪。 运行是单个工作单元（LLM 调用、工具调用、检索器调用、图步骤）。运行嵌套成树：顶层运行（整个智能体调用）包含子运行（每步），子运行包含孙运行（步骤内的 LLM 调用）。追踪是完整的树。每个运行记录：输入、输出、开始/结束时间、token 数、错误（如有）和元数据。对 LangChain/LangGraph 代码，检测是自动的（自定义代码只需几行）。

追踪查看器。 探索追踪的 UI：一侧是运行树，另一侧是完整输入/输出。你可以看到发送给模型的确切提示、确切的工具参数、确切的路由决策。这是调试界面——你遍历树找到智能体偏离的地方。

数据集。 精选的示例输入集合（带可选参考输出）。数据集是智能体行为的"测试套件"——你改变东西时运行的一组固定案例。

实验。 针对数据集运行智能体版本并记录结果。每个实验为每个示例产生输出，可以跨实验并排比较（提示的 v1 vs v2）。

评估器。 为智能体输出打分的函数。类型：

• 启发式：精确匹配、正则、代码执行（输出通过测试吗？）。
• LLM 评判：LLM 根据标准对输出打分（"这个答案正确且完整吗？"）。
• 人工：UI 中的手动标注。

评估器将"新提示更好吗？"变成数字（跨数据集的聚合分数）。

生产监控。 生产运行也被追踪，实现：错误率仪表板、延迟/token 成本跟踪、抽样生产运行供审查、以及将真实失败捕获到数据集（生产失败成为回归测试）。

反馈循环。 LangSmith 实现的生命周期：观察生产失败 → 添加到数据集 → 修复提示/智能体 → 运行实验验证修复提高分数且不回归其他案例 → 部署 → 监控。

设计决策

决策 1：自动层级追踪 vs 手动日志。

LangSmith 自动检测智能体运行（对支持的框架），产生结构化运行树，无需开发者努力。

权衡：

• 自动优势：零努力可见性。开发者无需编写日志代码即可获得完整追踪。这至关重要，因为追踪的价值在你没有预料到的情况下最高——那些正是你不会记录的。
• 自动优势：一致结构。每个运行有相同模式（输入/输出/延迟/token），使追踪可比较和可聚合。
• 自动成本：框架耦合。自动检测对 LangChain/LangGraph 最深；自定义框架需要手动集成（尽管 SDK 使其只需几行）。
• 自动成本：数据量。每次运行的完整追踪是大量数据；高生产量需要采样策略。

LangSmith 选择自动追踪，因为调试智能体的第一大障碍是相关数据未被捕获——自动化消除纪律要求。

决策 2：运行树（层级）vs 扁平事件日志。

追踪结构化为运行的嵌套树，而非事件的扁平序列。

权衡：

• 树优势：匹配智能体结构。智能体运行就是层级的（步骤包含 LLM 调用……）。树显示因果关系和包含——你看到坏的工具调用发生在步骤 3 内部，而步骤 3 是由 supervisor 路由到的。
• 树优势：可导航调试。你可以折叠/展开层级、跳转到失败的子树、看到任何运行的上下文（父的输入）。
• 树成本：构建和渲染比扁平日志更复杂。
• 树成本：非常深的智能体运行的深嵌套可能笨拙（通过折叠和搜索缓解）。

LangSmith 选择树，因为调试是关于在层级中找到哪里出错——扁平日志迫使你心理重建那个结构。

决策 3：LLM 评判评估器 vs 仅人工评估。

LangSmith 支持 LLM 评判（LLM 对输出打分）作为一等公民评估器，与启发式和人工审查并列。

权衡：

• LLM 评判优势：可扩展评估。人工审查无法扩展到每个实验数百个示例。LLM 评判可以在几分钟内对整个数据集打分，使频繁实验可行。
• LLM 评判优势：捕获软标准。"这个答案有帮助且准确吗？"难以归约为启发式，但对 LLM 评估是自然的。
• LLM 评判成本：评判偏见和噪声。LLM 评判有已知偏见（冗长、位置、自我偏好）且可能不一致。分数是估计，不是真相。
• LLM 评判成本：循环风险。用 LLM 评判 LLM 的输出可能遗漏人类会捕获的失败。

LangSmith 支持 LLM 评判，因为它是按智能体开发所需频率评估的唯一方式——但它与启发式和人工审查并列定位，理解评判质量本身必须被验证。

决策 4：数据集作为回归测试单元 vs 临时测试。

LangSmith 以持久数据集为中心工作流，每个更改都针对其测试。

权衡：

• 数据集优势：有度量的进步。每个更改针对相同案例打分，所以改进是真实的，回归被捕获。这将提示工程从民间传说变成工程。
• 数据集优势：失败捕获。添加到数据集的真实生产失败成为永久回归测试——系统的测试套件从实际故障中增长。
• 数据集成本：策展努力。好的数据集需要努力构建和维护。
• 数据集成本：过拟合风险。只为数据集优化可能过拟合；数据集必须刷新和扩展。

LangSmith 以数据集为中心，因为没有固定案例集，"新提示更好"是不可证伪的——而智能体开发需要可证伪的主张。

模拟设计者思考

*我在智能体团队，我们有一个抓不到的 bug。我们的支持智能体，大约五十分之一的运行，给出错误答案。我们读了代码十几遍——代码没问题，它是简单循环。问题在数据的某处：工具返回了奇怪的东西，或模型误读了工单，或路由器在第 7 步选错了专家。但我们没有那次运行内部发生了什么的记录。所以我们添加 print 语句并等待它再次发生——因为 LLM 是非确定性的，它不复现。我们在盲目调试。*

*这是你意识到的时刻：智能体的可调试性只与其追踪一样。代码不是问题，也永远不会是——代码是二十行。行为存在于数据中：提示、模型输出、工具结果、路由决策。如果你没有层级地、自动地、在每次运行中记录所有这些，那么失败的那次运行正是你看不到的。所以智能体可观测性的第一定律：记录一切，自动地，结构化为树。运行树——整个调用，每步和每个 LLM 调用嵌套其中——那就是制品。当失败发生时，你不再复现它。你打开它的追踪并遍历树，直到找到现实偏离预期的步骤。调试智能体变成阅读。*

*但调试是被动的。我还想在部署前知道我的提示变更是帮助还是伤害。业余方法：改变提示、手工试三个示例、发布、希望。工程方法：数据集——一百个带已知好答案的真实工单。我运行旧智能体、运行新智能体、给两者打分。现在"更好"是数字，我可以确切看到哪些案例回归。*

*打分是困难部分。某些案例我有真相（工单有确定答案——精确匹配）。大多数，正确性是判断（"这个响应有帮助吗？"）。我不能每次调整提示都让人工对一百个案例打分。所以我用 LLM 作评判：给它工单、响应和量表，要求打分。它有噪声、有时有偏见——我定期对照人工分数验证——但它是唯一能扩展到我需要的实验频率的东西。现在我的开发循环是：改变 → 实验 → 打分 → 比较 → 发布。那不是提示调整。那是带度量的迭代。*

*循环在生产中闭合。我追踪生产运行（抽样）、观察错误率和成本，当真实失败浮现时，我将其捕获到数据集。我的测试套件从实际故障中增长。下次某人的更改会导致那个失败时，实验会捕获它。数据集是团队对出了什么错的累积记忆。*

*原则：你无法改进你无法观察的东西，你无法观察你没有记录的东西。追踪使智能体可读。数据集使改进可度量。评估器使其可扩展。它们共同将智能体开发从手艺变成工程纪律——失败是数据点、更改是实验、进步是数字。*

关键启示与行业影响

LangSmith 确立可观测性是智能体工程的基础层——在评估之前、在优化之前，你必须能够看到智能体实际做了什么。自动层级追踪成为智能体的标准调试制品，"阅读追踪"取代"重新运行并希望"成为调试方法。教训：智能体的行为存在于其执行数据中，而非其代码中；默认记录一切。

运行树结构（匹配智能体的层级执行）被证明比扁平日志对调试有用得多，因为智能体失败通过导航包含和因果来定位。这影响了整个 LLM 工具生态的追踪设计。教训：构造你的可观测性数据以匹配系统的实际形状。

LangSmith 的数据集+实验+评估器工作流将智能体改进变成有度量的、可证伪的过程，并使 LLM 评判成为主流评估技术（对评判偏见有适当警告）。这使提示/智能体迭代专业化——从感觉到实验。教训：固定数据集和打分函数是区分工程与修补的东西。

生产到数据集的反馈循环（将真实失败捕获为回归测试）给智能体系统一条通往复合可靠性的路径——每次失败使测试套件更强。教训：你的生产失败是你最有价值的测试案例；构建捕获它们的管道。

追踪作为智能体问责的单元

除了调试和评估，追踪还服务于第三个角色，随着智能体更自主地行动而日益重要：它是问责的单元。当智能体发送邮件、处理退款或发布内容时，"它为什么那样做？"的问题不仅是诊断性的——它是责任、审计和信任的问题。追踪完整地回答它：这是输入，这是每个推理步骤和工具调用，这是导致该行动的决策。对受监管行业，这个审计轨迹不是可选的；它是部署的条件。LangSmith 的层级追踪默认捕获，给团队一个问责基底，手工构建将是巨大的——而且大多数团队如果自行其是会构建得太晚。

这个问责角色将追踪与成熟智能体栈中的其他治理实践联系起来。追踪是审查者在人机协同升级期间阅读的东西。它是评估器打分的东西。它是事件审查在失败后检查的东西。它是合规审计检查的东西。一个制品——捕获的、结构化的运行记录——服务所有这些消费者，这就是为什么很好地捕获它（完整、层级、保留）的投资多次回报自己。将追踪视为"只是调试"的团队留下了其大部分价值；将其视为系统记忆和良知的团队几乎免费获得治理。

前瞻性的挑战是规模：随着智能体数量增长，捕获和保留每个追踪变得昂贵，该领域正在开发采样策略、追踪摘要和分层保留，以保持问责基底可负担。但原则已定——行动的智能体必须能够解释自己，解释必须默认捕获，而非事后重建。追踪就是那个解释。它是使自主系统可问责的制品，而可问责性是自主性的代价。

Mastra：TypeScript 原生的智能体工程

概述

Mastra 是一个开源的、TypeScript 优先的智能体框架，由 Gatsby（React 静态网站框架）背后的团队创建，于 2024 年末发布。它将智能体工程原生带入 JavaScript/TypeScript 生态系统——世界上最大的开发者生态系统——框架设计围绕 TypeScript 的类型系统、现代 TS 开发的约定，以及将 AI 功能构建到产品中的前端/全栈工程师的需求。其核心原语是智能体（agents，LLM+工具+指令）、工作流（workflows，带分支、循环和并行执行的类型化、基于步骤的图）、以及工具（tools，类型化函数，通常包装现有应用代码）。

Mastra 的意义部分是人口结构的：在它之前，智能体框架空间压倒性地是 Python 的（LangGraph、CrewAI、AutoGen、Pydantic AI）。但大多数生产软件——特别是嵌入智能体的产品——是由 TypeScript 开发者构建的。Mastra 的赌注是这些开发者不应该为了构建智能体而学习 Python 和新的生态系统；框架应该来到他们这里，说他们的语言（字面上和习惯上）。它与 TS 开发者已经使用的工具（npm、Vite、Next.js、类型化 IDE）集成，并使智能体成为应用代码库的一等公民。

该框架的设计反映了强烈的开发者体验哲学（继承自 Gatsby）：合理默认、端到端类型安全、用于检查智能体和工作流的本地开发 UI，以及干净地映射到 TS 开发者已经构建代码方式的原语。

架构

智能体。 Mastra 智能体捆绑：

• instructions：系统提示（静态或动态）。
• model：LLM（通过统一提供者接口——OpenAI、Anthropic、Google 等，通过 Vercel AI SDK）。
• tools：智能体可以调用的类型化工具。

智能体可以直接调用（agent.generate(...)、agent.stream(...)），并可以将其他智能体作为工具调用（轻量级多智能体模式）。

工具。 工具用类型化模式定义（使用 Zod，TS 生态系统的标准验证库）：

• inputSchema：参数的 Zod 模式。
• execute：运行的函数，带完全类型化的输入。

因为模式是 Zod，工具参数类型流经 TypeScript——IDE 知道确切的形状，验证自动发生。工具通常包装应用现有的函数/API，这在存在于应用代码库内的框架中是自然的。

工作流。 Mastra 工作流是类型化的、基于步骤的图：

• 步骤：带类型化输入/输出的函数（Zod 模式）。
• 连接：步骤被链接（.then()）、分支（.branch()）、并行化（.parallel()）和循环（.dountil()、.dowhile()、.foreach()）。
• 工作流图是显式和可检查的——Mastra 可以渲染它，开发 UI 可视化它。
• 工作流支持挂起/恢复（suspend/resume，用于人机协同和长等待），带状态持久化。

记忆。 智能体可以被赋予记忆（对话历史、语义回忆），由可插拔存储支持，所以多轮行为开箱即用。

开发 UI（"Mastra Studio"）。 随框架提供的本地 Web 界面：列出智能体、与它们聊天、检查它们的工具、逐步运行和可视化工作流、查看 LLM 调用。这给 TS 开发者 Python 框架通过独立平台提供的检查/调试界面——但本地且免费。

与应用集成。 因为 Mastra 是 TS 库，智能体和工作流存在于与应用其余部分相同的代码库中，并由相同的管道部署（Next.js API 路由、serverless 函数、Node 服务器）。除非你想要，否则没有独立的"智能体服务"。

设计决策

决策 1：TypeScript 优先 vs 移植 Python 框架。

Mastra 为 TypeScript 原生构建，而非作为现有 Python 设计的移植。

权衡：

• TS 原生优势：生态系统契合。TS 开发者（最大群体）在他们的语言中获得智能体，带他们的工具（npm、类型化 IDE、现有测试框架），在他们现有的代码库内。无 Python sidecar、无跨语言边界。
• TS 原生优势：类型系统杠杆。TypeScript 的静态类型+Zod 模式给出端到端类型安全（工具参数、工作流步骤 I/O），在编译时捕获错误——Python 的动态类型无法同样干净匹配的 DX 胜利。
• TS 原生成本：更小的 AI/ML 生态系统。Python 有 ML 生态系统的深度（数据处理、评估库、研究代码）。TS 在这里更薄。
• TS 原生成本：晚于 Python 定义的领域。概念和模式很大程度上在 Python 中建立；Mastra 必须习惯地翻译它们。

团队选择 TS 原生，因为他们的论点是嵌入智能体产品的构建者压倒性地是 TS 开发者，用自己的语言服务他们是比在 Python 中竞争更大的机会。

决策 2：工具/工作流类型化的 Zod 模式 vs 手动类型定义。

Mastra 使用 Zod（运行时验证+静态类型推断）用于工具输入/输出和工作流步骤契约。

权衡：

• Zod 优势：单一真相来源。一个模式同时提供运行时验证（LLM 的工具调用参数被检查）和静态类型（IDE 和编译器知道形状）。验证和类型之间无漂移。
• Zod 优势：LLM 友好。Zod 模式被转换为模型看到的 JSON 模式，所以模型的工具接口总是与代码的期望同步。
• Zod 成本：依赖特定模式库（尽管 Zod 是 TS 事实上的标准）。
• Zod 成本：模式编写仪式（尽管比手写 JSON 模式+类型少）。

团队选择 Zod，因为它将"验证 LLM 的输出"和"类型化代码"坍缩为一个制品——核心 DX 胜利。

决策 3：带组合子的显式工作流图 vs 自由形式代码。

Mastra 工作流从类型化组合子（.then()、.branch()、.parallel()、循环）构建，形成显式、可可视化的图，而不仅仅是让开发者编写任意异步代码。

权衡：

• 显式图优势：可检查性。工作流的结构是数据对象——Mastra 可以可视化它、在开发 UI 中逐步执行它、推理它。任意代码无法可视化。
• 显式图优势：内置挂起/恢复。因为图是显式的，框架可以在步骤边界持久化状态并恢复（人机协同、长等待）——用不透明代码很难做到。
• 显式图成本：学习组合子 API（vs 只写函数）。
• 显式图成本：某些模式在纯代码中更自然。

团队选择显式图，因为它解锁的能力（可视化、逐步执行、挂起/恢复）正是使智能体工作流可调试和生产就绪的——纯代码无法提供。

决策 4：捆绑本地开发 UI vs 独立可观测性平台。

Mastra 附带用于检查/运行智能体和工作流的本地 studio，仓库中免费。

权衡：

• 捆绑优势：零摩擦调试。从 npm install 开始，开发者可以与智能体聊天、看其工具调用、可视化和逐步执行工作流。这大幅缩短构建-调试循环并降低采用门槛。
• 捆绑优势：隐私/简单。本地意味着开发时无需外部账户或数据出口。
• 捆绑成本：范围蔓延。构建 UI 对框架团队是重大投资。
• 捆绑成本：生产可观测性仍需要更多（studio 是开发工具，不是生产监控）。

团队捆绑 studio，因为开发者体验是他们的差异化，检查/调试界面是任何智能体工具链中使用最多的部分——使其本地和免费消除最大的采用摩擦。

模拟设计者思考

*我在 Mastra 团队，我们为 React/TypeScript 世界构建了多年开发者工具（Gatsby）。我们深知这个生态系统：数百万开发者、npm、TypeScript、Next.js、Vercel。我们看着智能体爆炸几乎完全发生在 Python 中。LangGraph、CrewAI、AutoGen——全是 Python。但这里是关键：构建将嵌入智能体的产品的人——SaaS 仪表板、商务网站、内部工具——是 TypeScript 开发者。他们生活在 VS Code，用 npm 发布，整个应用是 TS。我们告诉他们："要添加智能体，学习 Python、建立独立服务、桥接语言。"那是税。税会被避免。*

*所以论点：将智能体带给 TypeScript 开发者，用他们的语言、在他们的代码库中、带他们的工具。不是淡化的包装——一个感觉原生于他们已经工作方式的框架。*

*原生具体意味着什么？首先，类型。TS 开发者靠类型系统生活。所以我的工具不是松散的函数——它们是 Zod 模式，模式做双重职责：它是模型看到的 JSON 模式（所以 LLM 知道确切的工具接口），也是代码看到的 TypeScript 类型（所以 IDE 自动完成，编译器捕获错误）。一个制品，两个工作。当 LLM 用坏参数调用我的工具时，Zod 干净地拒绝它。当我接线工作流步骤时，类型端到端流动。这是 Python 无法完全匹配的 DX，我们倚重它。*

*第二，工作流。我可以说"只写异步函数"——但那样没有什么可可视化、没有什么可逐步执行、没有办法为人机协同挂起和恢复。所以我给他们显式图，从他们到处使用的流畅 API（RxJS、查询构建器）中链式组合子构建：.then()、.branch()、.parallel()、.dountil()。它读起来像他们到处使用的流畅 API。因为图是数据，我的开发 UI 可以绘制它，框架可以在每个步骤边界持久化状态并恢复——免费的人机协同。*

*第三，开发循环。扼杀采用的最快方式是使调试痛苦。所以我们附带本地 studio：运行 mastra dev，打开浏览器，与你的智能体聊天，看它的工具调用，可视化和逐步执行你的工作流。无账户、无云、无配置。"我改了提示，让我看看会发生什么"的时刻应该是两秒，而非部署。*

*一切存在于他们的应用中。智能体是 Next.js 代码库中的模块。工具包装现有的服务函数——无翻译层。它在应用部署的地方部署。智能体不是外部服务；它是产品的一部分。*

*赌注：下一波智能体构建者不是来自 ML。它来自已经发布软件的数百万产品工程师，他们将用说 TypeScript 的框架构建。我们不是与 LangGraph 争夺 Python ML 工程师。我们为有产品、有用户问题、想要其中有智能体的开发者构建——而不离开他们整个职业生涯所在的生态系统。*

关键启示与行业影响

Mastra 验证智能体框架机会远超 Python/ML 社区，原生服务 TypeScript 生态系统（而非通过移植或 sidecar）解锁大得多的构建者群体。其快速增长证明了产品工程师中真正被压抑的需求。教训：在开发者已经栖息的生态系统中会见他们；消除语言税的框架赢得长尾构建者。

Zod 模式作为单一真相来源的模式（一个制品同时提供模型的工具接口和代码的静态类型）成为类型安全智能体工具的参考设计，显示 LLM 接口验证和应用类型化可以统一。教训：将"模型看到的"和"代码期望的"坍缩为一个模式以消除漂移。

带类型化组合子的显式工作流图证明你可以给 TypeScript 开发者可检查、可挂起、可可视化的工作流，而不牺牲习惯的 DX——弥合"纯代码"（灵活但不透明）和"声明式引擎"（可检查但陌生）之间的差距。教训：显式图是可调试性和挂起/恢复的代价；用符合人体工程学的 API 支付它。

捆绑的本地开发 UI（Mastra Studio）提高了智能体框架的开发者体验标准，使检查/调试循环即时和本地。它强化了调试界面是智能体工具链中使用最多的部分且应无摩擦的原则。教训：将更改-观察循环缩短到秒，采用随之而来。

智能体存在于应用中的理由

Mastra 最具后果的设计决策不是任何单一功能，而是它体现的架构立场：智能体属于应用代码库内部，而非独立服务。这是对"智能体即微服务"模式的拒绝——许多团队默认的模式——TypeScript 产品通过 HTTP 与之对话的 Python 智能体服务。那种模式有真实成本：要桥接的语言边界、要运营的第二个部署、要维护的第二组依赖、以及产品领域模型与智能体视图之间的翻译层。Mastra 主张，对主导案例——服务产品自己用户、使用产品自己数据和函数的智能体——智能体应该是相同代码库中的模块，调用相同函数，由相同管道部署。包装现有服务函数的工具比到重新实现它的独立智能体的 RPC 调用更可靠。

这种立场有更深的含义：它默认使智能体的上下文丰富。存在于应用中的智能体自然可以访问用户的会话、产品的领域类型和现有的业务逻辑——正是使其行动相关和正确的东西。独立服务中的智能体必须被告知所有这些，通过序列化边界，跨越那个边界的每个字段都是上下文可能丢失或变形地方。应用内智能体不仅运营更简单；它信息更丰富，信息更丰富的智能体是更可靠的智能体。

这种立场的诚实边界是它更适合产品嵌入的智能体，而非智能体平台或多租户智能体用例，那里专门的服务（通常是 Python，更接近 ML 生态系统）是正确的选择。Mastra 不是主张每个智能体都应该是 TypeScript；它主张想要产品中有智能体的数百万产品工程师不应该为此建立一个独立的栈。对那个巨大且不断增长的群体，"智能体是模块而非服务"是正确的默认——它是将智能体放入最多产品的默认。

OpenAI Agents SDK：Swarm 的生产毕业

概述

OpenAI Agents SDK 于 2025 年 3 月发布，是 OpenAI 用于构建多智能体系统的生产级框架。它是 Swarm（2024 年 10 月的教育框架）的直接继承者，将 Swarm 的核心原语——作为指令+工具（"例程"）的智能体和作为控制转移的 handoff——毕业到受支持的、功能完整的 SDK，并添加 Swarm 刻意省略的生产层：护栏（guardrails，输入/输出验证）、追踪（tracing，内置可观测性）、上下文管理和结构化输出。该 SDK 代表 OpenAI 对"在我们模型上构建智能体的默认、开箱即用方式应该是什么样？"问题的回答。

该 SDK 的设计哲学反映了对智能体框架格局的特定观点，由观察数千客户构建智能体而形成：大多数编排复杂性应该下推到模型和平台，框架应该提供薄、可组合的原语集（智能体、handoff、护栏、工具），而非重型图引擎。LangGraph 要求你定义状态机、CrewAI 要求你定义团队的地方，Agents SDK 要求你定义智能体并让它们相互 handoff——模型的原生函数调用做路由。

SDK 的四个核心原语——Agent、Handoff、Guardrail 和 Runner——加上内置追踪形成连贯、最小的表面。它支持 OpenAI 模型和（通过模型无关接口）其他提供者，其追踪与 OpenAI 仪表板集成。它迅速成为在 OpenAI 模型上构建、想要比原生 API 调用更多结构但比图框架更少仪式的团队的首选。

架构

智能体。 智能体由以下定义：

• instructions：系统提示（静态或上下文的动态函数）。
• tools：它可以调用的函数。
• model：使用哪个模型（可以因智能体而异——分诊用便宜模型、难题用强模型）。
• output_type：智能体必须产生的可选结构化输出模式（Pydantic）。
• handoffs：它可以委派的智能体。

Handoff。 handoff 让智能体将整个对话/任务委派给另一个智能体。实现为特殊工具：当智能体调用 transfer_to_billing_agent() 时，Runner 交换活动智能体并继续。handoff 是多智能体协调机制——拓扑由哪些智能体有到哪些智能体的 handoff 定义，路由由智能体在运行时通过函数调用决定。

护栏。 护栏是对智能体输入或输出运行的验证函数：

• 输入护栏：检查传入请求（例如"这切题吗？包含 PII 吗？"），可以停止运行。
• 输出护栏：检查智能体的最终输出（例如"它符合政策吗？是正确的模式吗？"），可以拒绝它。

护栏与智能体并行运行（输入护栏）或之后运行（输出护栏），是 SDK 的安全/策略层。

Runner。 Runner 执行智能体循环：调用活动智能体 → 执行工具调用（包括交换活动智能体的 handoff）→ 重复直到智能体产生最终输出（无工具调用）→ 运行输出护栏 → 返回结果。Runner.run() 是异步的；Runner.run_sync() 和流式变体存在。

追踪。 每次运行自动追踪：每个智能体调用、LLM 调用、工具调用、handoff 和护栏都是 span，捕获输入/输出/延迟。追踪发送到 OpenAI 仪表板（或可导出到其他后端），提供内置可观测性，无需独立平台。

上下文。 类型化的 RunContext 对象传递给工具、handoff 过滤器和动态指令——给智能体访问应用状态（用户信息、数据库句柄、请求元数据）的依赖注入机制。

设计决策

决策 1：基于 handoff 的编排 vs 图/状态机引擎。

SDK 的多智能体模型是智能体之间的 handoff（继承自 Swarm），而非显式图。

权衡：

• handoff 优势：最小概念。没有要定义的图、没有要写的状态模式、没有要配置的编排者。多智能体协调只是"这个智能体可以调用那个智能体"。这是主流中最轻量的多智能体设计。
• handoff 优势：模型原生路由。路由利用模型的函数调用，在 OpenAI 模型上优化良好。智能体使用与工具相同的机制决定流程。
• handoff 成本：隐式拓扑。系统的结构分布在智能体的 handoff 列表和提示中——比显式图更难可视化和审计。
• handoff 成本：较少的精确控制。你无法轻易表达"总是按此状态运行 A 然后 B 然后 C"——为此，SDK 也提供工作流即智能体或使用 handoff 过滤器，但那不是框架的重心。

SDK 选择 handoff，因为 OpenAI 的观点（由 Swarm 的接受验证）是随着模型改进，编排应该委派给模型，框架的工作是使委派安全和可观察，而非微观管理流程。

决策 2：护栏作为一等公民原语 vs 安全作为事后想法。

SDK 将输入/输出验证提升为核心原语（与智能体和工具并列），而非留给开发者。

权衡：

• 护栏优势：默认安全结构。通过给护栏在架构中命名、类型化的位置，SDK 使添加策略检查变得自然——如果只是"你在代码中做的事情"则容易忘记。
• 护栏优势：并行执行。输入护栏与智能体并发运行，所以策略违反可以停止运行而不增加串行延迟。
• 护栏成本：额外调用（护栏通常是 LLM 调用），增加成本。
• 护栏成本：误报可能阻止合法请求——护栏调整是真实任务。

SDK 使护栏成为一等公民，因为安全/策略验证是普遍的生产需求，使其成为原语（而非练习）提高部署智能体的基线。

决策 3：内置追踪 vs 集成第三方。

SDK 附带到 OpenAI 仪表板的自动追踪，而非要求独立的可观测性工具。

权衡：

• 内置优势：零努力可观测性。每次运行开箱即被追踪——开发者无需配置任何东西即可看到智能体调用、工具调用、handoff 和护栏结果。这使调试循环即时。
• 内置优势：共同设计的 span。因为追踪内置于 Runner，span 精确匹配 SDK 的原语（handoff、护栏）——比通用检测更干净。
• 内置成本：将可观测性绑定到 OpenAI 仪表板（尽管追踪可通过处理器导出到其他后端）。
• 内置成本：OpenAI 要多维护一件事。

SDK 捆绑追踪，因为可观测性是智能体工作之后的第一大生产需求，零配置追踪消除拥有它的最大障碍。

决策 4：模型无关接口 vs 仅 OpenAI。

尽管由 OpenAI 构建，SDK 通过模型接口抽象支持非 OpenAI 模型。

权衡：

• 无关优势：OpenAI 商店之外的采用。有多提供者策略的团队可以采用 SDK 而无锁定，扩大其覆盖。
• 无关优势：作为框架（而非仅一个 API 的 SDK）的合法性。它在设计上竞争，而非仅默认访问。
• 无关成本：依赖 OpenAI 特定能力的功能（某些追踪集成、Responses API 功能）在其他模型上是尽力而为。
• 无关成本：维护抽象。

SDK 支持其他模型，因为框架采用复合模型采用，仅 OpenAI 的框架会被多提供者团队忽视。

模拟设计者思考

*我在 OpenAI 的应用团队，2025 年初，我有最好的数据集：我看着数千团队在我们的模型上构建智能体。我对他们实际需要什么形成了观点，因为我看着他们从头构建了一千次。*

*这是我看到的。每个团队写相同的循环：调用模型、检查工具调用、运行它们、循环。每个做多智能体的团队写相同的委派逻辑。每个发布到生产的团队临时添加相同的三件事：某种输入过滤器、某种输出检查、以及追踪，因为他们无法盲目调试。这种重复的重新发明是信号。这些不是新颖问题——它们是基础设施。基础设施应该被提供，而非重新推导。*

*我们已经用 Swarm 证明了编排模型。例程——智能体只是指令加工具。handoff——委派只是返回另一个智能体的工具调用。对 Swarm 的反应告诉我们原语是正确的：人们喜爱轻量，但他们不断问"现在我如何使它生产？"所以 Agents SDK 是 Swarm 的骨架加上生产肌肉：保持原语完全不变（不要修复被喜爱的），添加每个生产团队重建的四件事。*

*第一，护栏。我使它们成为一等公民——并行运行可以跳闸的输入护栏、验证结果的输出护栏。不是你导入的实用工具，是你声明的原语。如果框架给安全一个命名的席位，更多智能体构建时会带有它。*

*第二，追踪。自动的。每个智能体调用、每个工具调用、每个 handoff、每个护栏——一个 span，在仪表板中，从第一次运行开始。我看到太多团队在添加可观测性之前盲目飞行数周。使它免费，它从第一分钟就存在。*

*第三，上下文——类型化的 RunContext，所以工具和动态指令通过干净的注入点获得应用状态，而非全局。以及结构化输出，所以智能体可以契约性地绑定返回验证的类型。*

*Runner 将它们绑在一起：运行活动智能体、执行工具调用、在 handoff 时交换智能体、循环直到最终输出、检查输出护栏、返回。那是整个运行时。注意什么不在那里：没有图定义语言、没有状态模式、没有编排者节点。那是刻意的。我们的赌注——这是真正的赌注——是随着模型变得更好，框架应该变得更薄而非更厚。模型决定流程；框架的工作是使那个流程安全、可观察和可组合。需要刚性、可审计图的团队可以构建一个（智能体可以是工作流），但我们不会让每个人都为他们可能不需要的图引擎付费。*

*我支持其他模型，因为我宁愿在设计上赢，而非在默认上赢。尊重你模型选择的 SDK 是你标准化的那个。*

*原则：从数千构建者重新发明的东西中学习，并作为原语归还给他们。框架是生态系统经验的蒸馏。*

关键启示与行业影响

Agents SDK 验证了"薄原语、强平台"哲学：通过保持编排最小（智能体+handoff）并投资生产层（护栏、追踪、结构化输出），它提供了图中心框架的连贯替代。其采用确认了相当大的团队群体偏好模型驱动的路由加轻量框架，而非显式图定义。教训：框架厚度应该由用户需求证明，而非功能数量。

通过将 Swarm 的 handoff 模型毕业到受支持的 SDK，OpenAI 巩固了"委派即工具调用"作为主流多智能体模式，并给它生产可信度。handoff 现在是整个生态系统的标准概念。教训：由社区响应验证的教育性概念证明是生产标准的最佳基础。

使护栏成为一等公民原语（而非实用工具）提高了在其上构建的智能体的安全基线，输入护栏并行运行的设计显示安全检查无需增加串行延迟。教训：安全机制必须是有好人体工程学的原语，否则它们会被跳过。

内置的零配置追踪确立可观测性应该随框架附带，而非第三方集成项目。这给整个生态系统施加默认开启追踪的压力。教训：调试界面应该在第一次运行就工作。

薄框架赌注及其条件

Agents SDK 的薄框架哲学是带特定条件的赌注，理解它们对应用好它至关重要。当模型的路由判断对任务足够好时，赌注成立——在有能力的模型和范围明确的智能体集上，它越来越如此。当拓扑真正动态时成立，所以手工指定的图会是束缚。当生产层（护栏、追踪、结构化输出）足够强以使模型驱动的流程安全和可观察时成立。当这些条件失败时——弱模型、刚性合规要求、或需要穷尽审计每个可能路径——显式图框架保留优势。SDK 不是主张结构过时；它主张结构应该在其值得的地方添加，默认应该尽可能少。

这个赌注也有值得注意的自我实现维度：通过使基于 handoff 的编排成为最大 OpenAI 用户群的最省力路径，SDK 将塑造一代智能体的构建方式，模型将最快改进的正是其用户最常练习的路由模式。框架和模型共同演进——框架更多委派给模型，模型在被委派的事情上变得更好，框架可以进一步委派。这个反馈循环是图中心框架没有的战略资产，因为它们以不同形式路由绕过模型的决策。它最终是否被证实是智能体编排的核心开放问题。

对从业者，可操作的指导是将 SDK 的哲学视为要根据你的要求压力测试的默认，而非教条。从薄开始——智能体和 handoff 和护栏——让你系统的具体需求（可审计性、确定性、复杂状态）只在它们明显出现的地方拉你走向更多结构。这实际上是 Anthropic 阐明的相同"从简单开始，测量时添加复杂性"原则——应用于框架层本身。

Klarna AI 助手：第一个里程碑式生产智能体部署

概述

2024 年 2 月，Klarna（瑞典金融科技公司，约 5,000 名员工）宣布其 OpenAI 驱动的 AI 助手在第一个月处理了 230 万次客户服务对话——占 Klarna 客户服务聊天的三分之二，相当于 700 名全职客服的工作量，客户满意度与人工相同，解决时间从 11 分钟缩短到 2 分钟，重复联系减少 25%。这是第一个被广泛引用、量化的大型公司将核心面向客户的工作流大规模转移到 LLM 智能体的案例，并成为随后每个"生产智能体"商业案例的参照点。

Klarna 的故事对智能体工程很重要，不是因为架构奇特（按照本文档的标准，它是相对受约束的智能体：范围明确的助手，带账户查询和常见行动的工具、强护栏和人工升级），而是因为它展示了使智能体生产可行的部署*纪律*：发布前的严格评估、带人工监督的分阶段推出、对高频/低风险交互的紧密范围界定、持续监控，以及对业务影响的诚实衡量。它后来还提供了警示性的第二幕：随着数量和复杂性增长，Klarna 随后重新雇用了一些人工客服，强调智能体部署是演进的人机平衡，而非一次性替代。

该部署是将智能体视为*有损益表的产品*而非演示的案例研究：针对成本、满意度、解决率和错误指标衡量，并持续迭代。

架构

助手（受约束的智能体）。 部署的系统是 LLM 助手，带：

• 定义的范围：高频、充分理解的客户服务交互（支付状态、退款、争议、账户问题、购买历史）。复杂/罕见/敏感案例路由给人工。
• 工具/行动：与 Klarna 后端系统的集成，用于查询账户/订单数据和执行常见行动（处理退款、更新详细信息）——给智能体真实的效果通道，而非仅仅对话。
• 锚定：智能体的答案锚定在 Klarna 的实际客户数据（通过工具）和帮助内容上，减少最常见查询的幻觉。
• 语言/本地化：它在 23 个市场以 35+ 种语言运营——相对人工配置的关键优势（单一系统服务所有地区）。

护栏与升级层。

• 范围门控：意图分类只将范围内对话路由给智能体；范围外的去人工。
• 行动限制：智能体可以在政策内执行有界的行动集；超出的一切需要人工处理。
• 人工升级：当对话需要时（客户请求、低置信度、政策边缘）无缝移交给人工客服。

评估与推出管道。

• 离线评估：发布前，助手针对大量真实历史对话集测试，人工审查其响应，建立质量基线。
• 分阶段推出：在有限的市场集发布，随着指标保持而扩展——不是全球一刀切。
• 与人工 A/B 对比：助手的对话与人工客服在满意度、解决率和重复联系率上并排衡量。

监控与反馈循环。

• 持续指标跟踪：满意度分数、解决时间、重复联系率、升级率、每对话成本。
• 错误审查：抽样对话由人工审查，以捕获失败模式（错误答案、政策违反）并反馈纠正。
• 迭代改进：基于观察到的失败持续部署提示/内容/工具精炼。

业务衡量。 Klarna 用业务术语量化影响：处理的对话数、人力等效容量、成本节约（声称约 4000 万美元年化利润改善）。这种衡量层是架构的一部分，意义上它证明了持续投资和扩展的合理性。

设计决策

决策 1：受约束范围（高频/低风险）vs 完整客服覆盖。

Klarna 将助手范围界定为常见、充分理解的交互，而非所有客户服务。

权衡：

• 受约束优势：在重要地方的可靠性。范围界定的交互是智能体能处理好的（可预测的意图、清晰的数据、有界的行动）。这是数量所在（大部分联系），也是智能体错误率可接受的地方。
• 受约束优势：可管理的风险。"我的付款在哪里？"的错误答案下行风险小且可纠正；复杂争议的下行风险大。范围界定保持爆炸半径小。
• 受约束成本：不消除人工配置。复杂案例仍需要人工——智能体增强/捕获数量，而非替代功能。
• 受约束成本：需要好的路由器。范围门（意图分类）必须准确，否则智能体得到它无法处理的案例。

Klarna 选择受约束范围，因为它在最小化风险的同时最大化捕获的数量——经典 80/20：智能体处理 80% 的例行交互，人工处理 20% 的困难交互。

决策 2：通过后端工具的锚定行动 vs 纯对话助手。

助手可以通过集成工具实际做事（退款、查询），而非仅回答问题。

权衡：

• 行动优势：真实解决。客户的问题在对话中被解决（退款处理、状态找到），这就是解决时间从 11 分钟降到 2 分钟的原因。仅聊天的机器人仍需要人工行动。
• 行动优势：可衡量的价值。采取的行动 = 直接成本节约。这使 ROI 案例具体。
• 行动成本：有害行动的风险。错误退款是真金白银。通过行动限制、政策边界和监控缓解。
• 行动成本：集成努力。将智能体连接到后端系统（安全地，带适当授权）是重大工程。

Klarna 选择锚定行动，因为解决（而非对话）是产品——商业价值在于做。

决策 3：分阶段、有度量的推出 vs 大爆炸发布。

Klarna 在有限市场发布，针对人工基线衡量，随着指标保持而扩展。

权衡：

• 分阶段优势：受控失败。如果智能体表现不佳，损害限于初始市场，推出暂停。
• 分阶段优势：扩展的证据。每个阶段的指标为下一阶段建立案例（和信心）。这是有风险的部署如何变成被批准的项目的方式。
• 分阶段成本：达到全部价值更慢。收益在数月而非数天内累积。
• 分阶段成本：推出期间运行并行系统的运营复杂性。

Klarna 选择分阶段推出，因为面向客户的智能体的失败模式是公开且损害品牌的——你通过有度量的可靠性赢得扩展的权利。

决策 4：将满意度视为约束而非事后想法。

Klarna 将客户满意度分数作为发布/继续标准（智能体必须匹配人工满意度），而非仅仅是可有可无的。

权衡：

• 满意度约束优势：保护品牌。削减成本但惹恼客户的智能体破坏长期价值。保持满意度持平确保效率收益不以客户为代价。
• 满意度约束优势：诚实衡量。它防止"我们自动化了 70% 的聊天但每个人都讨厌它"的结果。
• 满意度约束成本：如果满意度下降可能减慢部署（扩展前需要修复）。
• 满意度约束成本：满意度是有噪声的指标（调查偏见），所以必须与解决/重复联系率一起解读。

Klarna 使满意度成为约束，因为智能体服务客户，只衡量成本的指标会优化错误的东西。

模拟设计者思考

*我领导 Klarna 的 AI 助手工作，2023 年末，我的任务是：使用这个新的 LLM 能力转变客户服务——但不要破坏信任。客户服务是我们最大的成本中心，也是最可见的表面。在一百万客户面前搞砸，我们是傲慢的案例研究。做对了，这是公司今年做的最重要的事。*

*第一个决策，其他一切都挂在上面：智能体处理什么？本能是"一切"。智慧是"例行的 80%"。看我们的联系数据：大多数对话是相同的十几个意图——我的付款在哪里、如何退款、更新我的详细信息。这些是高频、低模糊、有界行动。它们正是有好工具和锚定的智能体能可靠处理的。复杂争议、边缘案例、需要同理心的愤怒客户——那些保持人工。我不是在构建客户服务的替代品。我在构建吸收例行数量的机器，所以我的人工客服可以做真正需要他们的工作。*

*第二：智能体必须做，而非仅仅说。我们的聊天花 11 分钟的原因是人工阅读问题、打开三个内部系统、找到订单、处理行动、输入回复。如果我的智能体能调用那些系统——查询账户、检查付款、在政策内处理退款——对话坍缩到 2 分钟。所以我投资于集成和行动层，带硬限制：有界的行动集、在政策阈值内、一切记录。智能体有手，但它们在皮带上。*

*第三：在会见客户之前我如何知道它是好的？我不猜测——我评估。我取数月的真实对话，让智能体对它们运行，让人工评分响应。我建立标准：智能体必须匹配人工满意度、必须正确解决、必须不违反政策。我不是到处发布。我在几个市场发布，与人工并排运行，观察每个指标——满意度、解决时间、重复联系、升级。如果指标下滑，我停下来修复。我一个一个市场赢得。这不是发布。这是一系列证明。*

*第四：发布后第二天的计划。生产中的智能体如果你不看着它会退化——内容漂移、新失败模式出现、客户找到边缘。所以我构建监控：抽样对话供人工审查、每天跟踪指标、从"观察到的失败"到"部署的修复"的快速循环。智能体是带运营团队的产品，而非带提示的模型。*

*我用业务术语衡量，因为那是维持项目的东西：每月 230 万对话、满意度匹配人工、解决时间下降 82%、700 名客服的工作。当我向董事会展示时，我不是展示 BLEU 分数。我展示我们更快更便宜地解决了数百万客户问题，而没有让任何人更生气。*

*后来的教训，使整个故事成熟的：随着数量增长和简单案例被吸收，剩余的人工工作变得更难，我们再次需要熟练的客服。那不是失败——那是均衡。智能体接管例行，人工接管判断，分工演进。诚实的框架从来不是"智能体替代人类"。它是"例行的 80% 不再需要人类，这改变了你配置 20% 的一切方式"。*

关键启示与行业影响

Klarna 的部署成为 LLM 智能体可以以质量平价处理核心面向客户工作流的规模的标准证明——230 万对话/700 客服等效的数字被随后几乎每个智能体商业案例引用。它将"生产智能体"从猜测变为先例。教训：第一个可信的、量化的部署改变了整个行业对可能性的信念。

该部署的真正贡献是纪律而非架构：对高频/低风险交互的受约束范围、带硬限制的锚定行动、发布前针对人工基线的评估、分阶段推出、满意度作为约束保持、以及持续监控。这个剧本成为企业智能体部署的模板。教训：生产可行性通过范围控制和衡量赢得，而非模型能力。

"智能体做而非仅仅说"的决策（政策边界内的后端集成行动）是部署交付真实解决和可衡量 ROI 的原因——它确立了最高价值的智能体是有有界、良好集成效果通道的智能体。教训：商业价值在行动，安全在边界。

Klarna 的第二幕——随着剩余工作变难重新雇用人工客服——为"智能体替代人类"叙事提供了该领域最诚实的纠正，确立了持久的框架：智能体吸收例行数量、人工处理判断工作、分工随时间演进。教训：为移动的人机均衡做计划，而非一次性替代。

部署剧本的泛化

Klarna 的经验，加上随后的部署，已结晶为将智能体放到客户面前的通用剧本。第一，按风险/数量矩阵界定范围：瞄准智能体错误率可接受且数量使投资值得的高频、低风险交互。第二，给智能体有界的效果通道——政策限制内的真实行动——因为解决而非对话是价值所在。第三，发布前针对人工基线评估，并将客户满意度保持为约束而非虚荣指标。第四，分阶段推出，用有度量的可靠性赢得每个市场。第五，从第一天构建监控和错误审查循环，并将每个生产失败视为修复和回归测试。第六，用业务术语衡量——解决、成本、满意度——因为那是维持项目度过其不可避免的 rough patches 的东西。

这个剧本最重要的属性是它是建立信任的过程，而不仅是发布软件的清单。每个阶段产生证据——评估分数、试点指标、监控质量——将有风险的赌注转化为被批准的项目，对组织和客户都是。跳过阶段的团队（无基线广泛发布，或在满意度下滑时优化成本）是产生警示故事的团队。纪律是产品。

该剧本也泛化到客户服务之外，到智能体代表人们行动的任何领域：相同的原则——按风险界定范围、约束行动、针对基线评估、分阶段推出、持续监控、诚实衡量——适用，无论智能体是处理退款、分诊工单、起草文档还是运营运营。具体改变；earned trust 的结构不变。Klarna 的持久贡献是最清晰的早期示范：这个结构有效——大规模、公开、有数字证明。

智能体评估：使智能体成为工程的纪律

概述

智能体评估（"evals"）是系统地根据定义的标准衡量智能体行为的实践——使用精选数据集、自动评分器（启发式和 LLM 评判）和人工审查——以便对智能体的更改（提示、工具、模型、架构）可以基于证据而非直觉被接受或拒绝。它是将智能体开发从手艺转化为工程的纪律：没有 evals，你不知道你的更改是否有帮助；有了 evals，每个更改都是有度量的实验。

evals 的理由在智能体系统中特别强，因为有三个复合事实。第一，智能体是非确定性的：相同输入可以产生不同输出，所以"我试的时候它工作了"不是证据。第二，智能体行为是涌现的：它来自提示、工具、模型输出和控制流的交互，所以无法通过阅读代码来验证（代码是简单循环；行为在数据中）。第三，智能体失败是昂贵且公开的：行动的智能体（发送、退款、发布）可以造成真实损害，所以质量必须在部署前保证，而非之后发现。这些共同意味着知道智能体是好的的唯一可扩展方式是反复地、针对固定标准来衡量它。

现代 evals 实践——由 Hamel Husain（"你的 AI 产品需要 Evals"）等有影响力的从业者阐述，并在 LangSmith、Braintrust、Promptfoo 和 OpenAI Evals 等工具中制度化——有可识别的形状：从小型、真实的错误驱动数据集开始；构建评分器（可能时用精确匹配、判断用 LLM 评判）；每次更改运行 evals；并将 eval 结果视为合并标准。它是刻意务实的：小型、诚实的 eval 集胜过大型、合成的，目标是方向性信号，而非学术基准的完美。

架构

Eval 数据集。 精选的示例集，每个通常：输入（用户请求/任务），和可选的参考输出或量表。来源：

• 真实生产失败（最高价值的示例——它们是系统实际出错的案例）。
• 真实生产成功（防止在有效的东西上回归）。
• 手工制作的边缘案例（对抗性输入、政策边界、模糊请求）。
• 合成生成（LLM 生成变体——对数量有用，但必须验证，因为合成数据可能偏离现实）。

数据集被版本化并随时间增长；它是团队对"好"的累积定义。

评分器（Evaluator）。 为给定输入的智能体输出分配质量信号的函数。按可靠性排序的类型：

• 确定性/启发式：精确匹配、正则、JSON 模式验证、代码执行（智能体的代码通过测试吗？）、SQL 正确性、工具调用序列匹配。便宜、可靠，但只适用于真相可检查的地方。
• LLM 评判：LLM 根据量表对输出打分（"答案正确、完整、符合政策吗？评 1-5"或通过/失败）。适用于开放式输出；需要量表设计和针对人工判断的验证。
• 人工审查：黄金标准，用于校准 LLM 评判、解决模糊案例和抽查。不能扩展到每次运行，所以战略性使用。

Eval 运行。 针对完整数据集执行智能体并为每个示例打分。产生：每示例分数、聚合指标（通过率、平均分）、与上次运行的差异（哪些示例改善/回归）。这在每次有意义的更改（提示编辑、工具更改、模型切换、架构更改）时运行。

决策循环。 eval 结果反馈决策：这个更改发布吗？实践是要求：聚合分数不回归、关键示例无新失败、（对判断指标）LLM 评判的裁决一致。eval 成为合并标准——智能体等效的 CI 测试套件。

在线评估（监控）。 evals 扩展到生产：抽样的生产运行被打分（自动和人工审查），失败被捕获回数据集，漂移被检测（实时通过率在下降吗？）。这闭合循环：生产失败成为 eval 示例，防止回归，改善生产。

轨迹评估（智能体特定）。 除了最终输出打分，智能体 evals 可以评估*过程*：智能体是否以合理顺序调用了正确的工具？它采取了合理数量的步骤吗？它沿途是否遵守政策？轨迹 evals 对运行的路径（行动序列）打分，而非仅其目的地——这很重要，因为智能体可以通过危险或浪费的路径到达正确答案。

设计决策

决策 1：小型、真实、错误驱动的数据集 vs 大型合成基准。

务实的 evals 实践从真实失败构建的小型数据集开始，而非大型合成或学术基准。

权衡：

• 真实数据优势：有效性。真实失败按定义是你的系统出错的案例——改善它们直接改善产品。合成数据可能不反映你的实际分布。
• 真实数据优势：启动便宜。你可以在一天内从 20-50 个真实示例构建有用的 eval 集。这在"完美"之前使纪律运行起来。
• 真实数据成本：小样本有噪声；30 个示例的聚合分数有宽的置信区间。
• 真实数据成本：覆盖缺口；你只测试你见过的。通过持续增长集合缓解。

该实践选择真实且小优先，因为最大风险是根本没有 evals——小型诚实集启动反馈循环，它有机增长。

决策 2：开放式打分的 LLM 评判 vs 仅人工。

LLM 评判被用作基于判断标准的可扩展评分器，人工用于校准。

权衡：

• LLM 评判优势：规模和速度。在几分钟内对每次 eval 运行打分数百个示例使频繁实验可行。仅人工打分会成为迭代的瓶颈。
• LLM 评判优势：一致性。评判统一应用相同量表（人工会漂移）。
• LLM 评判成本：偏见和噪声（冗长偏见、位置偏见、自我偏好）。评判必须针对人工分数验证，其量表必须迭代。
• LLM 评判成本：可能遗漏领域专家会捕获的微妙失败。

该实践使用 LLM 评判，因为它是开放式智能体输出的唯一可扩展选项——但将其视为需要校准的仪器，而非信任的神谕。

决策 3：evals 作为合并标准 vs 信息性报告。

成熟团队基于 eval 结果门控更改（如 CI 测试），而非将 evals 视为瞥一眼的报告。

权衡：

• 门控优势：系统地防止回归。没有降低分数的更改发布——质量随时间棘轮上升。
• 门控优势：强制 eval 集质量。当 evals 阻止合并时，团队投资于保持它们快速、可靠和有代表性（不稳定的 evals 被修复，如不稳定的测试）。
• 门控成本：摩擦。慢或不稳定的 evals 延迟开发；eval 基础设施必须维护到 CI 标准。
• 门控成本：Goodhart 风险。优化分数可能过拟合数据集；通过刷新数据和保留示例缓解。

该实践基于 evals 门控，因为不阻止坏更改的质量信号是装饰——门控是使它成为工程的东西。

决策 4：除结果评估外的轨迹评估。

智能体 evals 对过程（工具调用、步骤数、政策遵守）打分，而非仅最终答案。

权衡：

• 轨迹优势：捕获危险/浪费的路径。通过调用破坏性工具或采取 40 步到达正确答案的智能体是问题，即使输出正确。轨迹 evals 捕获这一点。
• 轨迹优势：更好的调试。当结果错误时，轨迹显示过程在哪里偏离。
• 轨迹成本：更难定义。"好的轨迹"不如"正确答案"客观；轨迹量表需要设计。
• 轨迹成本：可能过度约束。惩罚与参考路径的任何偏离可能惩罚有效的替代策略。

该实践添加轨迹 evals，因为智能体由其行动定义，行动（而非仅答案）是风险所在。

模拟设计者思考

*我是刚发布智能体的工程师，我的 PM 问了我无法回答的问题："新提示更好吗？"我改了它，因为旧的似乎在退款问题上笨拙。我手工试了五个示例，看起来不错。但"在我恰好选的五个示例上看起来不错"不是答案。诚实的答案是：我不知道。这对代表客户行动的系统是不可接受的。*

*根本问题：我的智能体是非确定性的，其行为是涌现的。我无法阅读代码并知道它是否好——代码是循环。我无法试三次并知道——它是随机的。知道的唯一方式是每次更改时，针对许多案例、对照固定标准来衡量它。那个标准是我的 eval 集。*

*所以我从痛苦所在开始：我的失败。我拉出智能体出错的对话——来自支持工单、来自我一直在记录的追踪、来自投诉。二十个。那是我的第一个数据集，它是我将拥有的最有价值的数据集，因为它正是我的系统失败的案例。我也添加一些成功，所以我会注意到"修复"是否破坏了有效的东西。*

*现在打分。某些案例答案是可检查的——"它退对了金额吗？"——我写确定性检查。大多数，正确性是判断——"这个响应正确且符合政策吗？"我不能每次调整提示都人工评一百个案例，所以我构建 LLM 评判：这是请求、这是智能体的响应、这是量表，打分。因为我知道评判有偏见，我验证它：我手工评一个样本，检查评判大多数时间与我一致。如果不一致，我修复量表。评判是我校准的仪器，而非我信任的神谕。*

*现在循环：每次更改——提示、工具、模型——我运行整个集合并比较。通过率是 72%，现在是 81%。哪些示例改善？哪些回归？我在庆祝收益之前看回归。我与团队制定规则：如果 eval 分数下降，什么都不发布。eval 是我们的 CI。它将"我认为更好"变成"它更好，这是数字，这是它修复的案例"。*

*我将它扩展到智能体如何工作，而非仅它回答什么。我添加轨迹检查：它调用了正确的工具吗？它保持在行动限制内吗？它采取了合理的步骤数吗？因为通过鲁莽路径到达的正确答案是负债，我希望我的 evals 看到路径，而非仅目的地。*

*出现的实践：我的 eval 集从每个生产失败中增长（每个成为永久回归测试）。我的评判定期重新校准。我的 evals 在每次更改时运行并阻止坏的。这不是基准练习——它是我开发过程的操作系统。eval 集是我团队对"好"意味着什么的记忆，用示例而非观点书写。*

*教训：你无法改善你不衡量的东西，你无法信任你没有衡量的智能体。evals 是你希望的智能体和你知道的智能体之间的区别——而"知道"是生产接受的唯一标准。*

关键启示与行业影响

智能体评估确立，在非确定性、涌现系统中保证质量的唯一可扩展方式是针对固定标准的系统衡量——且那种衡量必须自动化、频繁和门控。它将智能体开发从凭感觉的提示调整变成实验纪律。教训：在你无法通过阅读代码验证的系统中，eval 集是规范。

务实的"从真实失败小处开始"方法降低了入门门槛，使 evals 成为第一天的实践，而非后期阶段的奢侈品。它证明小型、诚实、错误驱动的数据集比大型合成基准交付更多产品价值。教训：最有价值的 eval 示例是你的系统已经出错的示例。

LLM 评判成为开放式智能体输出的标准可扩展评分器，伴随将评判针对人工审查校准的关键纪律——确立评判是要验证的仪器，而非要信任的神谕。教训：在可能的地方自动化判断，但将人工保留在校准循环中。

向轨迹评估的扩展（对智能体的过程打分，而非仅其输出）认识到智能体的风险存在于其行动中——通过危险路径的正确答案仍然是问题。这是智能体特定的测试实践贡献。教训：评估旅程，而非仅目的地。

Evals 作为智能体系统的规范

evals 纪律最深刻的含义是，对非确定性系统，eval 集就是规范。传统软件由其代码规定：阅读代码（及其类型）你就知道它做什么。智能体不是——其代码是简单循环，其行为是提示、工具、模型和数据交互的涌现属性。预期行为唯一完整表达的地方在示例中："对这个输入，好的智能体这样做。"因此 eval 集不仅是测试制品；它是系统应该是什么的最完整可执行陈述。这样对待它的团队——像规范一样策展它、像 API 更改一样审查对它的更改、像代码一样版本化它——发现它成为他们开发过程的中心，人类和自动化系统都咨询它来回答"这对吗？"

这个重构也阐明了 evals 与其他智能体实践的关系。可观测性（追踪）告诉你智能体做了什么；evals 告诉你那是否好。护栏在运行时约束智能体可以做什么；evals 验证约束的行为仍然正确。人机协同处理系统无法处理的案例；evals 衡量那些案例出现的频率。所有其他实践要么馈入 eval 循环（追踪浮现要添加到集合的失败），要么被它验证（护栏更改本身是要打分的实验）。evals 是整合的纪律——使所有其他实践对共享标准负责的唯一实践。

前瞻性的挑战是 eval 方法必须与智能体能力保持同步。随着智能体承担更长、更开放的任务，"什么是好的轨迹？"和"对有多个有效解决方案的任务，什么是正确结果？"的问题变得更难，该领域正在积极研究轨迹打分、过程监督和量表设计。但方向已定：智能体工程正在成为评估驱动的纪律，现在构建强 eval 实践的团队正在构建复合优势——他们的竞争对手无法走捷径的、增长的、自我纠正的质量定义。模型会趋同；eval 集及其编码的质量将是差异化因素。