Skip to content

Agent 编排:从 ReAct 循环到可恢复的状态机 ​

一、先说清楚这个类目要练的手艺 ​

同一张报销单,财务系统里出现了两次。

第二次不是用户提交的。第一次跑挂了,运维改了个参数重新触发,系统就老老实实又提交了一遍。

钱多付了一笔,追回来花了三周。

这件事跟模型聪不聪明无关。它跟编排有关:当一次任务需要七八步、中间会失败、还要有人签字才能继续时,你拿什么把它串起来,以及串错了之后怎么收场。

练完之后你手上应该有四件东西:

  • 判断一个任务该用 ReAct 循环还是固定编排,并说得出另一半为什么不行
  • 一张能跑的状态图,节点、边、状态字段都写清楚
  • 一个断点,让流程在关键动作前停下来等人,且重启后能接上
  • 一套让重试不把副作用做两遍的写法

版本基线,截至 2026 年 11 月:LangGraph 的 Python 包在 1.2.x 线上,LangChain 在 1.5.x 线上,TypeScript 侧 @langchain/langgraph 在 1.7.x 线上。精确小版本请看 LangGraph 发布页 与 LangChain 发布页,我在这里给区间不给点号,因为它一个月动好几次。要注意的是 Python 版本门槛:LangChain 1.5 一线与 langchain-core 已经不再把 Python 3.10 列进支持范围,要 3.11 以上;而 LangGraph 包自身在 PyPI 上仍标 >=3.10,两者口径不一致,别踩在这条缝上。LangGraph 官方对自己的定位很清楚:低层编排运行时,不规定提示词也不规定 Agent 架构,见 LangGraph 概览。后面所有范式都得你自己定。

二、四种范式在技术栈里的坐标 ​

先看一张图,把四个词放到同一个坐标系里。纵轴是「路径由谁决定」,横轴是「状态存在哪」。

四种范式的区别,本质上不是「谁更先进」,而是「你把不确定性放在哪一层」。

ReAct 把不确定性放进每一步的决策里。形式是思考、行动、观察三步交替,arXiv:2210.03629 那篇 2022 年的论文讲透了:推理轨迹帮模型跟踪和更新计划、处理异常,行动让它去接触外部信息源。原文在 HotpotQA 和 Fever 上的实验说明,边想边查能缓解纯思维链的幻觉与错误传播。

Plan-Execute 把不确定性前置。先让模型输出一份完整计划,再逐条执行。Plan-and-Solve 那篇(arXiv:2305.04091,ACL 2023)针对的是零样本思维链的三类错误:计算错误、漏步、语义误解,其中「漏步」正是靠先出计划解决的。

Reflection 把不确定性放到事后。Reflexion(arXiv:2303.11366)不更新权重,让 Agent 对自己的失败做语言反思,把反思文本存进情节记忆,下一轮带着它重来。论文里 HumanEval 上 pass@1 报到 91%。

固定编排把不确定性彻底挪走。顺序、分支、重试全写在代码里,模型只在单个节点内部被调用。

一张对照表,把它钉住:

范式谁决定下一步适合什么任务主要失效方式
ReAct模型,每一步探索型:排查、检索、多源比对打转、重复调用、跑偏
Plan-Execute模型,一次性步骤可枚举但顺序不定的任务计划一开始就错,后面全错
Reflection模型,事后有明确验收信号(测试、校验)的任务反思空转,越改越远
固定编排代码合规流程、有明确 SOP 的业务遇到没写进代码的情况直接卡死

三、导入案例:一次报销单卡在第七步 ​

去年十月的一个报销审核助手,值得完整讲一遍,因为它把三个坑一次占齐了。

流程本来是这样:读单据 → 抽取金额与科目 → 查制度限额 → 判定是否超标 → 超标则生成说明 → 提交审批。第七步是「提交」,会真的写进财务系统。

出问题的那次,抽取环节把一张 3800 元的住宿发票识别成了 38000 元,判定环节正确地判成超标,生成了一段解释,然后提交了。人是在审批流里看到「超标十倍」才发现的。

复盘三个结论。抽取和判定之间没有人工确认点,这是设计缺陷,不是模型缺陷。判定到提交之间没有状态快照,出问题无法从中间重跑,只能整单重来。最要命的是重试没做幂等,运维手动重跑时系统提交了两次。

这三个问题分别对应后面的三节:断点、状态、幂等。

四、概念拆解:状态、节点、边,各自的反例 ​

先给三个定义。

状态(State)是一次运行的全部可变数据,通常是一个带类型声明的字典。反例是把状态藏在各个节点的局部变量里——这样你既没法检查点,也没法在断点恢复后还原现场。

