interrupt() 函数来工作。该函数接受任何可 JSON 序列化的值并将其呈现给调用者。当您准备好继续时,您可以通过使用 Command 重新调用图来恢复执行,然后它将成为节点内部 interrupt() 调用的返回值。
与在特定节点之前或之后暂停的静态断点不同,中断是动态的:它们可以放置在代码的任何位置,并且可以根据您的应用程序逻辑进行条件判断。
- 检查点保持您的位置: 检查点器写入确切的图状态,以便您可以在稍后恢复,即使在错误状态下也是如此。
thread_id是指针: 设置config={"configurable": {"thread_id": ...}}以告诉检查点器加载哪个状态。- 中断负载通过
chunk["interrupts"]呈现: 当使用version="v2"流式传输时,您传递给interrupt()的值出现在values流部分的interrupts字段中,这样您就知道图在等待什么。
thread_id 实际上是您的持久化游标。重用它会恢复相同的检查点;使用新值会启动一个具有空状态的全新线程。
使用 interrupt 暂停
interrupt 函数暂停图的执行并向调用者返回值。当您在节点内调用 interrupt 时,LangGraph 保存当前图状态并等待您使用输入恢复执行。
要使用 interrupt,您需要:
- 用于持久化图状态的 检查点器(在生产环境中使用耐久的检查点器)
- 配置中的 线程 ID,以便运行时知道从哪个状态恢复
- 在您想要暂停的位置调用
interrupt()(负载必须是可 JSON 序列化的)
interrupt 时,会发生以下情况:
- 图执行被挂起 在调用
interrupt的确切位置 - 状态被保存 使用检查点器,以便以后可以恢复执行,在生产环境中,这应该是持久化检查点器(例如,由数据库支持)
- 返回值 返回给调用者,位于
__interrupt__下;它可以是任何可 JSON 序列化的值(字符串、对象、数组等) - 图无限期等待 直到您使用响应恢复执行
- 响应被传回 当您恢复时进入节点,成为
interrupt()调用的返回值
恢复中断
在中断暂停执行后,您通过使用包含恢复值的Command 再次调用图来恢复图。恢复值被传回给 interrupt 调用,允许节点使用外部输入继续执行。
- v2 (LangGraph >= 1.1)
- v1 (default)
- 恢复时必须使用与中断发生时相同的 线程 ID
- 传递给
Command(resume=...)的值成为interrupt调用的返回值 - 恢复时,节点从调用
interrupt的节点的开头重新开始,因此interrupt之前的任何代码都会再次运行 - 您可以传递任何可 JSON 序列化的值作为恢复值
常见模式
中断解锁的关键功能是暂停执行并等待外部输入的能力。这对于各种用例很有用,包括:- 审批工作流:在执行关键操作(API 调用、数据库更改、金融交易)之前暂停
- 处理多个中断:在单次调用中恢复多个中断时,将中断 ID 与恢复值配对
- 审查和编辑:让人类在继续之前审查和修改 LLM 输出或工具调用
- 中断工具调用:在执行工具调用之前暂停,以便在执行前审查和编辑工具调用
- 验证人类输入:在进行下一步之前暂停以验证人类输入
使用人机回环 (HITL) 中断进行流式传输
在构建具有人机回环工作流的交互式代理时,您可以同时流式传输消息块和节点更新,以便在处理中断的同时提供实时反馈。 使用多种流模式("messages" 和 "updates")以及 subgraphs=True(如果存在子图)来:
- 实时流式传输生成的 AI 响应
- 检测图何时遇到中断
- 无缝处理用户输入并恢复执行
-
version="v2":所有块都是带有type,ns和data键的StreamPart字典 -
chunk["type"]:缩小流模式("messages","updates"等)的范围以进行类型推断 -
chunk["ns"]:标识源图(根图为空元组,子图已填充) -
subgraphs=True:嵌套图中检测中断所必需 -
Command(resume=...):使用用户提供的数据恢复图执行
处理多个中断
当并行分支同时中断时(例如,扇出到多个每个都调用interrupt() 的节点),您可能需要在单次调用中恢复多个中断。
当使用单次调用恢复多个中断时,将每个中断 ID 映射到其恢复值。
这确保每个响应在运行时都与正确的中断配对。
批准或拒绝
中断最常见的用途之一是在关键操作之前暂停并请求批准。例如,您可能希望要求人类批准 API 调用、数据库更改或任何其他重要决定。True 表示批准或 False 表示拒绝:
完整示例
完整示例
审查和编辑状态
有时您希望让人类在继续之前审查和编辑图的一部分状态。这对于纠正 LLM、添加缺失信息或进行调整很有用。完整示例
完整示例
工具中的中断
您还可以直接将中断放在工具函数内部。这使得工具本身在被调用时暂停以获取批准,并允许在执行前对人类审查和编辑工具调用。 首先,定义一个使用interrupt 的工具:
完整示例
完整示例
验证人类输入
有时您需要验证来自人类的输入,如果无效则再次询问。您可以使用循环中的多个interrupt 调用来完成此操作。
完整示例
完整示例
中断规则
当您在节点内调用interrupt 时,LangGraph 通过引发异常来挂起执行,该异常向运行时发出暂停信号。此异常沿调用栈传播并被运行时捕获,运行时通知图保存当前状态并等待外部输入。
当执行恢复时(在您提供所需输入后),运行时从头开始重新启动整个节点——它不会从调用 interrupt 的确切行恢复。这意味着 interrupt 之前运行的任何代码都将再次执行。因此,在使用中断时要遵循一些重要规则,以确保它们按预期行为。
不要在 try/except 中包装 interrupt 调用
interrupt 通过在调用点抛出特殊异常来暂停执行的方式。如果您在 try/except 块中包装 interrupt 调用,您将捕获此异常,中断将不会传回给图。
- ✅ 将
interrupt调用与易错代码分离 - ✅ 在 try/except 块中使用特定的异常类型
- 🔴 不要在裸 try/except 块中包装
interrupt调用
不要在节点内重新排序 interrupt 调用
在一个节点中使用多个中断很常见,但如果处理不当可能会导致意外行为。
当节点包含多个中断调用时,LangGraph 会维护一个针对执行该节点的任务的恢复值列表。每当执行恢复时,它从节点的开头开始。对于遇到的每个中断,LangGraph 检查任务的恢复列表中是否存在匹配的值。匹配是严格基于索引的,因此节点内中断调用的顺序很重要。
- ✅ 在节点执行之间保持
interrupt调用一致
不要在 interrupt 调用中返回复杂值
根据使用的检查点器不同,复杂值可能无法序列化(例如,您不能序列化函数)。为了使您的图适应任何部署,最佳实践是仅使用可以合理序列化的值。
- ✅ 向
interrupt传递简单、可 JSON 序列化的类型 - ✅ 传递具有简单值的字典/对象
- 🔴 不要向
interrupt传递函数、类实例或其他复杂对象
interrupt 之前调用的副作用必须是幂等的
因为中断通过重新运行调用它们的节点来工作,所以在 interrupt 之前调用的副作用应该(理想情况下)是幂等的。为了上下文,幂等性意味着同一操作可以应用多次,而不会改变初始执行之外的结果。
作为一个例子,您可能有一个在节点内更新记录的 API 调用。如果在调用之后调用 interrupt,当节点恢复时它将多次重新运行,可能会覆盖初始更新或创建重复记录。
- 🔴 不要在
interrupt之前执行非幂等操作 - 🔴 不要在不检查是否存在的情况下创建新记录
与作为函数调用的子图一起使用
当在节点内调用子图时,父图将从调用子图和触发interrupt 的 节点开头 恢复执行。同样,子图 也将从调用 interrupt 的节点开头恢复。
使用中继调试
要调试和测试图,您可以使用静态中断作为断点,一次一个节点地逐步执行图执行。静态中断在节点执行之前或之后的定义点触发。您可以通过在编译图时指定interrupt_before 和 interrupt_after 来设置这些。
静态中断 不 推荐用于人机回环工作流。请使用
interrupt 函数。- 编译时
- 运行时
- 断点在
compile期间设置。 interrupt_before指定应在节点执行之前暂停执行的节点。interrupt_after指定应在节点执行之后暂停执行的节点。- 需要检查点器来启用断点。
- 图运行直到击中第一个断点。
- 通过传入
None作为输入来恢复图。这将运行图直到击中下一个断点。
使用 LangSmith Studio
您可以在运行图之前在 UI 中使用 LangSmith Studio 在图中设置静态中断。您还可以使用 UI 检查执行过程中任何点的图状态。
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

