跳到主要内容
中断允许您在特定点暂停图执行,并等待外部输入后继续。这使得需要外部输入才能继续的人工介入模式成为可能。当中断触发时,LangGraph 使用其持久化层保存图状态,并无限期等待,直到您恢复执行。 中断通过在图节点中的任何位置调用 interrupt() 函数来实现。该函数接受任何可 JSON 序列化的值,并将其返回给调用者。当您准备好继续时,通过使用 Command 重新调用图来恢复执行,该 Command 随后成为节点内部 interrupt() 调用的返回值。 与静态断点(在特定节点之前或之后暂停)不同,中断是动态的——它们可以放置在代码中的任何位置,并且可以根据您的应用程序逻辑进行条件设置。
  • 检查点保持您的位置:检查点写入精确的图状态,以便您以后可以恢复,即使在错误状态下也是如此。
  • thread_id 是您的指针:设置 config={"configurable": {"thread_id": ...}} 告诉检查点要加载哪个状态。
  • 中断负载以 __interrupt__ 形式显示:您传递给 interrupt() 的值在 __interrupt__ 字段中返回给调用者,以便您知道图正在等待什么。
您选择的 thread_id 实际上是您的持久化游标。重复使用它会恢复相同的检查点;使用新值会启动一个全新的线程,状态为空。

使用 interrupt 暂停

interrupt 函数暂停图执行并向调用者返回值。当您在节点内调用 interrupt 时,LangGraph 保存当前图状态并等待您以输入恢复执行。 要使用 interrupt,您需要:
  1. 一个检查点来持久化图状态(在生产环境中使用持久化检查点)
  2. 配置中的线程 ID,以便运行时知道从哪个状态恢复
  3. 在您想要暂停的地方调用 interrupt()(负载必须是可 JSON 序列化的)
from langgraph.types import interrupt

def approval_node(state: State):
    # Pause and ask for approval
    approved = interrupt("Do you approve this action?")

    # When you resume, Command(resume=...) returns that value here
    return {"approved": approved}
当您调用 interrupt 时,会发生以下情况:
  1. 图执行被暂停在调用 interrupt 的确切位置
  2. 状态通过检查点保存,以便以后可以恢复执行。在生产环境中,这应该是一个持久化检查点(例如,由数据库支持)
  3. 值在 __interrupt__ 下返回给调用者;它可以是任何可 JSON 序列化的值(字符串、对象、数组等)
  4. 图无限期等待,直到您以响应恢复执行
  5. 当您恢复时,响应会传回节点,成为 interrupt() 调用的返回值

恢复中断

中断暂停执行后,您可以通过再次使用包含恢复值的 Command 调用图来恢复它。恢复值将传回给 interrupt 调用,允许节点继续执行外部输入。
from langgraph.types import Command

# Initial run - hits the interrupt and pauses
# thread_id is the persistent pointer (stores a stable ID in production)
config = {"configurable": {"thread_id": "thread-1"}}
result = graph.invoke({"input": "data"}, config=config)

# Check what was interrupted
# __interrupt__ contains the payload that was passed to interrupt()
print(result["__interrupt__"])
# > [Interrupt(value='Do you approve this action?')]

# Resume with the human's response
# The resume payload becomes the return value of interrupt() inside the node
graph.invoke(Command(resume=True), config=config)
恢复的关键点
  • 恢复时必须使用中断发生时使用的相同线程 ID
  • 传递给 Command(resume=...) 的值成为 interrupt 调用的返回值
  • 当恢复时,节点会从调用 interrupt 的节点开头重新启动,因此 interrupt 之前的任何代码都会再次运行
  • 您可以传递任何可 JSON 序列化的值作为恢复值

常见模式

中断解锁的关键能力是暂停执行并等待外部输入。这对于各种用例都很有用,包括
  • 审批工作流:在执行关键操作(API 调用、数据库更改、金融交易)之前暂停
  • 审查和编辑:让人类在继续之前审查和修改 LLM 输出或工具调用
  • 中断工具调用:在执行工具调用之前暂停,以在执行前审查和编辑工具调用
  • 验证人工输入:在进入下一步之前暂停以验证人工输入

批准或拒绝

