在客户现场部署 Agent,最难的是谁来点“批准”
LangGraph 的 interrupt 能在退款发出前暂停 Agent,等人审批几分钟甚至一整夜,再从原处继续。
要点速览
- interrupt 函数在指定位置暂停图,等待外部输入,并通过 Command(resume=...) 接收审批决定。
- interrupt 必须配合 checkpointer,生产环境需要持久化的 checkpointer;thread_id 决定是继续已有线程还是新开一个线程。
- 恢复时节点会从头重新运行,所以所有非幂等操作都必须放在 interrupt 之后。
设想这样一个场景:你为客户部署的 Agent 已经拟好一笔退款,只差一步就要发出。客户那边的负责人希望在钱离开账户之前亲自审核。这可能只要几分钟,也可能要等到第二天早上。
LangChain 团队在 2024 年 12 月 14 日的官方博客中把原因说得很直白:Agent 可以很强大,但并不完美。LangGraph 的 interrupt 函数正是由此而来,据 LangChain 团队介绍,它从设计之初就面向生产环境。
对前线部署工程师(FDE)来说,这不是一个无关紧要的技术细节。当 Agent 会动到客户的钱或线上系统时,应该从一开始就设计好让人喊“停”的位置,而不是等客户提出来再补。
LangGraph 是什么,不是什么
LangGraph 对自己的定位是:一个底层编排框架,用于构建、管理和部署有状态、长时间运行的 Agent。它由 LangChain 背后的团队 LangChain Inc 开发,但不依赖 LangChain 也能使用。代码采用 MIT 许可证发布。
“底层”二字值得细读。LangGraph 不会直接给你一个现成的 Agent,而是提供自己组装 Agent 的零件:由步骤组成的图、在各步骤间流转的状态,以及可以停下来的位置。
开发者着重强调两点好处。一是持久执行(durable execution):Agent 能扛住故障,可以长时间运行。二是人在回路(human-in-the-loop):运行过程中的任何时刻,都可以查看和修改 Agent 的状态。
一个暂停点,三个组件
根据官方文档,interrupt 可以让图在特定位置暂停,等待外部输入后再继续。暂停就需要有地方保存状态,因此文档要求必须配置 checkpointer,并建议生产环境使用持久化的 checkpointer。
checkpointer 把每个线程的状态保存为检查点(checkpoint)。同一套机制支撑多种用途:对话记忆、人在回路、时间回溯和容错。第三个组件是 thread_id。沿用已有的值,就从对应的检查点继续;换一个新值,则会开启一个状态为空的全新线程。
那么审核人的决定怎么传进来?传给 Command(resume=...) 的内容,就是 interrupt 调用本身的返回值。在节点内部看,interrupt 就像一次普通的函数调用:调用它,它等待,返回的就是审核人的决定。
一个最小的审批节点
文档指出,interrupt 最常见的用法是在关键操作前暂停并请求批准。下面是一个可运行的示例:只有一个节点的图,配一个内存 checkpointer。第一次调用停在 interrupt;第二次用同一个 thread_id 恢复执行。标识符含义如下:amount 是金额,result 是结果,approve_refund 是“批准退款”,execute_refund 是“执行退款”,decision 是决定,approve 是“批准”。
from typing import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import interrupt, Command
class State(TypedDict):
amount: int
result: str
def execute_refund(state):
print("已退款:", state["amount"])
def approve_refund(state: State):
decision = interrupt({
"action": "refund",
"amount": state["amount"],
})
if decision == "approve":
execute_refund(state) # 只在批准之后才执行
return {"result": decision}
builder = StateGraph(State)
builder.add_node("approve_refund", approve_refund)
builder.add_edge(START, "approve_refund")
builder.add_edge("approve_refund", END)
# InMemorySaver 只适合本地试用;生产环境需要持久化的 checkpointer
graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "refund-request-001"}}
# 第一次运行:图停在 interrupt,状态按 thread_id 保存
result = graph.invoke({"amount": 100}, config=config)
print(result["__interrupt__"]) # 等待审核人处理的 payload
# 审核人点击按钮后,用同一个 config(同一个 thread_id)再次调用
graph.invoke(Command(resume="approve"), config=config)
代码注释依次说明:退款只在批准之后执行;InMemorySaver 只用于本地测试,生产环境需要持久化的 checkpointer;第一次运行停在 interrupt,状态按 thread_id 保存;打印出来的是等待审核的 payload;审核人按下按钮后,用同一个 config,也就是同一个 thread_id 再次调用。
审批界面可以沿用客户现有的任何工具。你要做的是取出 interrupt 给出的 payload,展示给对的人,再通过 Command(resume=...) 带上正确的 thread_id 把决定送回去。一旦误发到新的 thread_id,得到的就是一个空线程,而不是那笔待处理的退款。
interrupt 上方那几行里的陷阱
文档写得很明确:恢复时,节点会从头重新运行,所以 interrupt 之前的每一行都会再执行一次。由此得出的规则是:绝不要把非幂等操作放在 interrupt 之前。
假设你在 interrupt 前面发了一封“您的申请正在等待审批”的邮件。审核人批准后,节点重跑,客户就会收到第二封邮件。如果把邮件换成写入财务系统,这个错误足以让整个项目失去信任。
最简单的修法是把发邮件挪到 interrupt 下方,或者干脆移出节点,交给审批界面负责通知。如果必须留在上方,就要让它幂等:比如按 thread_id 记录邮件已发送,再次发送前先检查这个标记。
什么时候该选 LangGraph?
如果客户的流程步骤清晰,包含不可撤销的操作,并且有一位负责审批、但不会守在旁边等着的人,就值得考虑 LangGraph。长时间运行和状态持久化,正是让 Agent 能等上一整夜、又不丢失中间进度的关键。
代价在于很多事要自己决定,因为这是一个底层工具:为生产环境选定持久化的 checkpointer,为每个业务请求管理对应的 thread_id,并逐个检查节点里哪些代码会被重跑。如果工作流只是一问一答、无需任何人审批,这些能力大部分都用不上。
先学什么,简历上怎么写
比较合理的学习顺序分三步:先是 checkpointer 和 thread_id,然后是 interrupt 与 Command(resume=...) 这一对,最后才是节点重跑的教训。前两项是机制,最后一项才能区分真正在生产中跑过的人和只读过文档的人。
阅读 FDE 或 AI 工程师岗位的职位描述时,留意“human-in-the-loop”“stateful agent”“long-running workflow”这类措辞。在简历上,与其写“使用过 LangGraph”,不如具体说明你在哪个操作前设置了审批点、状态存在哪里、恢复执行是怎么处理的。
客户很少问你的 Agent 有多聪明。他们问的是:它会在哪里停下,谁有权让它继续。
这篇文章对你有帮助吗?
感谢你的反馈!