---
tags: [AI, workflow, orchestration]
阶段: 08-Agent与工程化
难度: ★★★
created: 2026-10-18
related: "[[AI-Agent与工具调用]], [[MCP协议]], [[Harness与Loop工程]], [[Agent记忆与上下文]]"
---

# Agent工作流与编排

## 定义

**工作流**（workflow）指控制流由代码预先确定的编排方式：模型调用被放置在固定的节点上，节点之间的转移由代码、规则或可检验的条件决定，模型不选择下一步执行哪个节点。与之相对，**Agent** 把下一步的选择交给模型，其定义与循环结构见 [[AI-Agent与工具调用]]。**编排**（orchestration）指对节点调度、状态传递、并发控制、失败处理与观测的整体设计。

用状态机描述工作流。设状态集合为 $S$、转移标签集合为 $\Sigma$、转移函数为 $\delta$，则

$$
s_{t+1}=\delta(s_t,\sigma_t),\qquad
\sigma_t\in\Sigma,\qquad
s_0\in S,\qquad
F\subseteq S,
$$

当 $s_t\in F$ 时流程终止。若流程无环，则它同时是一个有向无环图 $G=(V,E)$，其中 $V$ 为节点集合、$E$ 为依赖边集合，$|V|=n$、$|E|=m$。

| 符号 | 含义 |
|---|---|
| $S$ | 状态集合，本篇中状态是一份可 JSON 序列化的数据 |
| $\Sigma$ | 转移标签，取值为节点返回的下一阶段名或条件判定结果 |
| $\delta$ | 转移函数，由节点实现与边上的守卫条件共同定义 |
| $s_0$ | 初始状态，由任务输入构造 |
| $F$ | 终止状态集合，含成功与失败两类 |
| $V,\ E$ | DAG 的节点与依赖边 |
| $T$ | 最大转移次数，防止不收敛 |
| $r$ | 单节点最大重试次数 |
| $c$ | 单任务成本上限 |

其余术语在首次出现处定义：**提示链**（prompt chaining）指把任务拆为固定顺序的多次模型调用；**路由**（routing）指先分类再分派到不同下游；**并行化**（parallelization）指同时执行互不依赖的子任务，或对同一任务多次采样后聚合；**编排者-工作者**（orchestrator-workers）指由一个模型动态拆分子任务并分派给多个执行者；**评估者-优化者**（evaluator-optimizer）指由一个模型生成、另一个模型按明确标准评估并给出修改要求的循环；**重规划**（replanning）指在观测到失败或新信息后重新生成计划；**检查点**（checkpoint）指在节点边界持久化状态以支持恢复；**span** 指一次可计时的操作记录，多个 span 组成一条轨迹。

## 为什么重要

单次模型调用只能完成一步映射；多步任务需要控制流。控制流有两种来源：代码与模型。选择哪一种，决定系统的方差、可测试性与成本上界。

由模型决定控制流时，路径数量随步数指数增长。设每步有 $b$ 种可能的动作、共 $n$ 步，则路径数为 $b^{n}$。取 $b=4$、$n=6$，路径数 4096，穷举测试不可行；由代码决定控制流时，路径数等于图中的边数，取 $m=12$，可逐条覆盖。这条对比是工作流存在的直接理由：当转移条件可以在设计时枚举，把判断写进代码可以换取确定性与可测性。

失败代价随步数累积。沿用 [[AI-Agent与工具调用]] 的估算，单步成功率为 $p$ 时 $n$ 步全对的概率约为 $p^{n}$。工作流允许在节点边界插入校验与重试，使每一步的失败局部化；纯模型驱动的循环一旦在早期步骤走入错误分支，后续步骤全部在错误状态上执行，且难以从轨迹中定位分叉点。

成本上界同样重要。工作流可以在设计时算出最坏情况的调用次数与 token 上界；Agent 的步数由模型决定，只能在运行时截断。对需要预算承诺的生产系统，这个差别决定能否给出服务等级。

编排还决定多 Agent 是否值得。多 Agent 的收益来自并行与上下文隔离，代价是通信开销、冲突处理与调试复杂度；没有编排设计的多 Agent 系统通常同时承担全部代价而不获得收益。