中断最常见的用途之一是在关键操作之前暂停并请求批准。例如,您可能希望让人类批准 API 调用、数据库更改或任何其他重要决策。
from typing import Literal
from langgraph.types import interrupt, Command

def approval_node(state: State) -> Command[Literal["proceed", "cancel"]]:
    # Pause execution; payload shows up under result["__interrupt__"]
    is_approved = interrupt({
        "question": "Do you want to proceed with this action?",
        "details": state["action_details"]
    })

    # Route based on the response
    if is_approved:
        return Command(goto="proceed")  # Runs after the resume payload is provided
    else:
        return Command(goto="cancel")
当您恢复图时,传入 true 表示批准,false 表示拒绝
# To approve
graph.invoke(Command(resume=True), config=config)

# To reject
graph.invoke(Command(resume=False), config=config)
import sqlite3
from typing import Literal, Optional, TypedDict

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


class ApprovalState(TypedDict):
    action_details: str
    status: Optional[Literal["pending", "approved", "rejected"]]


def approval_node(state: ApprovalState) -> Command[Literal["proceed", "cancel"]]:
    # Expose details so the caller can render them in a UI
    decision = interrupt({
        "question": "Approve this action?",
        "details": state["action_details"],
    })

    # Route to the appropriate node after resume
    return Command(goto="proceed" if decision else "cancel")


def proceed_node(state: ApprovalState):
    return {"status": "approved"}


def cancel_node(state: ApprovalState):
    return {"status": "rejected"}


builder = StateGraph(ApprovalState)
builder.add_node("approval", approval_node)
builder.add_node("proceed", proceed_node)
builder.add_node("cancel", cancel_node)
builder.add_edge(START, "approval")
builder.add_edge("approval", "proceed")
builder.add_edge("approval", "cancel")
builder.add_edge("proceed", END)
builder.add_edge("cancel", END)

# Use a more durable checkpointer in production
checkpointer = MemorySaver()
graph = builder.compile(checkpointer=checkpointer)

config = {"configurable": {"thread_id": "approval-123"}}
initial = graph.invoke(
    {"action_details": "Transfer $500", "status": "pending"},
    config=config,
)
print(initial["__interrupt__"])  # -> [Interrupt(value={'question': ..., 'details': ...})]

# Resume with the decision; True routes to proceed, False to cancel
resumed = graph.invoke(Command(resume=True), config=config)
print(resumed["status"])  # -> "approved"

审查和编辑状态

有时您希望让人类在继续之前审查和编辑图状态的一部分。这对于纠正 LLM、添加缺失信息或进行调整很有用。
from langgraph.types import interrupt

def review_node(state: State):
    # Pause and show the current content for review (surfaces in result["__interrupt__"])
    edited_content = interrupt({
        "instruction": "Review and edit this content",
        "content": state["generated_text"]
    })

    # Update the state with the edited version
    return {"generated_text": edited_content}
恢复时,提供编辑后的内容
graph.invoke(
    Command(resume="The edited and improved text"),  # Value becomes the return from interrupt()
    config=config
)
import sqlite3
from typing import TypedDict

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


class ReviewState(TypedDict):
    generated_text: str


def review_node(state: ReviewState):
    # Ask a reviewer to edit the generated content
    updated = interrupt({
        "instruction": "Review and edit this content",
        "content": state["generated_text"],
    })
    return {"generated_text": updated}


builder = StateGraph(ReviewState)
builder.add_node("review", review_node)
builder.add_edge(START, "review")
builder.add_edge("review", END)

checkpointer = MemorySaver()
graph = builder.compile(checkpointer=checkpointer)

config = {"configurable": {"thread_id": "review-42"}}
initial = graph.invoke({"generated_text": "Initial draft"}, config=config)
print(initial["__interrupt__"])  # -> [Interrupt(value={'instruction': ..., 'content': ...})]

# Resume with the edited text from the reviewer
final_state = graph.invoke(
    Command(resume="Improved draft after review"),
    config=config,
)
print(final_state["generated_text"])  # -> "Improved draft after review"

工具中的中断

