高级 📋 6 个步骤 第 632 / 632 篇

LangGraph 1.2.20 的 strict resume 实操:把人工审批改成不可重放的一次性答复

页面重试、双击确认、脚本重跑都可能把同一份审批答复投两次。LangGraph 1.2.20 给同一任务里的每次 interrupt() 独立 id,并新增 strict resume,对未知或已消费的答复直接抛 UnknownInterruptError。本教程用一张不需要模型的最小审批图六步复现:挂起取 id、重放旧行为、打开严格模式、按 id 作答、跑出三类拒绝、最后把一次性票据写进服务层。

2026.11.18· 12 分钟上手· 约 3883 字· 🕸️ LangGraph / ✅ strict resume

人工审批最容易出错的地方,不是「没人点同意」,而是同一个同意被用了两次:页面重试、双开标签页、用户点了返回再点一次,后端拿着一个已经消费过的答复继续往下跑,图早就换到下一个问题上了。LangGraph 1.2.20(2026-11-05)专门修这一类问题——同一个任务里的每次 interrupt() 有了自己的 id,并新增一个 strict resume 模式,不认识或已用过的答复会被直接拒绝,而不是静默忽略。

🧩 适合谁:用 LangGraph 做「跑之前先让人确认」的开发者——部署、退款、改数据库、发邮件这类不可逆动作。前置准备:Python 3.10 以上、一个虚拟环境、pip install langgraph==1.2.22。本篇不需要任何模型 API Key:节点全是确定性函数,全部行为可以在本机复现,这对排查审批问题反而更合适。

四条边界先记住:① strict 模式只在根图生效,嵌套子图继承配置但不会独立再校验;② 走远程图时这个配置键会在序列化前被丢弃(_sanitize_config 的黑名单),所以远程部署要另行验证;③ 同一节点里连续调用两次 interrupt(),两次可能拿到同一个 id,别把 id 当成「这是第几个问题」的指纹;④ 严格模式拒绝的是「过期答复」,它不是授权系统,谁有权限点同意仍需你自己判。

先弄清:interrupt、checkpoint、resume 三件套怎么配合

把这三个概念摆清楚,后面的报错才不会看错对象。关键的一点常被忽略:节点恢复时是从函数第一行重新执行的,不是像协程那样从挂起的那一行继续。

环节发生了什么对代码的要求
执行到 interrupt(payload)图挂起,checkpoint 保存状态,payload 与 id 通过 get_state().interrupts 暴露给调用方payload 要能独立看懂,别依赖外部变量
人做决定你的界面记录「针对哪个 id、做了什么决定、谁点的、什么时候」这一步在 LangGraph 之外,必须自己存
恢复用同一 thread 提交 Command(resume=...)节点从第一行重跑,interrupt() 的返回值变成你给的答复
副作用重跑意味着 interrupt() 之前的代码会再执行一次发消息、扣款这类动作必须幂等或挪到挂起之后
💡 所以「审批前先发一封通知邮件」这种写法要小心:节点恢复时会再发一次。把副作用放到审批之后的节点,或者用幂等键去重。

Step 1:装版本,建一张最小的审批图

1 三十行代码,一个挂起点

先不要接模型。一个 review 节点加一个 apply 节点,就足够复现所有边界行为;等逻辑跑通,再把 review 换成「让模型生成摘要给人看」。

# approval_graph.py
from typing import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.types import interrupt, Command
from langgraph.checkpoint.memory import MemorySaver

class S(TypedDict, total=False):
    request: str
    decision: str
    applied: bool

def review(state: S):
    # 第一次执行到这里就挂起,payload 交给调用方展示给人
    verdict = interrupt({"ask": "是否批准这次发布?", "target": state["request"]})
    return {"decision": verdict}

def apply(state: S):
    # 真正的副作用放这里,避免在 review 里重复执行
    return {"applied": True}

builder = StateGraph(S)
builder.add_node("review", review)
builder.add_node("apply", apply)
builder.add_edge(START, "review")
builder.add_edge("review", "apply")
builder.add_edge("apply", END)

graph = builder.compile(checkpointer=MemorySaver())
# run_once.py
from approval_graph import graph

cfg = {"configurable": {"thread_id": "deploy-1"}}
out = graph.invoke({"request": "release v1.2.3"}, cfg)
print(out)                       # 输出里带 __interrupt__
state = graph.get_state(cfg)
for i in state.interrupts:
    print(i.id, i.value)         # 32 位十六进制 id + payload
