Agent工作流与编排
定义
工作流(workflow)指控制流由代码预先确定的编排方式:模型调用被放置在固定的节点上,节点之间的转移由代码、规则或可检验的条件决定,模型不选择下一步执行哪个节点。与之相对,Agent 把下一步的选择交给模型,其定义与循环结构见 AI-Agent与工具调用。编排(orchestration)指对节点调度、状态传递、并发控制、失败处理与观测的整体设计。
用状态机描述工作流。设状态集合为 、转移标签集合为 、转移函数为 ,则
当 时流程终止。若流程无环,则它同时是一个有向无环图 ,其中 为节点集合、 为依赖边集合,、。
| 符号 | 含义 |
|---|---|
| 状态集合,本篇中状态是一份可 JSON 序列化的数据 | |
| 转移标签,取值为节点返回的下一阶段名或条件判定结果 | |
| 转移函数,由节点实现与边上的守卫条件共同定义 | |
| 初始状态,由任务输入构造 | |
| 终止状态集合,含成功与失败两类 | |
| DAG 的节点与依赖边 | |
| 最大转移次数,防止不收敛 | |
| 单节点最大重试次数 | |
| 单任务成本上限 |
其余术语在首次出现处定义:提示链(prompt chaining)指把任务拆为固定顺序的多次模型调用;路由(routing)指先分类再分派到不同下游;并行化(parallelization)指同时执行互不依赖的子任务,或对同一任务多次采样后聚合;编排者-工作者(orchestrator-workers)指由一个模型动态拆分子任务并分派给多个执行者;评估者-优化者(evaluator-optimizer)指由一个模型生成、另一个模型按明确标准评估并给出修改要求的循环;重规划(replanning)指在观测到失败或新信息后重新生成计划;检查点(checkpoint)指在节点边界持久化状态以支持恢复;span 指一次可计时的操作记录,多个 span 组成一条轨迹。
为什么重要
单次模型调用只能完成一步映射;多步任务需要控制流。控制流有两种来源:代码与模型。选择哪一种,决定系统的方差、可测试性与成本上界。
由模型决定控制流时,路径数量随步数指数增长。设每步有 种可能的动作、共 步,则路径数为 。取 、,路径数 4096,穷举测试不可行;由代码决定控制流时,路径数等于图中的边数,取 ,可逐条覆盖。这条对比是工作流存在的直接理由:当转移条件可以在设计时枚举,把判断写进代码可以换取确定性与可测性。
失败代价随步数累积。沿用 AI-Agent与工具调用 的估算,单步成功率为 时 步全对的概率约为 。工作流允许在节点边界插入校验与重试,使每一步的失败局部化;纯模型驱动的循环一旦在早期步骤走入错误分支,后续步骤全部在错误状态上执行,且难以从轨迹中定位分叉点。
成本上界同样重要。工作流可以在设计时算出最坏情况的调用次数与 token 上界;Agent 的步数由模型决定,只能在运行时截断。对需要预算承诺的生产系统,这个差别决定能否给出服务等级。
编排还决定多 Agent 是否值得。多 Agent 的收益来自并行与上下文隔离,代价是通信开销、冲突处理与调试复杂度;没有编排设计的多 Agent 系统通常同时承担全部代价而不获得收益。
在本库中的位置:AI-Agent与工具调用 给出单个循环的实现,本篇讨论多个循环与固定节点的组织方式;Agent记忆与上下文 讨论状态如何跨轮保存与检索;MCP协议 给出工具与资源的跨进程接口;Harness与Loop工程 讨论承载这些结构的运行时。对应学习目标中的「会评估」与「能复现」:能画出编排图并说明每条边的条件,能用成功率、步数、成本与延迟四项指标比较不同编排。
原理与推导
1 分界线:谁决定下一步
判断标准可以写成三个可检验的问题。
第一,路径能否在设计时枚举。若所有分支条件都能从可观测状态计算,例如「分类结果为技术类则走检索节点」,则分支有限且已知,写在代码里。若分支依赖模型对开放式输入的判断,且判断结果无法预先列出,则交给模型。
第二,错误是否可局部恢复。工作流中每个节点有明确的输入输出契约,失败可定位到节点并重试;Agent 的失败可能表现为「走错方向」,重试同一步无效,必须回退到更早的状态。若任务需要频繁回退,应把回退显式建模为状态机的边,而不是交给模型自行决定。
第三,成本与延迟是否有上界要求。工作流的调用次数由结构决定,上界可计算;Agent 的调用次数由模型决定,只能截断。对有服务等级要求的场景,工作流更可控。
两者不是互斥关系。常见的结构是「工作流外壳 + Agent 节点」:整体控制流由代码固定,个别需要探索的节点内部是一个完整的 Agent 循环。这样既保留了结构可测性,又在局部允许模型自主决策。判据是:节点内部的步数是否难以预估;若可以预估,节点也应当是固定子图。
| 维度 | 工作流 | 自主 Agent |
|---|---|---|
| 控制流来源 | 代码、规则、守卫条件 | 模型的每次输出 |
| 路径数量 | 等于边数,可枚举 | 随步数指数增长 |
| 可测试性 | 可逐条覆盖边与节点 | 只能按任务集统计成功率 |
| 成本上界 | 设计时可计算 | 运行时截断 |
| 失败定位 | 定位到节点 | 需回放轨迹判断分叉点 |
| 适用任务 | 步骤可预先描述、结果可校验 | 步骤依赖中间观测、无法预先描述 |
2 五种常见模式
提示链把节点按固定顺序串联,前一步输出作为后一步输入的一部分。设单次调用成本为 、延迟为 ,则 步链条的成本为 、延迟约为 。链条的失效方式是误差传播:第 1 步的错误会作为第 2 步的输入被继续加工,最终输出看似合理但基于错误前提。缓解方法是在步骤之间加入可程序化检验的门(gate),例如要求第 1 步输出通过模式校验与关键字段非空检查,未通过则不进入下一步。
路由先由分类器或规则判断输入类型,再分派到对应的下游流程。成本为一次分类加一次下游调用,延迟为两者之和。失效方式是错分:分类错误会使下游用错误的提示与工具处理输入,且错误不可在下游纠正。缓解方法是设置置信度阈值,低于阈值时走通用路径或转人工;同时对每个类别单独统计准确率,避免总体准确率掩盖小类别的高错误率。
并行化有两种形态需要区分。分段(sectioning)把任务拆成互不依赖的子任务并行执行,墙钟时间为 ,成本为各子任务之和;投票(voting)对同一任务重复 次并聚合结果,成本为 倍,用于降低单次采样的方差。投票的收益依赖错误独立性:设单次错误率为 ,三次独立多数投票的错误率为
取 ,;取 ,。当各次采样共享同一提示与同一模型时,错误高度相关,实际 会接近 ,此时投票只增加成本。判断是否需要投票,应先测量同一输入多次采样的结果一致性。
编排者-工作者由一个模型把任务拆成子任务并分派,工作者执行后由编排者汇总。与固定并行的区别是子任务数量与内容在运行时确定。成本为一次拆分、 次执行与一次汇总;失效方式是重复劳动与信息丢失,前者源于拆分粒度不当,后者源于工作者只拿到子任务描述而没有共享约束。
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 倍,收益取决于评估标准是否可检验。若评估者只给出「不好,请改进」这类无标准反馈,循环会震荡或退化;若评估标准是清单式的,例如「必须包含公式」「必须引用来源编号」「数值必须与给定数据一致」,则每一轮都有明确的收敛方向。
flowchart LR
G[生成] --> E{评估:按清单逐项检查}
E -->|全部通过| D[输出]
E -->|存在问题| F[修订:针对问题清单]
F --> G
E -->|轮次达上限| H[带缺陷交付并记录]
3 状态机与 DAG
状态机的三个要素是状态、转移与守卫条件。状态必须是完整描述当前进度所需的最小数据集;转移由节点返回值决定;守卫条件是在转移前必须成立的可检验命题,例如「检索结果非空」「草稿长度超过阈值」。把守卫写成显式判断而非注释,可以在转移失败时给出具体原因。
用状态机建模的收益是可穷举测试。转移总数为 ,取 、,共 36 条待测转移,可以逐条构造用例。这比按任务集统计成功率更能定位缺陷:失败会落在具体边上。
DAG 用于无环的任务分解。节点是任务,边是依赖,拓扑序给出合法的执行顺序。关键路径长度决定并行执行的最短墙钟时间:
取依赖图中有两条路径,耗时分别为 与 ,则关键路径为 10,增加并行度不能把总时长降到 10 以下,只能缩短关键路径上的节点。
需要循环时(重试、修订、重规划),有两种建模方式:在 DAG 上加入带次数上限的回边,或改用状态机。回边必须携带单调递减的计数器,否则不保证停机。这是第 6 节失败处理与易错点中「无限循环」的根源。
状态的可序列化性决定系统能否恢复。状态中只应保存 JSON 可表达的值:字符串、数字、布尔、列表、字典。数据库连接、文件句柄、模型客户端、协程锁都不应进入状态,应改为保存其标识并在恢复时重建。检查点写在节点边界:节点执行前持久化输入状态,执行后持久化输出状态;恢复时从最后一个成功检查点继续,未完成的节点按幂等语义重放。
4 规划
规划是把目标拆成可执行步骤并确定顺序的过程。规划的输出应是一份结构化计划,每个步骤至少包含五个字段:标识、动作(调用哪个工具或哪个子流程)、输入(引用哪些前序输出)、依赖列表、验收条件。
任务分解的终止条件是「步骤可执行」:每一步都能映射到一个工具调用或一次可校验的模型调用,且验收条件可以用程序或明确清单判断。分解过粗会导致单步内部仍有不确定控制流,分解过细会导致步骤间传递成本超过执行成本。
依赖排序是偏序到全序的转换。给定依赖关系,拓扑排序的复杂度为 ;若排序过程中无法取出入度为零的节点,则图中存在环,计划非法。排序结果不唯一,选择时应优先把关键路径上的节点提前,以缩短总时长。
计划的合法性检查包含四项:无环;每个依赖都指向已存在的步骤;预算估计不超过上限,估计方式为各步 token 上界与调用次数之积;每步都有验收条件。缺少第四项时,失败无法判定,重规划也失去依据。
重规划的触发条件应显式定义,常见四类:节点在重试耗尽后仍失败;观测结果与计划假设矛盾,例如检索不到计划中引用的文档;预算消耗超过阈值;出现计划中未覆盖的新信息。重规划本身是一次模型调用,成本不低;每一步都重规划等价于退化为自主 Agent,失去工作流的成本上界。
5 多 Agent 协作
多 Agent 的价值来自两个机制:并行与上下文隔离。并行缩短墙钟时间,隔离使每个 Agent 的上下文只包含完成任务所需的信息,从而降低单次调用的 token 数与干扰。
通信拓扑有四种。主管式(supervisor)由一个协调者向工作者分派并收集,边数为 ,冲突面小;对等式(peer)任意两个 Agent 可通信,边数为 ,适合需要交叉验证的场景,成本随规模平方增长;黑板式(blackboard)通过共享存储间接通信,写入需要版本控制;流水线式(pipeline)按阶段串联,阶段间只传递结构化产物。
消息应包含五个字段:发送者、接收者、意图、载荷、关联标识。关联标识用于把响应匹配到请求,缺少它时并发响应会错配。载荷应是结构化数据而非整段对话历史,后者会使上下文在 Agent 之间复制,成本按 Agent 数量线性增长。
上下文隔离的代价是信息丢失。工作者只看到子任务描述时,可能违反全局约束,例如输出格式、术语表、预算上限。可行的做法是在每个工作者的系统提示中注入一份「约束摘要」,由编排者在分派时生成,并保持与全局状态同步。
冲突有三类。写冲突指两个 Agent 修改同一状态键,后写覆盖先写;结论冲突指两个 Agent 对同一事实给出不同结果;资源冲突指同时占用同一配额。处理方式分别是:为每个键指定唯一写者,其他 Agent 通过消息请求写入;用评估者对冲突结论做裁决,裁决依据是证据而非多数;对配额做集中分配,在分派时预留。
6 失败处理
错误按可恢复性分为四类,处理方式不同。
| 类别 | 例子 | 处理 |
|---|---|---|
| 瞬时错误 | 限流、连接超时、下游 5xx | 退避重试,次数上限 |
| 永久错误 | 参数非法、资源不存在、权限拒绝 | 不重试,走回退或终止 |
| 逻辑错误 | 输出不满足验收条件、计划前提不成立 | 重规划或修订 |
| 策略错误 | 需要人工授权、超出预算 | 升级人工或终止 |
退避重试的间隔取
其中 为已重试次数, 为均匀随机数。随机项用于避免多个客户端同时重试造成同步冲击。重试的前提是操作幂等或携带幂等键,否则超时重试会产生重复副作用,见 AI-Agent与工具调用 第 6 节。
回退有三种形式:换用成本更低的模型或更短的提示;返回缓存中的近似结果并标注降级;返回部分结果并说明缺失部分。三种形式都要求下游能够处理降级标记,否则降级会被当作正常结果使用。
升级人工是第四种处理方式,适用于需要授权、超出预算或连续失败的任务。升级包应包含四项内容:任务目标与当前状态、已尝试的步骤与各自结果、失败原因的错误码与日志片段、可选的建议动作。缺少前三项时,人工需要重新调查,升级反而增加总延迟。
熔断用于阻止连续失败的下游拖垮整个流程。连续失败次数超过阈值后进入打开状态,直接返回失败而不调用下游;经过冷却期后进入半开状态,允许少量请求探测;探测成功后恢复关闭状态。熔断状态应保存在流程状态之外,由运行时统一维护。
预算护栏是最后一道约束。每个任务在开始时分配 token、费用与墙钟预算,节点执行前检查剩余额度,不足时终止并返回已完成部分。缺少护栏时,一个逻辑错误的重试循环可以在数分钟内耗尽月度配额。
7 可观测性
一次任务执行对应一条轨迹,轨迹由 span 组成。每个 span 至少记录:轨迹标识、span 标识、父 span 标识、名称、开始与结束时间、状态、以及属性集合。属性集合包含模型名、输入输出 token 数、费用、工具名、重试次数与错误码。
费用按下式累计:
其中 、 为第 次模型调用的输入与输出 token 数,、 为对应单价。取 、 元每百万 token、、 元每百万 token,单次费用为 元;一个 8 步任务约 0.19 元。这个量级说明为什么「重试次数」与「上下文长度」是成本的主要杠杆。
四项核心指标:成功率、P95 延迟、平均步数、单任务费用。四项都应按任务类型分组统计,总体平均值会掩盖长尾。轨迹还应支持回放:从检查点恢复状态并重放后续节点,用于复现失败。回放要求节点确定性与外部依赖可模拟,两者都需要在设计中预留。
8 框架定位
三个框架的定位差异如下。表中只描述设计中心,不涉及版本特性与性能数字。
| 框架 | 设计中心 | 适合的结构 | 需要自行解决的问题 |
|---|---|---|---|
| LangGraph | 显式图与共享状态,节点与边由开发者定义,支持检查点 | 状态机、带恢复的长流程 | 状态模式设计、评估、成本控制 |
| AutoGen | 多 Agent 会话,Agent 之间以消息交互 | 对话式协作、角色分工 | 终止条件、冲突裁决、轨迹治理 |
| CrewAI | 角色与任务分工,按 crew 组织任务 | 角色清晰的流水线式协作 | 细粒度控制流、失败回退 |
选择依据是控制流的形态:需要显式状态、检查点与确定性转移时,图式结构更直接;需要多个 Agent 反复对话并逐步收敛时,会话式结构更直接;任务可以按角色与交付物划分时,角色式结构更直接。三者都不替代本篇前七节的内容:状态模式、失败处理、评估与成本控制必须在框架之外设计。框架文档见 MCP协议 之外的独立资料,本篇只做定位比较。
9 何时不该用多 Agent
多 Agent 的固定成本包括:每次分派与汇总各一次模型调用;上下文在边界处被压缩,存在信息损失;并发写入需要冲突处理;调试需要跨 Agent 关联轨迹。若收益不能覆盖这些成本,单 Agent 或纯工作流更合适。
判断清单如下,任一条件成立时应优先选择单 Agent 或固定工作流:
- 单次调用或三步以内的提示链即可完成。
- 任务上下文可以完整放入单个窗口,且不需要隔离敏感信息。
- 子任务之间存在强序列依赖,无法并行。
- 端到端延迟预算小于两次模型调用的时间。
- 缺少评估手段,无法判断多 Agent 是否带来改进。
- 任务失败代价高,需要可穷举测试的控制流。
反过来,多 Agent 适用的条件是:子任务可独立执行且有并行收益;不同子任务需要不同工具集或不同权限;上下文规模超过单窗口,必须分区;或者需要独立视角做交叉验证。
关键直觉
编排的本质是把不确定性限制在节点内部,把确定性放在节点之间:节点内部可以是模型,节点之间的边应由代码或可检验条件决定。
与严格定义的关系:状态机定义中的 就是这些边;把 写成显式函数并在每次转移前检查守卫条件,等价于把「下一步做什么」从模型的自由生成改为可测试的判定。工作流并不消除模型的不确定性,它把不确定性约束在可度量、可重试的范围内。
例子与代码
下面的实现包含一个可序列化状态、六个节点、一个带重试的运行器,以及一次完整演示。演示任务是回答「LoRA 的可训练参数量如何计算」,流程为:INTAKE 校验输入,ROUTE 按关键词路由到技术类,RETRIEVE 取回文档,ANALYZE 生成草稿并在首次调用时抛出可重试错误以演示重试,REVIEW 按清单评估,未通过则进入 FIX 修订,修订后再次评估,通过后进入 DONE。
代码分四块。第一块是 Phase 与 State:状态只包含 JSON 可表达的值,to_json 输出用于检查点与日志的视图。第二块是运行器:循环以最大转移次数为上界;捕获 TransientError 时不推进阶段,只增加重试计数,超过上限转入 FAILED;其他异常视为永久错误,直接失败。第三块是节点:每个节点只读取状态并返回下一阶段,打印信息以缩进区分于转移日志。第四块是演示:构造初始状态并打印最终状态、可序列化检查与转移轨迹。
# 带路由与重试的状态机工作流(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 行是评估者-优化者循环:评估给出两项具体问题,修订后复查通过。轨迹末行把每次转移压缩为二元组,可直接用于核对状态机是否只走了预期边。
[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 节部署后的监控、指标与故障归因。