LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

NNathaniel bigo··原创首发·AI 辅助撰写
8 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

  1. 新版官方首选方案是在节点函数内部调用 interrupt(待审数据),配合 Command(resume=人工结果) 恢复运行,比早期静态写死 interrupt_before 灵活得多。
  2. 暂停期间不占后台算力:一旦撞上 interrupt(),进程直接保存状态并正常返回响应;哪怕主管三天后才在网页点同意,只要带上原 thread_id 就能原地唤醒。
  3. 少了这两样必定报错:编译图时必须传 checkpointer(保存器),且每次调用必须传 config={"configurable": {"thread_id": "..."}}。
  4. 最重要的一条底层铁律:恢复时被暂停的节点会从该函数的第一行重新执行(只是这次遇到 interrupt() 不再停住,而是直接吐出人工传入的 resume 值)——所以发请求、扣款等副作用代码绝不能写在同一个节点里 interrupt() 的上方。

LangGraph 人工审批暂停与恢复四步

图:本站根据 LangGraph 官方文档 Human-in-the-loop 整理的示意图

本文根据 LangChain / LangGraph 官方文档《Human-in-the-loop》《Interrupts》整理,核对日期 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 LangChain 官方网站。

适用于谁

  • 搜「langgraph human in the loop」「langgraph interrupt 用法」「langgraph 人工审批」的开发者;
  • 智能体已经能调写库、发邮件或退款工具了,但上线前安全团队要求「凡是写操作必须先暂停给主管点确认按钮,同意后才能真执行」的后端工程师;
  • 照着文档写了 interrupt(),恢复时却发现节点上半截的逻辑又重复跑了一遍、正在查原因的人。

如果你是第一次接触状态图,建议先花五分钟读完 /guides/langgraph-quickstart-install-first-graph;为什么这类跨天审批场景适合用图编排,也可回顾 /guides/claude-agent-sdk-vs-langchain-how-to-choose。

一、完整可运行示例:高危操作执行前暂停等人工确认

下面的纯 Python 脚本模拟了一个「执行工单补偿发放」节点:当补偿积分超过免审线时,调用 interrupt() 把待审详情抛给外部调用方;等拿到人类返回的 "approve" 或修改后的数值后,再真正落库完成。

python
from typing import TypedDict
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import StateGraph, START, END
from langgraph.types import interrupt, Command

class TicketState(TypedDict):
    user_id: str
    points: int
    status: str

def issue_compensation_node(state: TicketState):
    pts = state["points"]
    # 超过 500 积分时触发动态人工挂起,把待审摘要抛出去
    if pts > 500:
        decision = interrupt({
            "question": "积分补偿超免审线,请确认是否批准或修改额度",
            "user_id": state["user_id"],
            "proposed_points": pts,
        })
        if not decision.get("approved"):
            return {"status": "人工已驳回该笔发放"}
        # 允许审批人顺手改小发放数值后再放行
        pts = decision.get("final_points", pts)

    # 注意:真正落库发积分的写操作必须放在 interrupt 之后
    return {
        "points": pts,
        "status": f"已向用户 {state['user_id']} 成功发放 {pts} 积分",
    }

builder = StateGraph(TicketState)
builder.add_node("issue_compensation", issue_compensation_node)
builder.add_edge(START, "issue_compensation")
builder.add_edge("issue_compensation", END)

# 必须挂载检查点保存器(生产环境换成 PostgresSaver)
graph = builder.compile(checkpointer=InMemorySaver())

if __name__ == "__main__":
    cfg = {"configurable": {"thread_id": "ticket-9001"}}

    # 第一次调用:跑到 interrupt 处自动停住并返回 __interrupt__ 提示
    first_out = graph.invoke(
        {"user_id": "U_88", "points": 1200, "status": "pending"},
        config=cfg,
    )
    print("首次返回(已挂起):", first_out["__interrupt__"])

    # 模拟后台主管审批同意并将额度调整为 800 后恢复同一个 thread_id
    final_out = graph.invoke(
        Command(resume={"approved": True, "final_points": 800}),
        config=cfg,
    )
    print("恢复后最终结果:", final_out["status"])

运行这段代码,你会看到第一次 invoke 并没有执行下方的发放逻辑,而是返回了一个包含 __interrupt__ 列表的字典——你的前端页面只需读取里面的 question 和 proposed_points 渲染成审批弹窗;等主管点击按钮后,后端接口调用第二次 graph.invoke(Command(resume=...), config=cfg) 即可跑完剩余流程。

使用 interrupt 必防的三个踩坑点

图:本站根据 LangGraph 官方文档 Interrupts 规范 整理的示意图