在本库中的位置：[[AI-Agent与工具调用]] 给出单个循环的实现，本篇讨论多个循环与固定节点的组织方式；[[Agent记忆与上下文]] 讨论状态如何跨轮保存与检索；[[MCP协议]] 给出工具与资源的跨进程接口；[[Harness与Loop工程]] 讨论承载这些结构的运行时。对应学习目标中的「会评估」与「能复现」：能画出编排图并说明每条边的条件，能用成功率、步数、成本与延迟四项指标比较不同编排。

## 原理与推导

### 1 分界线：谁决定下一步

判断标准可以写成三个可检验的问题。

第一，路径能否在设计时枚举。若所有分支条件都能从可观测状态计算，例如「分类结果为技术类则走检索节点」，则分支有限且已知，写在代码里。若分支依赖模型对开放式输入的判断，且判断结果无法预先列出，则交给模型。

第二，错误是否可局部恢复。工作流中每个节点有明确的输入输出契约，失败可定位到节点并重试；Agent 的失败可能表现为「走错方向」，重试同一步无效，必须回退到更早的状态。若任务需要频繁回退，应把回退显式建模为状态机的边，而不是交给模型自行决定。

第三，成本与延迟是否有上界要求。工作流的调用次数由结构决定，上界可计算；Agent 的调用次数由模型决定，只能截断。对有服务等级要求的场景，工作流更可控。

两者不是互斥关系。常见的结构是「工作流外壳 + Agent 节点」：整体控制流由代码固定，个别需要探索的节点内部是一个完整的 Agent 循环。这样既保留了结构可测性，又在局部允许模型自主决策。判据是：节点内部的步数是否难以预估；若可以预估，节点也应当是固定子图。

| 维度 | 工作流 | 自主 Agent |
|---|---|---|
| 控制流来源 | 代码、规则、守卫条件 | 模型的每次输出 |
| 路径数量 | 等于边数，可枚举 | 随步数指数增长 |
| 可测试性 | 可逐条覆盖边与节点 | 只能按任务集统计成功率 |
| 成本上界 | 设计时可计算 | 运行时截断 |
| 失败定位 | 定位到节点 | 需回放轨迹判断分叉点 |
| 适用任务 | 步骤可预先描述、结果可校验 | 步骤依赖中间观测、无法预先描述 |

### 2 五种常见模式

提示链把节点按固定顺序串联，前一步输出作为后一步输入的一部分。设单次调用成本为 $c$、延迟为 $\ell$，则 $n$ 步链条的成本为 $nc$、延迟约为 $n\ell$。链条的失效方式是误差传播：第 1 步的错误会作为第 2 步的输入被继续加工，最终输出看似合理但基于错误前提。缓解方法是在步骤之间加入可程序化检验的门（gate），例如要求第 1 步输出通过模式校验与关键字段非空检查，未通过则不进入下一步。

路由先由分类器或规则判断输入类型，再分派到对应的下游流程。成本为一次分类加一次下游调用，延迟为两者之和。失效方式是错分：分类错误会使下游用错误的提示与工具处理输入，且错误不可在下游纠正。缓解方法是设置置信度阈值，低于阈值时走通用路径或转人工；同时对每个类别单独统计准确率，避免总体准确率掩盖小类别的高错误率。

并行化有两种形态需要区分。分段（sectioning）把任务拆成互不依赖的子任务并行执行，墙钟时间为 $\max_i \tau_i$，成本为各子任务之和；投票（voting）对同一任务重复 $k$ 次并聚合结果，成本为 $k$ 倍，用于降低单次采样的方差。投票的收益依赖错误独立性：设单次错误率为 $e$，三次独立多数投票的错误率为

$$
e_3=3e^{2}(1-e)+e^{3}=3e^{2}-2e^{3}.
$$

取 $e=0.1$，$e_3=0.028$；取 $e=0.3$，$e_3=0.216$。当各次采样共享同一提示与同一模型时，错误高度相关，实际 $e_3$ 会接近 $e$，此时投票只增加成本。判断是否需要投票，应先测量同一输入多次采样的结果一致性。

编排者-工作者由一个模型把任务拆成子任务并分派，工作者执行后由编排者汇总。与固定并行的区别是子任务数量与内容在运行时确定。成本为一次拆分、$k$ 次执行与一次汇总；失效方式是重复劳动与信息丢失，前者源于拆分粒度不当，后者源于工作者只拿到子任务描述而没有共享约束。