💡 thread_id 是恢复时的定位键。同一个 thread 才能接着上次的 checkpoint 走;换一个 id 就是一张全新的图,这也是「多标签页互相打架」的根源——它们共用同一个 thread。

Step 2:先复现旧行为,看清「重放为什么能过」

2 同一份答复发两次,1.2.19 及以前不会拦

在不开严格模式的默认状态下,指向不存在或已消费中断的 map,会被静默接受。这不算 bug,而是历史的宽松语义:图只要拿到能用的答复就继续。

# replay.py
from langgraph.types import Command
from approval_graph import graph

cfg = {"configurable": {"thread_id": "deploy-1"}}
graph.invoke({"request": "release v1.2.3"}, cfg)

card = graph.get_state(cfg).interrupts[0]

# 第一次:正常批准
print(graph.invoke(Command(resume={card.id: "approve"}), cfg))

# 第二次:把同一张票据再投一次(模拟页面重试)
print(graph.invoke(Command(resume={card.id: "approve"}), cfg))   # 不报错

这就是真实事故的形状:前端超时重试、用户双击、脚本重跑,都会把同一份答复再投一次。图的语义是「继续」,于是第二次调用可能落到下一个挂起点上,用旧问题的答案回答了新问题。要拦住它,需要的是「这个 id 现在是不是还在等待」的校验,而不是更严的提示词。

Step 3:打开严格模式,只需要一个 config 键

3 在 configurable 里加一行

严格模式通过配置键启用,不需要改节点代码、也不新增公开参数。键名是库里的常量 CONFIG_KEY_STRICT_RESUME,字符串值是 __pregel_strict_resume。

# strict.py
cfg = {
    "configurable": {
        "thread_id": "deploy-1",
        "__pregel_strict_resume": True,   # 打开严格恢复
    }
}
graph.invoke({"request": "release v1.2.3"}, cfg)
条件严格校验是否生效说明
根图 + 该键为 True生效推荐用法
嵌套子图不再独立校验继承父级配置,只由根图把关
checkpoint 已被后续写入取代跳过校验重放已完成任务时属于预期行为
经远程图调用该键被丢弃序列化前清洗,远程侧不会收到

这是内部配置键,不是稳定 API。它出现在库的常量里而不是公开文档的示例里,升级小版本时应把它当作「需要回归验证的行为」而不是「写一次长期有效」。上线前把这张表的四行都跑一遍,比读 changelog 更可靠。

Step 4:改成按 id 答复,从 pending 列表里取

4 不要缓存 id,每轮现取

严格模式要判断「这个 id 还在不在等」,所以答复必须写成 map 形式:键是中断 id,值是你的决定。map 形式的键要求是 32 位十六进制摘要,正好就是 interrupts 里给出的 id。

# approve_by_id.py
from langgraph.types import Command
from approval_graph import graph

cfg = {
    "configurable": {
        "thread_id": "deploy-1",
        "__pregel_strict_resume": True,
    }
}
graph.invoke({"request": "release v1.2.3"}, cfg)

state = graph.get_state(cfg)
pending = {i.id: i for i in state.interrupts}
print("待答复:", list(pending))

# 真正的审批:只对当前 pending 的 id 作答
target_id = next(iter(pending))
out = graph.invoke(Command(resume={target_id: "approve"}), cfg)
print(out)
💡 界面层把「问题文本 + id」一起渲染给审批人,回调时带上 id 回传。这样即使同时挂着三个问题,也不会张冠李戴;同时挂多个问题时,单值答复会被判为歧义,必须逐 id 作答。

Step 5:把三类拒绝逐个跑出来,确认它们真的发生

5 三种 reason,对应三种界面提示

拒绝时抛的是 UnknownInterruptError,带三个字段:reason、interrupt_ids(不处于等待的 id)、pending_ids(仍在等待的 id)。用它就能在前端给出「这条审批已失效,请刷新后重试」这种可操作的提示。

# refusals.py
from langgraph.types import Command
from langgraph.errors import UnknownInterruptError
from approval_graph import graph

def probe(label, payload, cfg):
    try:
        graph.invoke(Command(resume=payload), cfg)
        print(label, "-> 通过")
    except UnknownInterruptError as e:
        print(label, "-> 拒绝:", e.reason, e.interrupt_ids, e.pending_ids)