二、生产环境写 interrupt 必守的三条工程纪律

  1. 把耗时大模型调用拆到前一个独立节点:因为恢复时当前节点会从头重跑一遍,如果你把「调大模型想方案」和「interrupt() 等人工点同意」塞在同一个函数里,点同意恢复时那次大模型调用又会被白跑一次浪费额度。正确拆法是:节点 A 调大模型生成待审参数写入 State → 节点 B 专职调 interrupt() 拿审批结果并执行工具;
  2. 生产库务必替换掉 InMemorySaver:人工审批往往间隔几十分钟甚至跨天,内存保存器遇到服务发版重启就会丢掉挂起线程,上线前请换成 PostgreSQL 等持久化保存器;
  3. 配合远程 MCP 高危写工具一起用:当你通过适配器挂载了外部业务系统的增删改 MCP 工具(见 /guides/langgraph-mcp-integration-guide)时,不要把删除或群发工具裸露在全自动 ToolNode 里,给高危工具外包一层带 interrupt() 的人工确认壳最稳妥。开发期想直观模拟断点恢复,也可以直接在本地 Studio 画布里点按钮测试(见 /guides/langgraph-debug-visualize-studio-guide)。

平时研发团队借助 Claude 或 ChatGPT 梳理复杂审批状态转移边界与编写异步回调接口时,个人官方订阅说明也可参考 /chongzhi/claude-pro。

常见问题

Q:如果用户挂起后一直不点审批,怎么查询这个 thread_id 当前是不是正卡在等待人工状态?

随时调用 state_snapshot = graph.get_state(cfg) 检查返回的快照对象:如果里面的 tasks 包含未处理的 interrupts(或 next 非空),就说明该会话当前正停在人工断点处,前端刷新页面时靠这个接口就能重新渲染出刚才的待办卡片。

Q:旧项目里用的 compile(interrupt_before=["tools"]) 还能继续用吗?

依然兼容保留。如果你的需求非常简单——只要每次进工具节点前无脑一刀切停住,静态 interrupt_before 写起来很省事;但只要你需要「小额免审、大额才停」这类按业务字段动态判断是否挂起的逻辑,函数内的 interrupt() 清晰得多。

相关教程

参考资料

  • LangChain / LangGraph 官方文档:Human-in-the-loop & Interrupts — https://docs.langchain.com/
  • langchain-ai/langgraph 官方 GitHub 仓库 — https://github.com/langchain-ai/langgraph

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  5. 05

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0
  6. 06

    MCP 收费吗:开源协议免费边界、第三方 API 账单与隐形 Token 开销说明

    搜「mcp 收费 吗」的人常担心装多了插件会被扣费。MCP(模型上下文协议)本身和官方 SDK 采用 MIT 协议完全免费;实际使用中可能产生费用的只有两处:挂载过多工具占用的大模型上下文 Token,以及部分外部商业数据源自带的 API 套餐。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    MCP 协议最新版本更新了什么:无状态架构、OAuth 2.1、结构化输出与异步 Tasks 详解

    搜「mcp 重大 更新」「mcp 协议 更新」想补齐规范演进脉络?本文对照 modelcontextprotocol.io 官方规范更新日志,梳理从 Streamable HTTP 到无状态优先架构、OAuth 2.1 资源服务器、Elicitation 交互补参与异步 Tasks 扩展的核心变化。

    Claude其他 AI 工具0
  2. 02

    A2A 和 MCP 有什么区别:工具连接协议与智能体通信协议的边界和配合

    很多人问「有了 MCP 为什么还要出 A2A,两者是不是二选一的竞争关系」。两份官方规范都明确写明它们是上下互补关系:MCP 负责给单个智能体挂载工具与数据源,A2A 负责让多个独立黑盒智能体跨团队、跨框架互相派单协作。

    Claude其他 AI 工具0
  3. 03

    A2A 协议是什么、怎么用:Agent2Agent 智能体互联规范、名片发现与 Python 接入流程

    A2A(Agent2Agent)是由 Google 发起并移交 Linux 基金会托管的开放智能体通信协议,用来让不同团队、不同框架开发的独立智能体跨网络互相派单协作。本文按官方规范讲清 Agent Card、Task 状态机与 Python SDK 接入步骤。

    Gemini其他 AI 工具0
  4. 04

    AutoGen 现在怎么样了?微软官方演进路线与 Microsoft Agent Framework 入门

    搜 AutoGen 新教程常被 0.2、0.4、社区分支和 Semantic Kernel 绕晕。按微软官方文档,微软已将 AutoGen 与 Semantic Kernel 两支团队合并推出统一的开源框架 Microsoft Agent Framework。本文讲清现状与 Python 快速上手。

    ChatGPT其他 AI 工具0
  5. 05

    CrewAI 多轮对话与记忆怎么配:memory=True 三层记忆、人工介入与 Flows 状态持久化

    刚用上 CrewAI 的人常疑惑 kickoff 跑完就结束,怎么做多轮连续对话与跨次记忆。本文按官方文档拆解 memory=True 的短期/长期/实体三层记忆、嵌入模型配置,以及用 Flows 状态流和 @persist 搭建多轮会话的实战写法。

    其他 AI 工具0
  6. 06

    CrewAI 入门教程:Agent 角色、Task 任务、执行流程(Process)与第一个团队示例

    CrewAI 是主打「拟人化角色分工」的 Python 多智能体开源框架。本文按官方文档讲清安装要求、Agent(角色/目标/背景)、Task(任务描述与预期输出)和 Process(顺序接力与经理层级模式)的配合逻辑,并给出最小可运行代码。

    其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~