节点(Node)是一个纯函数:读状态,返回对状态的增量更新。反例是节点里做网络请求却不记录结果——重跑时又打一次,副作用重复。

边(Edge)决定下一个节点是谁,分固定边和条件边。反例是把所有分支都塞进一个节点内部用 if-else 写死——那样图就失去了可视化,也失去了按节点设置重试策略的能力。

一个最小可跑的骨架长这样:

python
from typing import TypedDict, Literal
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver

class Claim(TypedDict):
    doc_id: str
    amount: int | None
    over_limit: bool | None
    approved: bool | None

def extract(state: Claim) -> dict:
    # 真实实现调 OCR + 抽取模型;这里用固定值演示
    return {"amount": 3800}

def judge(state: Claim) -> dict:
    return {"over_limit": (state["amount"] or 0) > 2000}

def route(state: Claim) -> Literal["need_approval", "submit"]:
    return "need_approval" if state["over_limit"] else "submit"

def need_approval(state: Claim) -> dict:
    return {"approved": None}   # 真正的人审在断点里做

builder = StateGraph(Claim)
builder.add_node("extract", extract)
builder.add_node("judge", judge)
builder.add_node("need_approval", need_approval)
builder.add_edge(START, "extract")
builder.add_edge("extract", "judge")
builder.add_conditional_edges("judge", route)
builder.add_edge("need_approval", END)
graph = builder.compile(checkpointer=InMemorySaver())

# 运行结果
out = graph.invoke({"doc_id": "BX-2026-1116-07", "amount": None,
                    "over_limit": None, "approved": None},
                   config={"configurable": {"thread_id": "BX-2026-1116-07"}})
print(out)
# {'doc_id': 'BX-2026-1116-07', 'amount': 3800, 'over_limit': True, 'approved': None}

注意 checkpointer=InMemorySaver() 这一行。没有它,图跑完就什么都不剩,后面所有关于断点和恢复的能力都不存在。

五、人在回路:断点的语义比位置重要 ​

LangGraph 的 interrupt() 用法很简单:在节点里调它,传一个可 JSON 序列化的载荷,执行就停在那里,状态被检查点保存,等你用 Command(resume=...) 把它唤醒,传进去的值成为 interrupt() 的返回值。

这里有一个必须提前知道的行为,我第一次踩到时以为是自己写错了:恢复时,包含 interrupt() 的那个节点会从头重新执行,也就是 interrupt() 之前的所有代码会再跑一遍。所以断点前面不能放有副作用的操作——你要是把「扣库存」写在 interrupt() 上面,每次人审完就多扣一次。

正确的位置是:把断点放在动作之前,让「决定」和「执行」分在两个节点里。

python
from langgraph.types import interrupt, Command

def request_approval(state: Claim) -> dict:
    decision = interrupt({
        "type": "approval",
        "doc_id": state["doc_id"],
        "amount": state["amount"],
        "question": "金额超过限额,是否通过?",
    })
    return {"approved": bool(decision)}

# 第一次 invoke 会停在断点;人审完带上答案再调一次同一个 thread_id
graph.invoke(Command(resume=True),
             config={"configurable": {"thread_id": "BX-2026-1116-07"}})

thread_id 是恢复的指针,复用同一个值就是续跑同一份状态,换个新值就是从零开始。这一点决定了你怎么设计会话:一个业务单号对应一个 thread_id,是最省心的做法。

六、失败恢复与幂等:只能做到至少一次 ​

这是整节最容易被低估的一节。

LangGraph 的 RetryPolicy 默认 max_attempts=3、initial_interval=0.5 秒、backoff_factor=2.0、jitter=True,默认只对特定异常重试,HTTP 库的异常只在 5xx 时重试。参数好办,语义难办。

官方文档写得很直白:重试会从头的重新执行整个节点函数,这带来的是至少一次(at-least-once)语义,不是恰好一次。它不会让外部副作用只发生一次。

关键在于检查点写在超步(super-step)边界,不在函数中间。节点中途失败,这一轮的图内写入会被丢弃;但节点内部已经发生的副作用——扣款、发邮件、写外部系统——在边界之外,没人帮你回滚。

所以有副作用的地方必须自带幂等键,而且这个键必须在副作用发生之前就已经是持久的:

python
def charge(state: Claim) -> dict:
    # 错误示范:在节点内生成再返回
    # key = str(uuid.uuid4())   -> 节点没跑完就不会被检查点记住,
    #                              重试时生成的是另一个 key,扣两次
    key = f"charge:{state['doc_id']}"   # 从已经持久化的状态推导
    payment.charge(amount=state["amount"], idempotency_key=key)
    return {"charged": True}