# 场景一:随便编一个 32 位 id(等价于已消费的旧票据)
probe("unknown-id", {"0" * 32: "approve"}, cfg)

# 场景二:空 map
probe("empty-map", {}, cfg)

# 场景三:同时挂着多个问题时只给单值
probe("ambiguous", "approve", cfg)
场景reason非严格模式下的旧行为
map 里带未知或已消费的 idnot_pending静默接受
提交空 mapempty_map静默接受
有多个 pending 却只给一个值ambiguous抛普通 RuntimeError

还有一条容易误解的规则:当没有任何 pending 中断时,传单个值是合法的,用来恢复那些停在静态断点(interrupt_before / interrupt_after)上的图。所以「单值一律禁止」是错的,别在网关层做这种一刀切校验。

更贴近真实业务的是「同时挂两个审批」:一条分支等发布批准,另一条分支等预算批准。这种图在严格模式下必须一次性把两个 id 都答完,只给一个会直接命中歧义拒绝。

# two_gates.py
from langgraph.graph import StateGraph, START, END
from langgraph.types import interrupt, Command
from langgraph.checkpoint.memory import MemorySaver

def release_gate(state):
    return {"release_ok": interrupt("批准发布?")}

def budget_gate(state):
    return {"budget_ok": interrupt("批准预算?")}

b = StateGraph(dict)
b.add_node("release", release_gate)
b.add_node("budget", budget_gate)
b.add_edge(START, "release")
b.add_edge(START, "budget")     # 两个分支并行,各自挂起
b.add_edge(["release", "budget"], END)
graph2 = b.compile(checkpointer=MemorySaver())

cfg2 = {"configurable": {"thread_id": "ship-9",
                         "__pregel_strict_resume": True}}
graph2.invoke({}, cfg2)

ids = {i.value: i.id for i in graph2.get_state(cfg2).interrupts}
print(ids)                       # 两个问题,两个 id

# 一次调用同时答复两个;缺一个就会被判为歧义
graph2.invoke(Command(resume={ids["批准发布?"]: "yes",
                              ids["批准预算?"]: "no"}), cfg2)
💡 界面层可以用这段代码做自检:只要 len(pending) > 1,就禁用「一键全部同意」按钮,强制逐个确认。审批面板里两个问题挨在一起时,人眼很容易点错,这比后端拦截更早生效。

四条结构上的约定,能让你少踩大部分坑。它们不是框架强制要求,而是从「节点会从第一行重跑」这个事实推出来的:

约定原因违反后的表现
审批单独成节点恢复时整节点重跑,混着业务逻辑会重复执行审批通过后通知发两次、库存扣两次
副作用放在审批之后挂起前执行的代码无法回滚拒绝之后系统状态已被改过
payload 自带上下文审批人要能只看 payload 就做决定界面得反查数据库才能渲染,容易看到旧值
一个 thread 一次只推进一件事并发答复同一 thread 容易互相覆盖两个审批人同时点,后到的覆盖先到的
💡 拒绝发生在任何写入之前,pending 中断仍然可以继续回答。也就是说重试是安全的:用户看到「审批已失效」后刷新拿到新 id,再点一次就能正常推进,不会把图搞坏。

Step 6:收口到服务层,把「一次性」写进流程

6 图只负责拒绝,票据要你自己管

严格模式解决的是「答复与 pending 不匹配」,剩下的三件事必须由服务层承担:谁能批、批的是哪一个动作、这条决定留痕在哪。下面这段可以当作最小实现。

# approvals.py
import time, uuid

# 审批票据:interrupt_id -> 票据(一次性核销)
TICKETS = {}

def issue_ticket(thread_id, interrupt_id, action, actor):
    TICKETS[(thread_id, interrupt_id)] = {
        "ticket": uuid.uuid4().hex,
        "action": action,          # 与 payload 里的目标动作绑定
        "actor": actor,
        "issued_at": time.time(),
        "used": False,
    }

def redeem(thread_id, interrupt_id, actor):
    item = TICKETS.get((thread_id, interrupt_id))
    if not item:
        raise PermissionError("没有对应票据")
    if item["used"]:
        raise PermissionError("票据已核销")
    if item["actor"] != actor:
        raise PermissionError("票据不属于当前审批人")
    item["used"] = True            # 先核销再提交,失败也不复用
    return item

