Principle:Langchain ai Langgraph Interrupt Definition
| Property | Value |
|---|---|
| Concept | Defining points where graph execution pauses to collect human input |
| Workflow | Human_in_the_Loop_Agent |
| Pipeline Stage | Interrupt Declaration |
| Repository | Langchain_ai_Langgraph |
| Source | libs/langgraph/langgraph/types.py:L420-543, libs/prebuilt/langgraph/prebuilt/interrupt.py:L51-85
|
Overview
An interrupt in LangGraph is a cooperative mechanism that allows a node to pause graph execution and surface a value to the calling client. This enables human-in-the-loop patterns where automated processing halts at a defined point, presents context or a question to a human operator, and waits for their response before continuing.
Description
LangGraph provides the interrupt(value) function as the primary way for nodes to declare pause points. When a node calls interrupt(value), the following sequence occurs:
- The function checks if a resume value already exists for this interrupt (from a prior
Command(resume=...)call). If so, it returns that value immediately instead of pausing. - If no resume value is found, the function raises a
GraphInterruptexception containing anInterruptdataclass with the provided value and a deterministic ID derived from the checkpoint namespace. - The Pregel execution loop catches this exception, records the interrupt as a pending write, and halts the current super-step.
- The interrupt value is surfaced to the client via the
__interrupt__stream event.
Each Interrupt object carries:
value: Any Python object that communicates context to the human (a question, a preview of an action, structured data, etc.)id: A deterministic identifier generated from the checkpoint namespace, used to match resume values to their corresponding interrupts.
For structured human-in-the-loop patterns, the HumanInterrupt TypedDict provides a standardized schema that describes an action request, allowed response types, and a description. This is a convention built on top of the raw interrupt mechanism.
A node can contain multiple interrupt() calls. LangGraph matches resume values to interrupts by their order within the node: the first resume value corresponds to the first interrupt, the second to the second, and so on. This ordering is tracked via an interrupt counter in the scratchpad.
Usage
Interrupt definitions are used whenever a graph needs to:
- Request human approval before executing a potentially dangerous action (e.g., running a tool, sending an email)
- Collect human input to guide the next step of processing (e.g., asking a clarifying question)
- Present intermediate results for human review before proceeding
- Implement guardrails where a human validates LLM output before it is used
The interrupt() function must be called from within a node function, and the graph must have a checkpointer configured. Without a checkpointer, the GraphInterrupt exception will propagate unhandled.
Theoretical Basis
The interrupt mechanism in LangGraph implements a cooperative interruption model, as opposed to preemptive interruption:
- Cooperative interruption: The node itself decides when and where to pause by explicitly calling
interrupt(). The runtime does not forcibly stop a node mid-execution. This gives the node author full control over what state is visible at the pause point. - Interrupt-resume protocol: The interrupt-resume cycle forms a two-phase protocol. In the first phase, the node raises an interrupt with a value. In the second phase, the client provides a resume value via
Command(resume=...), and the node re-executes from the beginning, with prior interrupts returning their cached resume values. - Idempotent re-execution: Because the node re-executes from the start on resume, all code before an interrupt runs again. The interrupt function acts as a checkpoint within the node: on re-execution, it returns the previously provided resume value rather than pausing again. This is conceptually similar to continuation-passing style, where the interrupt captures a "continuation point."
- Human oversight patterns: The interrupt mechanism supports several standard oversight patterns: approval gates, feedback loops, guided input collection, and review checkpoints. The
HumanInterrupt/HumanResponseTypedDicts provide a structured vocabulary for these interactions.