Principle:Langchain ai Langgraph Interrupt Graph Compilation
| Property | Value |
|---|---|
| Concept | Compiling a graph with interrupt points for human-in-the-loop workflows |
| Workflow | Human_in_the_Loop_Agent |
| Pipeline Stage | Graph Compilation |
| Repository | Langchain_ai_Langgraph |
| Source | libs/langgraph/langgraph/graph/state.py:L1035-1045, libs/prebuilt/langgraph/prebuilt/chat_agent_executor.py:L302-303
|
Overview
Graph compilation with interrupt points is the process of transforming a StateGraph builder into an executable CompiledStateGraph (a Pregel instance) that knows which nodes should trigger execution pauses. This is accomplished via the interrupt_before and interrupt_after parameters of StateGraph.compile(), combined with a mandatory checkpointer for state persistence.
Description
LangGraph supports two complementary approaches to defining interrupt points:
1. Compile-time interrupt declarations
The StateGraph.compile() method accepts interrupt_before and interrupt_after parameters, each of which can be:
- A list of node names: The graph pauses before or after the named nodes execute.
- The special value
"*"(typeAll): The graph pauses before or after every node. None: No compile-time interrupts (the default).
When interrupt_before=["tools"] is specified, the Pregel execution loop will checkpoint the state and halt execution before the "tools" node runs. When interrupt_after=["agent"] is specified, the loop halts after the "agent" node completes. These declarations are stored as interrupt_before_nodes and interrupt_after_nodes on the compiled graph.
2. In-node interrupt calls
Nodes can also call interrupt(value) directly within their body. This approach gives finer-grained control, as the node can decide dynamically whether to pause based on its input or intermediate computations.
Checkpointer requirement
Both approaches require a checkpointer. During compilation, the checkpointer is stored on the CompiledStateGraph. During validation, any node names in the interrupt lists are verified to exist in the graph. At runtime, if interrupts are configured but no checkpointer is present, the graph will raise an error.
The create_react_agent() convenience function also accepts interrupt_before and interrupt_after parameters, passing them through to the internal StateGraph.compile() call. The typical pattern for a human-in-the-loop agent is interrupt_before=["tools"], which pauses the agent before executing any tool calls, allowing a human to review and approve them.
Usage
Interrupt graph compilation is used in two primary scenarios:
- Approval gates: Setting
interrupt_before=["tools"]on a ReAct agent so that tool calls are presented to a human for approval before execution. - Review checkpoints: Setting
interrupt_after=["agent"]to review the LLM's output before the workflow continues.
Theoretical Basis
The compile-time interrupt configuration implements a form of static interrupt scheduling:
- Interrupt-before semantics: The graph saves a checkpoint and pauses before the node's function runs. The node appears in the
nexttuple of theStateSnapshot. On resume, the node executes with the current state (possibly modified byupdate_state()). - Interrupt-after semantics: The graph saves a checkpoint after the node completes and its writes are applied. The next node in the graph appears in the
nexttuple. - Checkpointer as prerequisite: Interrupts without a checkpointer are meaningless because there would be no way to save the state for later resumption. The compilation process enforces this by validating the interrupt node names and storing the checkpointer reference.
- Composition with in-node interrupts: Compile-time interrupts and in-node
interrupt()calls can be used together. Compile-time interrupts provide coarse-grained control at node boundaries, while in-node interrupts provide fine-grained control at arbitrary points within a node's logic.