您还可以直接在工具函数中放置中断。这使得工具本身在被调用时暂停以进行批准,并允许在执行工具调用之前进行人工审查和编辑。 首先,定义一个使用 interrupt 的工具:
from langchain.tools import tool
from langgraph.types import interrupt

@tool
def send_email(to: str, subject: str, body: str):
    """Send an email to a recipient."""

    # Pause before sending; payload surfaces in result["__interrupt__"]
    response = interrupt({
        "action": "send_email",
        "to": to,
        "subject": subject,
        "body": body,
        "message": "Approve sending this email?"
    })

    if response.get("action") == "approve":
        # Resume value can override inputs before executing
        final_to = response.get("to", to)
        final_subject = response.get("subject", subject)
        final_body = response.get("body", body)
        return f"Email sent to {final_to} with subject '{final_subject}'"
    return "Email cancelled by user"
当您希望审批逻辑与工具本身一起存在,使其在图的不同部分可重用时,此方法很有用。LLM 可以自然地调用工具,并且中断会在工具被调用时暂停执行,允许您批准、编辑或取消操作。
import sqlite3
from typing import TypedDict

from langchain.tools import tool
from langchain_anthropic import ChatAnthropic
from langgraph.checkpoint.sqlite import SqliteSaver
from langgraph.graph import StateGraph, START, END
from langgraph.types import Command, interrupt


class AgentState(TypedDict):
    messages: list[dict]


@tool
def send_email(to: str, subject: str, body: str):
    """Send an email to a recipient."""

    # Pause before sending; payload surfaces in result["__interrupt__"]
    response = interrupt({
        "action": "send_email",
        "to": to,
        "subject": subject,
        "body": body,
        "message": "Approve sending this email?",
    })

    if response.get("action") == "approve":
        final_to = response.get("to", to)
        final_subject = response.get("subject", subject)
        final_body = response.get("body", body)

        # Actually send the email (your implementation here)
        print(f"[send_email] to={final_to} subject={final_subject} body={final_body}")
        return f"Email sent to {final_to}"

    return "Email cancelled by user"


model = ChatAnthropic(model="claude-sonnet-4-5-20250929").bind_tools([send_email])


def agent_node(state: AgentState):
    # LLM may decide to call the tool; interrupt pauses before sending
    result = model.invoke(state["messages"])
    return {"messages": state["messages"] + [result]}


builder = StateGraph(AgentState)
builder.add_node("agent", agent_node)
builder.add_edge(START, "agent")
builder.add_edge("agent", END)

checkpointer = SqliteSaver(sqlite3.connect("tool-approval.db"))
graph = builder.compile(checkpointer=checkpointer)

config = {"configurable": {"thread_id": "email-workflow"}}
initial = graph.invoke(
    {
        "messages": [
            {"role": "user", "content": "Send an email to alice@example.com about the meeting"}
        ]
    },
    config=config,
)
print(initial["__interrupt__"])  # -> [Interrupt(value={'action': 'send_email', ...})]

# Resume with approval and optionally edited arguments
resumed = graph.invoke(
    Command(resume={"action": "approve", "subject": "Updated subject"}),
    config=config,
)
print(resumed["messages"][-1])  # -> Tool result returned by send_email

验证人工输入

有时您需要验证人类输入,如果无效则再次询问。您可以使用循环中的多个 interrupt 调用来完成此操作。
from langgraph.types import interrupt

def get_age_node(state: State):
    prompt = "What is your age?"

    while True:
        answer = interrupt(prompt)  # payload surfaces in result["__interrupt__"]

        # Validate the input
        if isinstance(answer, int) and answer > 0:
            # Valid input - continue
            break
        else:
            # Invalid input - ask again with a more specific prompt
            prompt = f"'{answer}' is not a valid age. Please enter a positive number."

    return {"age": answer}
每次您以无效输入恢复图时,它都会以更清晰的消息再次询问。一旦提供了有效输入,节点完成,图继续。
import sqlite3
from typing import TypedDict

from langgraph.checkpoint.sqlite import SqliteSaver
from langgraph.graph import StateGraph, START, END
from langgraph.types import Command, interrupt


class FormState(TypedDict):
    age: int | None