```mermaid
flowchart TD
    U[任务] --> O[编排者：拆分子任务]
    O --> W1[工作者 1：检索]
    O --> W2[工作者 2：计算]
    O --> W3[工作者 3：校验]
    W1 --> A[汇总与一致性检查]
    W2 --> A
    W3 --> A
    A -->|存在缺口| O
    A -->|通过| D[输出]
```

评估者-优化者由一个生成节点产出候选，一个评估节点按明确标准给出问题清单，修订节点据此修改，循环直到通过或达到轮次上限。成本约为单次生成的 2 至 3 倍，收益取决于评估标准是否可检验。若评估者只给出「不好，请改进」这类无标准反馈，循环会震荡或退化；若评估标准是清单式的，例如「必须包含公式」「必须引用来源编号」「数值必须与给定数据一致」，则每一轮都有明确的收敛方向。

```mermaid
flowchart LR
    G[生成] --> E{评估：按清单逐项检查}
    E -->|全部通过| D[输出]
    E -->|存在问题| F[修订：针对问题清单]
    F --> G
    E -->|轮次达上限| H[带缺陷交付并记录]
```

### 3 状态机与 DAG

状态机的三个要素是状态、转移与守卫条件。状态必须是完整描述当前进度所需的最小数据集；转移由节点返回值决定；守卫条件是在转移前必须成立的可检验命题，例如「检索结果非空」「草稿长度超过阈值」。把守卫写成显式判断而非注释，可以在转移失败时给出具体原因。

用状态机建模的收益是可穷举测试。转移总数为 $|S|\times|\Sigma|$，取 $|S|=6$、$|\Sigma|=6$，共 36 条待测转移，可以逐条构造用例。这比按任务集统计成功率更能定位缺陷：失败会落在具体边上。

DAG 用于无环的任务分解。节点是任务，边是依赖，拓扑序给出合法的执行顺序。关键路径长度决定并行执行的最短墙钟时间：

$$
L_{\text{crit}}=\max_{\text{路径}}\sum_{v\in\text{路径}}\tau_v.
$$

取依赖图中有两条路径，耗时分别为 $3+5+2=10$ 与 $4+2=6$，则关键路径为 10，增加并行度不能把总时长降到 10 以下，只能缩短关键路径上的节点。

需要循环时（重试、修订、重规划），有两种建模方式：在 DAG 上加入带次数上限的回边，或改用状态机。回边必须携带单调递减的计数器，否则不保证停机。这是第 6 节失败处理与易错点中「无限循环」的根源。

状态的可序列化性决定系统能否恢复。状态中只应保存 JSON 可表达的值：字符串、数字、布尔、列表、字典。数据库连接、文件句柄、模型客户端、协程锁都不应进入状态，应改为保存其标识并在恢复时重建。检查点写在节点边界：节点执行前持久化输入状态，执行后持久化输出状态；恢复时从最后一个成功检查点继续，未完成的节点按幂等语义重放。

### 4 规划

规划是把目标拆成可执行步骤并确定顺序的过程。规划的输出应是一份结构化计划，每个步骤至少包含五个字段：标识、动作（调用哪个工具或哪个子流程）、输入（引用哪些前序输出）、依赖列表、验收条件。

任务分解的终止条件是「步骤可执行」：每一步都能映射到一个工具调用或一次可校验的模型调用，且验收条件可以用程序或明确清单判断。分解过粗会导致单步内部仍有不确定控制流，分解过细会导致步骤间传递成本超过执行成本。

依赖排序是偏序到全序的转换。给定依赖关系，拓扑排序的复杂度为 $O(|V|+|E|)$；若排序过程中无法取出入度为零的节点，则图中存在环，计划非法。排序结果不唯一，选择时应优先把关键路径上的节点提前，以缩短总时长。

计划的合法性检查包含四项：无环；每个依赖都指向已存在的步骤；预算估计不超过上限，估计方式为各步 token 上界与调用次数之积；每步都有验收条件。缺少第四项时，失败无法判定，重规划也失去依据。

重规划的触发条件应显式定义，常见四类：节点在重试耗尽后仍失败；观测结果与计划假设矛盾，例如检索不到计划中引用的文档；预算消耗超过阈值；出现计划中未覆盖的新信息。重规划本身是一次模型调用，成本不低；每一步都重规划等价于退化为自主 Agent，失去工作流的成本上界。