# 调用侧:先核销,再由严格模式兜底
item = redeem("deploy-1", target_id, "alice")
graph.invoke(Command(resume={target_id: "approve"}), cfg)
职责放哪为什么
答复是否属于当前 pendingLangGraph(strict resume)只有图知道挂起状态
票据是否已核销、是否本人你的服务层图不认人,也不存业务票据
审批对象是否被篡改服务层把 action 写进票据并与 payload 比对防止「换了目标沿用旧同意」
审计留痕持久化表 + 日志事后追责与复盘
💡 顺序建议:先落库「票据已核销 + 决定 + 操作人」,再调用图恢复。这样即使恢复失败,你也能看到「有人批过但没推进」,而不是既没推进也没记录。

升级时还有一处代码要改:UnknownInterruptError 不是 RuntimeError 的子类,老代码里那个 except RuntimeError 拦不住它。上线前把捕获顺序调好,否则用户看到的是 500 而不是「审批已失效」。

# errors_to_http.py
from langgraph.errors import UnknownInterruptError

def resume_or_explain(graph, payload, cfg):
    try:
        return graph.invoke(Command(resume=payload), cfg)
    except UnknownInterruptError as e:
        # 先捕获具体异常,再捕获兜底
        if e.reason == "not_pending":
            return {"code": 409, "msg": "这条审批已失效,请刷新后重新确认",
                    "pending": list(e.pending_ids)}
        if e.reason == "empty_map":
            return {"code": 400, "msg": "没有提交任何决定"}
        return {"code": 409, "msg": "有多个待审批项,请逐项确认",
                "pending": list(e.pending_ids)}
    except RuntimeError as e:
        return {"code": 409, "msg": str(e)}

上线后要盯的指标不多,但每一条都对应一种真实故障。把它们接到现有监控里,比事后翻日志有效:

指标异常信号可能是哪里坏了
not_pending 拒绝率突然升高前端在重试,或票据没核销就复用
ambiguous 拒绝数持续大于 0界面没做逐项确认,仍在提交单值
挂起时长长尾很长没人认领审批,需要加提醒或超时策略
票据核销与实际推进的差值差值持续扩大核销后恢复失败,属于要立刻查的漏推进

做到哪一步算成功

检查项期望现象对应步骤
能挂起首次 invoke 返回 __interrupt__,get_state().interrupts 有 id 与 payloadStep 1
旧行为可复现不开严格模式时,重复投同一 id 不报错Step 2
严格模式生效同样操作抛 UnknownInterruptError,reason=not_pendingStep 3、5
按 id 可推进用当前 pending 的 id 作答,图继续走到 applyStep 4
三类拒绝齐全unknown-id、empty-map、ambiguous 分别命中三种 reasonStep 5
服务层兜底同一票据第二次核销被拒,且日志有记录Step 6
🎉 做完这一套,你的审批从「点一下就可能被重放」变成「一条答复只能用一次、用错了会被图拒绝、用过没用过都有账」。这才是可以放到生产环境的确认环节。

常见问题速查

现象大概率原因与处理
加了键但没生效键放错了层级(要在 configurable 里)、拼写不符,或当前是嵌套子图;用根图配置再试
远程部署后拦不住重放该键在远程调用的配置清洗中被丢弃;远程侧要单独验证,或把校验前移到你的网关
同一节点两次 interrupt 的 id 一样符合当前实现;判断「是否同一个问题」要用 payload,不要用 id
提交单值报「multiple pending interrupts」同时挂了多个问题,必须按 id 逐个答复;没有 pending 时单值才合法
报错后图坏了不会:校验发生在写入前,pending 仍可继续回答;刷新拿新 id 重试即可
节点恢复后重复发通知恢复是从节点第一行重跑;把副作用移到挂起之后,或用幂等键去重
升级到更高小版本后行为变化把 Step 3 的四行条件表当回归清单跑一遍,别只看 release note 标题
想要「谁能批」的强约束严格模式不做授权;在服务层用票据 + 角色校验,图只负责状态一致性
📌 配套阅读:本中心《LangGraph interrupt() 新增 responseSchema》讲的是挂起载荷的结构化约束,本篇讲的是答复侧的一次性校验;一个管「问什么」,一个管「答得对不对、还能不能用」。
← 返回教程中心