# 在客户现场部署 Agent，最难的是谁来点“批准”

> LangGraph 的 interrupt 能在退款发出前暂停 Agent，等人审批几分钟甚至一整夜，再从原处继续。

原文: https://fdetimes.net/zh/tools/langgraph-interrupt-human-approval/

设想这样一个场景：你为客户部署的 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` 是“批准”。

```python
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 前面发了一封“您的申请正在等待审批”的邮件。审核人批准后，节点重跑，客户就会收到第二封邮件。如果把邮件换成写入财务系统，这个错误足以让整个项目失去信任。

最简单的修法是把发邮件挪到 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 有多聪明。他们问的是：它会在哪里停下，谁有权让它继续。

**本周动手试试:**

- 用 LangGraph 搭一个图，在模拟的“退款”操作前只放一个审批节点，然后分别用 approve 和 reject 两个值通过 Command(resume=...) 恢复执行。
- 故意在 interrupt 之前放一条日志打印或文件写入，恢复执行后数一数它运行了几次，亲眼看看节点重跑。
- 改写简历中的一行，描述你如何为 Agent 设计人工审批点，写明拦截的是哪个操作以及原因。

## 信源

- [langchain-ai/langgraph (GitHub README)](https://github.com/langchain-ai/langgraph)

- [Interrupts – LangGraph docs (docs.langchain.com)](https://docs.langchain.com/oss/python/langgraph/interrupts)

- [Interrupts – LangGraph docs (docs.langchain.com)](https://docs.langchain.com/oss/python/langgraph/human-in-the-loop)

- [Persistence – LangGraph docs (docs.langchain.com)](https://docs.langchain.com/oss/python/langgraph/persistence)

- [Making it easier to build human-in-the-loop agents with interrupt](https://www.langchain.com/blog/making-it-easier-to-build-human-in-the-loop-agents-with-interrupt)