### 5 多 Agent 协作

多 Agent 的价值来自两个机制：并行与上下文隔离。并行缩短墙钟时间，隔离使每个 Agent 的上下文只包含完成任务所需的信息，从而降低单次调用的 token 数与干扰。

通信拓扑有四种。主管式（supervisor）由一个协调者向工作者分派并收集，边数为 $O(k)$，冲突面小；对等式（peer）任意两个 Agent 可通信，边数为 $O(k^{2})$，适合需要交叉验证的场景，成本随规模平方增长；黑板式（blackboard）通过共享存储间接通信，写入需要版本控制；流水线式（pipeline）按阶段串联，阶段间只传递结构化产物。

消息应包含五个字段：发送者、接收者、意图、载荷、关联标识。关联标识用于把响应匹配到请求，缺少它时并发响应会错配。载荷应是结构化数据而非整段对话历史，后者会使上下文在 Agent 之间复制，成本按 Agent 数量线性增长。

上下文隔离的代价是信息丢失。工作者只看到子任务描述时，可能违反全局约束，例如输出格式、术语表、预算上限。可行的做法是在每个工作者的系统提示中注入一份「约束摘要」，由编排者在分派时生成，并保持与全局状态同步。

冲突有三类。写冲突指两个 Agent 修改同一状态键，后写覆盖先写；结论冲突指两个 Agent 对同一事实给出不同结果；资源冲突指同时占用同一配额。处理方式分别是：为每个键指定唯一写者，其他 Agent 通过消息请求写入；用评估者对冲突结论做裁决，裁决依据是证据而非多数；对配额做集中分配，在分派时预留。

### 6 失败处理

错误按可恢复性分为四类，处理方式不同。

| 类别 | 例子 | 处理 |
|---|---|---|
| 瞬时错误 | 限流、连接超时、下游 5xx | 退避重试，次数上限 $r$ |
| 永久错误 | 参数非法、资源不存在、权限拒绝 | 不重试，走回退或终止 |
| 逻辑错误 | 输出不满足验收条件、计划前提不成立 | 重规划或修订 |
| 策略错误 | 需要人工授权、超出预算 | 升级人工或终止 |

退避重试的间隔取

$$
d_n=\min\big(d_{\max},\ d_0\cdot2^{n}\big)\cdot U(0,1),
$$

其中 $n$ 为已重试次数，$U(0,1)$ 为均匀随机数。随机项用于避免多个客户端同时重试造成同步冲击。重试的前提是操作幂等或携带幂等键，否则超时重试会产生重复副作用，见 [[AI-Agent与工具调用]] 第 6 节。

回退有三种形式：换用成本更低的模型或更短的提示；返回缓存中的近似结果并标注降级；返回部分结果并说明缺失部分。三种形式都要求下游能够处理降级标记，否则降级会被当作正常结果使用。

升级人工是第四种处理方式，适用于需要授权、超出预算或连续失败的任务。升级包应包含四项内容：任务目标与当前状态、已尝试的步骤与各自结果、失败原因的错误码与日志片段、可选的建议动作。缺少前三项时，人工需要重新调查，升级反而增加总延迟。

熔断用于阻止连续失败的下游拖垮整个流程。连续失败次数超过阈值后进入打开状态，直接返回失败而不调用下游；经过冷却期后进入半开状态，允许少量请求探测；探测成功后恢复关闭状态。熔断状态应保存在流程状态之外，由运行时统一维护。

预算护栏是最后一道约束。每个任务在开始时分配 token、费用与墙钟预算，节点执行前检查剩余额度，不足时终止并返回已完成部分。缺少护栏时，一个逻辑错误的重试循环可以在数分钟内耗尽月度配额。

### 7 可观测性

一次任务执行对应一条轨迹，轨迹由 span 组成。每个 span 至少记录：轨迹标识、span 标识、父 span 标识、名称、开始与结束时间、状态、以及属性集合。属性集合包含模型名、输入输出 token 数、费用、工具名、重试次数与错误码。

费用按下式累计：