def get_age_node(state: FormState):
    prompt = "What is your age?"

    while True:
        answer = interrupt(prompt)  # payload surfaces in result["__interrupt__"]

        if isinstance(answer, int) and answer > 0:
            return {"age": answer}

        prompt = f"'{answer}' is not a valid age. Please enter a positive number."


builder = StateGraph(FormState)
builder.add_node("collect_age", get_age_node)
builder.add_edge(START, "collect_age")
builder.add_edge("collect_age", END)

checkpointer = SqliteSaver(sqlite3.connect("forms.db"))
graph = builder.compile(checkpointer=checkpointer)

config = {"configurable": {"thread_id": "form-1"}}
first = graph.invoke({"age": None}, config=config)
print(first["__interrupt__"])  # -> [Interrupt(value='What is your age?', ...)]

# Provide invalid data; the node re-prompts
retry = graph.invoke(Command(resume="thirty"), config=config)
print(retry["__interrupt__"])  # -> [Interrupt(value="'thirty' is not a valid age...", ...)]

# Provide valid data; loop exits and state updates
final = graph.invoke(Command(resume=30), config=config)
print(final["age"])  # -> 30

中断规则

当您在节点内调用 interrupt 时,LangGraph 通过引发一个信号运行时暂停的异常来暂停执行。此异常通过调用栈传播并被运行时捕获,运行时通知图保存当前状态并等待外部输入。 当执行恢复时(在您提供请求的输入之后),运行时从头开始重新启动整个节点——它不会从调用 interrupt 的确切行恢复。这意味着在 interrupt 之前运行的任何代码都将再次执行。因此,在使用中断时,需要遵循一些重要规则,以确保它们按预期行为。

不要将 interrupt 调用包装在 try/except 中

interrupt 在调用点暂停执行的方式是抛出一个特殊异常。如果您将 interrupt 调用包装在 try/except 块中,您将捕获此异常,并且中断将不会传回给图。
  • ✅ 将 interrupt 调用与容易出错的代码分开
  • ✅ 在 try/except 块中使用特定的异常类型
def node_a(state: State):
    # ✅ Good: interrupting first, then handling
    # error conditions separately
    interrupt("What's your name?")
    try:
        fetch_data()  # This can fail
    except Exception as e:
        print(e)
    return state
  • 🔴 不要将 interrupt 调用包装在裸 try/except 块中
def node_a(state: State):
    # ❌ Bad: wrapping interrupt in bare try/except
    # will catch the interrupt exception
    try:
        interrupt("What's your name?")
    except Exception as e:
        print(e)
    return state

不要重新排列节点内的 interrupt 调用

在单个节点中使用多个中断很常见,但如果不小心处理,这可能导致意外行为。 当节点包含多个中断调用时,LangGraph 会维护一个特定于执行节点的任务的恢复值列表。每当执行恢复时,它都会从节点的开头开始。对于遇到的每个中断,LangGraph 都会检查任务的恢复列表中是否存在匹配值。匹配是严格基于索引的,因此节点内中断调用的顺序很重要。
  • ✅ 保持 interrupt 调用在节点执行中保持一致
def node_a(state: State):
    # ✅ Good: interrupt calls happen in the same order every time
    name = interrupt("What's your name?")
    age = interrupt("What's your age?")
    city = interrupt("What's your city?")

    return {
        "name": name,
        "age": age,
        "city": city
    }
  • 🔴 不要条件性地跳过节点内的 interrupt 调用
  • 🔴 不要使用在执行过程中不确定的逻辑来循环 interrupt 调用
def node_a(state: State):
    # ❌ Bad: conditionally skipping interrupts changes the order
    name = interrupt("What's your name?")

    # On first run, this might skip the interrupt
    # On resume, it might not skip it - causing index mismatch
    if state.get("needs_age"):
        age = interrupt("What's your age?")

    city = interrupt("What's your city?")

    return {"name": name, "city": city}

不要在 interrupt 调用中返回复杂值

根据所使用的检查点,复杂值可能无法序列化(例如,您无法序列化函数)。为了使您的图能够适应任何部署,最佳实践是只使用可以合理序列化的值。
  • ✅ 将简单、可 JSON 序列化的类型传递给 interrupt
  • ✅ 传递带有简单值的字典/对象