这段代码里有个细节值得停一下:注释掉的那行是很多人第一版会写的。它看起来完全合理,因为 key 确实唯一;问题在于这个唯一值是「这一次尝试」的唯一值,不是「这一笔业务」的唯一值。重试就是新的一次尝试。

如果你的业务里找不到天然的持久化标识,官方给的办法是:单独用一个节点把生成的 key 写进状态,再执行副作用,并且把 durability 设成 sync——同步落盘之后下一步才开始,中间崩溃也不会丢。三种 durability 模式的差别是:exit 只在结束时持久化,性能最好但中途崩溃无法恢复;async 异步写,性能好但有极小概率丢检查点;sync 同步写,最稳也最慢。

七、成本控制:三个能立刻收紧的旋钮 ​

第一是轮次上限。ReAct 循环必须有一个硬上限,我们的默认是 8 轮,超过就走兜底。没有上限的循环在遇到「工具一直返回空结果」时能烧掉你一整天的预算。

第二是工具输出截断。一次检索回来 20 条、每条 800 字,第二轮上下文就爆了。我们统一在工具层截到 400 字并附上原文 id,模型需要细节再按 id 取。

第三是路由降级。分类、抽取这类确定性高的节点用小模型,规划和反思用大模型。这一条听起来像废话,实际做的时候很少人真的去分。我们分了之后,单次任务成本降了大约四成,质量上没有可感知的差异。

反过来给一条明确的否定判断:不建议给 Agent 加「无限反思」来兜底质量。Reflexion 那套在原论文里之所以有效,前提是有外部验收信号——单元测试过没过、编译器报没报错。业务场景里没有这种信号时,反思会退化成一堆自我批评的形容词,既改不动结果,还每一轮都在烧钱。我们给反思节点设的上限是两轮,第三轮必须人工介入,这数字没有理论依据,纯粹被账单逼出来的。

八、三个我一开始也想错了的地方 ​

很多人以为 ReAct 是默认最优解。实际上它的成本最高、最不可预测,凡是路径能写死的任务,用固定编排又快又稳。

后两条我是在事故复盘会上被问住的,不是读书读出来的。

很多人以为加了检查点就能断点续跑。实际上还得有稳定的 thread_id 和持久化的 checkpointer(内存版进程一停就没了),缺一个都不成立。

很多人以为重试是安全的。实际上它给的是至少一次语义,副作用必须自己保证幂等,框架不替你做。

九、八个词先钉住,后面才谈得下去 ​

这张表可以当速查用,面试和方案评审里被追问的通常就是这几个词。

术语英文一句话解释
反应式循环ReAct思考与行动交替,每步由模型决策
计划执行Plan-Execute先产出完整计划,再逐步执行
反思Reflection用语言总结失败,存入记忆影响下一轮
状态图StateGraph用节点和边表达流程,状态显式传递
检查点checkpointer在超步边界持久化状态,支持恢复
断点interrupt暂停执行等人输入,恢复时重跑所在节点
至少一次at-least-once重试保证执行一次以上,副作用需自行去重
持久化级别durabilityexit/async/sync 三档,决定崩溃能恢复多少

十、把这张图搬回你们系统之前 ​

动手两件:把上面的报销图加一个 submit 节点,要求它在断点通过后才执行,并验证重复调用不会提交两次;把 InMemorySaver 换成持久化 checkpointer,杀掉进程再从同一个 thread_id 恢复,看状态是否完整。

这两件事做完,你大概会发现第二件比想象中麻烦:持久化 checkpointer 要一个真实的数据库,而 thread_id 的设计一旦和你现有的业务主键不一致,恢复时就会出现「状态在、业务单号对不上」的尴尬。我们的做法是让 thread_id 直接等于业务单号,代价是同一个业务单号无法并发跑两个流程——这个限制当时没写进设计文档,是上线后一个重试事故教会我的。

想清楚三件:你们哪个流程现在缺一个断点?如果那个断点加了,重跑时会多做几次什么?兜底路径长什么样,谁来看它?

最后一件我没法替你判断的:这套东西的复杂度值不值。状态图、检查点、断点、幂等键,四样加起来是一笔不小的工程投入,而如果你的流程只有三步、失败重跑一次就能接受,硬上状态图纯属自找麻烦。判断依据是「一次失败的人工补救成本」——超过半小时的,值得上;五分钟能手工补的,写个 for 循环就够了。