$$
\text{cost}=\sum_{t}\big(T^{\text{in}}_t p_{\text{in}}+T^{\text{out}}_t p_{\text{out}}\big)+\sum_{j}\text{cost}_{\text{tool},j},
$$

其中 $T^{\text{in}}_t$、$T^{\text{out}}_t$ 为第 $t$ 次模型调用的输入与输出 token 数，$p_{\text{in}}$、$p_{\text{out}}$ 为对应单价。取 $T^{\text{in}}=20000$、$p_{\text{in}}=1$ 元每百万 token、$T^{\text{out}}=1000$、$p_{\text{out}}=4$ 元每百万 token，单次费用为 $0.02+0.004=0.024$ 元；一个 8 步任务约 0.19 元。这个量级说明为什么「重试次数」与「上下文长度」是成本的主要杠杆。

四项核心指标：成功率、P95 延迟、平均步数、单任务费用。四项都应按任务类型分组统计，总体平均值会掩盖长尾。轨迹还应支持回放：从检查点恢复状态并重放后续节点，用于复现失败。回放要求节点确定性与外部依赖可模拟，两者都需要在设计中预留。

### 8 框架定位

三个框架的定位差异如下。表中只描述设计中心，不涉及版本特性与性能数字。

| 框架 | 设计中心 | 适合的结构 | 需要自行解决的问题 |
|---|---|---|---|
| LangGraph | 显式图与共享状态，节点与边由开发者定义，支持检查点 | 状态机、带恢复的长流程 | 状态模式设计、评估、成本控制 |
| AutoGen | 多 Agent 会话，Agent 之间以消息交互 | 对话式协作、角色分工 | 终止条件、冲突裁决、轨迹治理 |
| CrewAI | 角色与任务分工，按 crew 组织任务 | 角色清晰的流水线式协作 | 细粒度控制流、失败回退 |

选择依据是控制流的形态：需要显式状态、检查点与确定性转移时，图式结构更直接；需要多个 Agent 反复对话并逐步收敛时，会话式结构更直接；任务可以按角色与交付物划分时，角色式结构更直接。三者都不替代本篇前七节的内容：状态模式、失败处理、评估与成本控制必须在框架之外设计。框架文档见 [[MCP协议]] 之外的独立资料，本篇只做定位比较。

### 9 何时不该用多 Agent

多 Agent 的固定成本包括：每次分派与汇总各一次模型调用；上下文在边界处被压缩，存在信息损失；并发写入需要冲突处理；调试需要跨 Agent 关联轨迹。若收益不能覆盖这些成本，单 Agent 或纯工作流更合适。

判断清单如下，任一条件成立时应优先选择单 Agent 或固定工作流：

1. 单次调用或三步以内的提示链即可完成。
2. 任务上下文可以完整放入单个窗口，且不需要隔离敏感信息。
3. 子任务之间存在强序列依赖，无法并行。
4. 端到端延迟预算小于两次模型调用的时间。
5. 缺少评估手段，无法判断多 Agent 是否带来改进。
6. 任务失败代价高，需要可穷举测试的控制流。

反过来，多 Agent 适用的条件是：子任务可独立执行且有并行收益；不同子任务需要不同工具集或不同权限；上下文规模超过单窗口，必须分区；或者需要独立视角做交叉验证。

## 关键直觉

> [!tip] 编排的本质是把不确定性限制在节点内部，把确定性放在节点之间：节点内部可以是模型，节点之间的边应由代码或可检验条件决定。
>
> 与严格定义的关系：状态机定义中的 $\delta$ 就是这些边；把 $\delta$ 写成显式函数并在每次转移前检查守卫条件，等价于把「下一步做什么」从模型的自由生成改为可测试的判定。工作流并不消除模型的不确定性，它把不确定性约束在可度量、可重试的范围内。

## 例子与代码

下面的实现包含一个可序列化状态、六个节点、一个带重试的运行器，以及一次完整演示。演示任务是回答「LoRA 的可训练参数量如何计算」，流程为：`INTAKE` 校验输入，`ROUTE` 按关键词路由到技术类，`RETRIEVE` 取回文档，`ANALYZE` 生成草稿并在首次调用时抛出可重试错误以演示重试，`REVIEW` 按清单评估，未通过则进入 `FIX` 修订，修订后再次评估，通过后进入 `DONE`。