def node_a(state: State):
    # ✅ Good: passing simple types that are serializable
    name = interrupt("What's your name?")
    count = interrupt(42)
    approved = interrupt(True)

    return {"name": name, "count": count, "approved": approved}
  • 🔴 不要将函数、类实例或其他复杂对象传递给 interrupt
def validate_input(value):
    return len(value) > 0

def node_a(state: State):
    # ❌ Bad: passing a function to interrupt
    # The function cannot be serialized
    response = interrupt({
        "question": "What's your name?",
        "validator": validate_input  # This will fail
    })
    return {"name": response}

中断之前调用的副作用必须是幂等的

因为中断通过重新运行调用它们的节点来工作,所以在调用 interrupt 之前调用的副作用应该(理想情况下)是幂等的。就上下文而言,幂等性意味着相同的操作可以多次应用,而不会改变初始执行之外的结果。 例如,您可能在节点内部有一个更新记录的 API 调用。如果在该调用之后调用了 interrupt,当节点恢复时,它将被多次重新运行,可能会覆盖初始更新或创建重复记录。
  • ✅ 在 interrupt 之前使用幂等操作
  • ✅ 将副作用放在 interrupt 调用之后
  • ✅ 在可能的情况下,将副作用分离到不同的节点中
def node_a(state: State):
    # ✅ Good: using upsert operation which is idempotent
    # Running this multiple times will have the same result
    db.upsert_user(
        user_id=state["user_id"],
        status="pending_approval"
    )

    approved = interrupt("Approve this change?")

    return {"approved": approved}
  • 🔴 不要执行 interrupt 之前的非幂等操作
  • 🔴 在创建新记录之前,不要不检查它们是否存在
def node_a(state: State):
    # ❌ Bad: creating a new record before interrupt
    # This will create duplicate records on each resume
    audit_id = db.create_audit_log({
        "user_id": state["user_id"],
        "action": "pending_approval",
        "timestamp": datetime.now()
    })

    approved = interrupt("Approve this change?")

    return {"approved": approved, "audit_id": audit_id}

与作为函数调用的子图一起使用

在节点内调用子图时,父图将从调用子图并触发 interrupt节点开头恢复执行。同样,子图也将从调用 interrupt 的节点开头恢复。
def node_in_parent_graph(state: State):
    some_code()  # <-- This will re-execute when resumed
    # Invoke a subgraph as a function.
    # The subgraph contains an `interrupt` call.
    subgraph_result = subgraph.invoke(some_input)

async function node_in_subgraph(state: State) {
    someOtherCode(); # <-- This will also re-execute when resumed
    result = interrupt("What's your name?")
    ...
}

使用中断进行调试

要调试和测试图,您可以使用静态中断作为断点,一次一个节点地逐步执行图。静态中断在节点执行之前或之后在定义点触发。您可以通过在编译图时指定 interrupt_beforeinterrupt_after 来设置这些。
静态中断建议用于人工介入工作流。请改用 interrupt 方法。
  • 编译时
  • 运行时
graph = builder.compile(
    interrupt_before=["node_a"],  
    interrupt_after=["node_b", "node_c"],  
    checkpointer=checkpointer,
)

# Pass a thread ID to the graph
config = {
    "configurable": {
        "thread_id": "some_thread"
    }
}

# Run the graph until the breakpoint
graph.invoke(inputs, config=config)  

# Resume the graph
graph.invoke(None, config=config)  
  1. 断点在 compile 时设置。
  2. interrupt_before 指定在节点执行之前应暂停执行的节点。
  3. interrupt_after 指定在节点执行之后应暂停执行的节点。
  4. 需要检查点才能启用断点。
  5. 图将运行直到遇到第一个断点。
  6. 图通过传入 None 作为输入来恢复。这将运行图直到遇到下一个断点。

使用 LangGraph Studio

您可以使用LangGraph Studio在运行图之前在 UI 中设置图中的静态中断。您还可以使用 UI 在执行的任何点检查图状态。 image
以编程方式连接这些文档到 Claude、VSCode 等,通过 MCP 获取实时答案。
© . This site is unofficial and not affiliated with LangChain, Inc.