代码分四块。第一块是 `Phase` 与 `State`：状态只包含 JSON 可表达的值，`to_json` 输出用于检查点与日志的视图。第二块是运行器：循环以最大转移次数为上界；捕获 `TransientError` 时不推进阶段，只增加重试计数，超过上限转入 `FAILED`；其他异常视为永久错误，直接失败。第三块是节点：每个节点只读取状态并返回下一阶段，打印信息以缩进区分于转移日志。第四块是演示：构造初始状态并打印最终状态、可序列化检查与转移轨迹。

```python
# 带路由与重试的状态机工作流（Python 3.10+，仅用标准库）
from __future__ import annotations

import json
from dataclasses import dataclass, field
from enum import Enum
from typing import Callable


class Phase(str, Enum):
    INTAKE = "INTAKE"
    ROUTE = "ROUTE"
    RETRIEVE = "RETRIEVE"
    ANALYZE = "ANALYZE"
    REVIEW = "REVIEW"
    FIX = "FIX"
    DONE = "DONE"
    FAILED = "FAILED"


@dataclass
class State:
    """全部字段都是可 JSON 序列化的基础类型，便于检查点与回放。"""

    task_id: str
    question: str
    route: str = ""
    docs: list[str] = field(default_factory=list)
    draft: str = ""
    issues: list[str] = field(default_factory=list)
    fix_rounds: int = 0
    calls: dict[str, int] = field(default_factory=dict)    # 节点内部调用计数
    retries: dict[str, int] = field(default_factory=dict)  # 运行器重试计数
    trace: list[dict[str, object]] = field(default_factory=list)

    def to_json(self) -> str:
        return json.dumps(
            {
                "task_id": self.task_id,
                "question": self.question,
                "route": self.route,
                "docs": self.docs,
                "issues": self.issues,
                "fix_rounds": self.fix_rounds,
                "trace": self.trace,
            },
            ensure_ascii=False,
        )


class TransientError(Exception):
    """可重试错误：限流、网络抖动、下游临时不可用。"""


MAX_TRANSITIONS = 12
MAX_RETRIES = 2
MAX_FIX_ROUNDS = 2


class Workflow:
    def __init__(self, nodes: dict[Phase, Callable[[State], Phase]]) -> None:
        self.nodes = nodes

    def run(self, state: State) -> tuple[State, Phase]:
        phase = Phase.INTAKE
        for seq in range(1, MAX_TRANSITIONS + 1):
            handler = self.nodes[phase]
            try:
                nxt = handler(state)
            except TransientError as exc:
                used = state.retries.get(phase.value, 0) + 1
                state.retries[phase.value] = used
                print(f"[{seq:02d}] {phase.value:<8} !! 可重试错误: {exc} (第 {used} 次)")
                state.trace.append({"seq": seq, "phase": phase.value,
                                    "status": "retry", "error": str(exc)})
                if used > MAX_RETRIES:
                    print(f"[{seq:02d}] {phase.value:<8} -> FAILED (重试耗尽)")
                    state.trace.append({"seq": seq, "phase": phase.value,
                                        "next": "FAILED", "error": str(exc)})
                    return state, Phase.FAILED
                continue  # 不推进状态，重试同一节点
            except Exception as exc:  # 永久错误直接失败，不做重试
                print(f"[{seq:02d}] {phase.value:<8} -> FAILED ({type(exc).__name__}: {exc})")
                state.trace.append({"seq": seq, "phase": phase.value,
                                    "next": "FAILED", "error": str(exc)})
                return state, Phase.FAILED

            state.trace.append({"seq": seq, "phase": phase.value, "next": nxt.value})
            print(f"[{seq:02d}] {phase.value:<8} -> {nxt.value}")
            if nxt in (Phase.DONE, Phase.FAILED):
                return state, nxt
            phase = nxt
        print(f"[{MAX_TRANSITIONS:02d}] 达到最大转移次数，强制终止")
        return state, Phase.FAILED


# ---------- 节点实现：每个节点只读 State，返回下一个 Phase ----------
DOCS = {
    "technical": [
        "LoRA 在冻结的原权重旁路加入低秩分解矩阵 A 与 B，仅训练这两个矩阵。",
        "若原权重形状为 d×k，秩为 r，则单层可训练参数量为 r(d+k)。",
    ],
    "billing": ["账单按 token 计费，输入与输出单价不同。"],
}


def intake(state: State) -> Phase:
    state.question = state.question.strip()
    if len(state.question) < 4:
        raise ValueError("问题过短，无法处理")
    return Phase.ROUTE


def route(state: State) -> Phase:
    q = state.question
    if any(k in q for k in ("参数量", "LoRA", "公式", "梯度")):
        state.route = "technical"
    elif any(k in q for k in ("账单", "计费", "价格")):
        state.route = "billing"
    else:
        state.route = "technical"
    print(f"       路由规则命中: route={state.route}")
    return Phase.RETRIEVE


def retrieve(state: State) -> Phase:
    state.docs = DOCS.get(state.route, [])
    if not state.docs:
        raise ValueError(f"路由 {state.route} 没有可用文档")
    print(f"       检索到 {len(state.docs)} 条文档")
    return Phase.ANALYZE


def analyze(state: State) -> Phase:
    n = state.calls.get("ANALYZE", 0) + 1
    state.calls["ANALYZE"] = n
    if n == 1:
        raise TransientError("模型网关 429")
    state.draft = "LoRA 在权重旁路加入低秩矩阵，因此可训练参数显著减少。"
    print(f"       生成草稿 {len(state.draft)} 字")
    return Phase.REVIEW


def review(state: State) -> Phase:
    state.issues = []
    if "r(d+k)" not in state.draft:
        state.issues.append("缺少单层参数量公式 r(d+k)")
    if "冻结" not in state.draft:
        state.issues.append("未说明原权重被冻结")
    print(f"       评估结果: {state.issues or '通过'}")
    if not state.issues:
        return Phase.DONE
    if state.fix_rounds >= MAX_FIX_ROUNDS:
        print("       修订轮次达到上限，带缺陷交付")
        return Phase.DONE
    return Phase.FIX


def fix(state: State) -> Phase:
    state.fix_rounds += 1
    missing = "；".join(state.issues)
    state.draft = (
        "LoRA 冻结原权重，在旁路加入低秩矩阵 A（r×k）与 B（d×r），"
        "单层可训练参数量为 r(d+k)。"
    )
    print(f"       第 {state.fix_rounds} 轮修订，针对: {missing}")
    return Phase.REVIEW


workflow = Workflow({
    Phase.INTAKE: intake,
    Phase.ROUTE: route,
    Phase.RETRIEVE: retrieve,
    Phase.ANALYZE: analyze,
    Phase.REVIEW: review,
    Phase.FIX: fix,
})

state = State(task_id="T-001", question="LoRA 的可训练参数量如何计算？")
final_state, final_phase = workflow.run(state)

print("---")
print("终止阶段:", final_phase.value)
print("状态可序列化:", json.loads(final_state.to_json())["task_id"])
print("最终草案:", final_state.draft)
print("转移轨迹:", [(t["phase"], t.get("next") or t.get("status")) for t in final_state.trace])
```

输出如下。第 4 行是重试：`ANALYZE` 首次调用抛出瞬时错误，运行器不推进阶段，第二次进入同一节点后成功。第 6 至 8 行是评估者-优化者循环：评估给出两项具体问题，修订后复查通过。轨迹末行把每次转移压缩为二元组，可直接用于核对状态机是否只走了预期边。

```text
[01] INTAKE   -> ROUTE
       路由规则命中: route=technical
[02] ROUTE    -> RETRIEVE
       检索到 2 条文档
[03] RETRIEVE -> ANALYZE
[04] ANALYZE  !! 可重试错误: 模型网关 429 (第 1 次)
       生成草稿 29 字
[05] ANALYZE  -> REVIEW
       评估结果: ['缺少单层参数量公式 r(d+k)', '未说明原权重被冻结']
[06] REVIEW   -> FIX
       第 1 轮修订，针对: 缺少单层参数量公式 r(d+k)；未说明原权重被冻结
[07] FIX      -> REVIEW
       评估结果: 通过
[08] REVIEW   -> DONE
---
终止阶段: DONE
状态可序列化: T-001
最终草案: LoRA 冻结原权重，在旁路加入低秩矩阵 A（r×k）与 B（d×r），单层可训练参数量为 r(d+k)。
转移轨迹: [('INTAKE', 'ROUTE'), ('ROUTE', 'RETRIEVE'), ('RETRIEVE', 'ANALYZE'), ('ANALYZE', 'retry'), ('ANALYZE', 'REVIEW'), ('REVIEW', 'FIX'), ('FIX', 'REVIEW'), ('REVIEW', 'DONE')]
```

几个部件的移除实验可以说明设计意图。去掉 `MAX_TRANSITIONS`，若 `review` 的通过条件写错，`REVIEW → FIX → REVIEW` 会无限循环；去掉 `retries` 计数，瞬时错误会被无限重试；把 `phase` 直接存成模型客户端对象，`to_json` 会抛出 `TypeError`，检查点无法写入；把 `REVIEW` 的问题清单改为自由文本「请改进」，`FIX` 无法知道改什么，`fix_rounds` 会以随机方向增长。

演示中有两处刻意简化。第一，路由使用关键词规则而非模型分类，便于复现；生产系统应把分类器输出与置信度一并写入状态，低于阈值时转人工。第二，评估与修订共用一个进程，真实系统中评估者应是独立调用，并只接收草稿与清单，不接收生成过程的中间推理，以避免评估者复用生成者的错误前提。

## 易错点

> [!warning]
> 1. 无限循环。修订循环或重试循环只设了「成功即退出」，没有设次数上限；或回边计数器在异常分支未递减。检查方法：对每个环，指出环上单调变化的量及其上界。
> 2. 状态不可序列化。把客户端、文件句柄、锁或生成器放进状态，检查点写入失败，恢复时读取到空值。检查方法：对状态调用一次 `json.dumps`，失败即不合规。
> 3. 并行写冲突。两个分支同时写同一状态键，后完成的分支覆盖前者，且顺序不确定。检查方法：为每个状态键标注唯一写者，或为写操作定义合并函数。
> 4. 评估缺失。评估者与生成者使用同一提示、没有明确清单，评估结论恒为通过；或只统计最终成功率而不统计每轮修订的增益。检查方法：人为注入一个已知缺陷，确认评估者能检出。
> 5. 重试非幂等节点。超时后重试发送邮件或创建订单，产生重复副作用。检查方法：列出所有有副作用的节点，确认重试路径上是否携带幂等键。
> 6. 跨 Agent 复制全量上下文。每个工作者都收到完整对话历史，成本按 Agent 数量线性增长，且关键约束被淹没。检查方法：统计每个 Agent 的输入 token，确认其只包含子任务所需内容。

## 关联笔记

- [[AI-Agent与工具调用]] —— 前置：单循环的动作协议、错误回填与终止条件，是工作流节点的实现基础。
- [[Agent记忆与上下文]] —— 后续：跨轮状态的保存、摘要与检索，决定编排能承载多长的任务。
- [[MCP协议]] —— 后续：节点调用外部工具与资源的标准化接口。
- [[Harness与Loop工程]] —— 后续：承载编排的运行时、检查点与轨迹系统。
- [[成本-延迟-质量权衡]] —— 对照：路由、并行与评估循环在三项指标上的取舍。

## 达标检测

- [ ] 用三个问题判断一个任务应实现为工作流还是自主 Agent，并对给定任务给出理由。
- [ ] 画出五种编排模式中任意三种的结构图，标注每种模式的成本上界与主要失效方式。
- [ ] 给定依赖图，手工做一次拓扑排序并指出关键路径。
- [ ] 运行本篇代码，把 `MAX_RETRIES` 改为 0 并说明输出如何变化。
- [ ] 指出状态中不可序列化的一个字段，给出替换方案。
- [ ] 为一个两分支并行流程设计冲突处理规则，并说明写者的确定方式。

## 参考来源

- Anthropic, "Building effective agents", 2024 —— 对应本篇第 2 节的五种模式划分与「优先选择最简单结构」的判断。
- Yao et al., "ReAct: Synergizing Reasoning and Acting in Language Models", arXiv:2210.03629 —— 对应第 1 节关于模型驱动控制流的讨论。
- LangChain, LangGraph 文档, langchain-ai.github.io/langgraph —— 对应第 8 节图式编排与检查点的定位描述。
- Chip Huyen, *Designing Machine Learning Systems*, 2022, 第 7 章与第 8 章 —— 对应第 7 节部署后的监控、指标与故障归因。
