Principle:Langchain ai Langgraph State Inspection

Property	Value
Concept	Inspecting and modifying graph execution state for human review
Workflow	Human_in_the_Loop_Agent
Pipeline Stage	State Management
Repository	Langchain_ai_Langgraph
Source	`libs/langgraph/langgraph/pregel/main.py:L1235-1275` (get_state), `L2309-2320` (update_state), `libs/prebuilt/langgraph/prebuilt/interrupt.py:L87-106`

Overview

State inspection is the ability to retrieve and examine the current state of a paused graph execution, including channel values, pending tasks, interrupt data, and execution metadata. Combined with state mutation (via update_state()), this enables a human operator to understand what the graph is doing, modify its state before resuming, and provide structured responses to interrupts.

Description

When a graph pauses at an interrupt, the human operator typically needs to:

Understand the current situation: What node was about to execute? What are the pending tool calls? What question did the interrupt ask?
Decide how to proceed: Approve, reject, modify, or redirect the graph's next action.
Optionally modify state: Change values in the graph state before resuming, such as editing a message, adding context, or correcting an error.

LangGraph provides two methods on the compiled graph (Pregel) to support these needs:

`get_state(config)`

Retrieves a StateSnapshot for the given thread. The snapshot contains:

values: Current values of all state channels (the graph's shared state).
next: A tuple of node names that would execute in the next step. If the graph was interrupted before a node, that node appears here.
tasks: A tuple of PregelTask objects representing the pending tasks. Each task includes its ID, name, path, any error, and any interrupts.
interrupts: A tuple of Interrupt objects representing pending interrupts that need resolution.
metadata: Checkpoint metadata including the source (input, loop, update), step number, and writes.
config: The config used to fetch this snapshot (includes checkpoint_id).
parent_config: The config for the parent checkpoint, enabling history traversal.
created_at: Timestamp of when the checkpoint was created.

`update_state(config, values, as_node=None, task_id=None)`

Modifies the graph state by applying the given values as if they came from a specific node. This is useful for:

Editing pending tool calls before allowing execution.
Injecting human responses into the state.
Correcting errors in the graph state.

The as_node parameter specifies which node the update appears to come from, which affects routing logic. If not provided, it defaults to the last node that updated the state.

`HumanResponse` TypedDict

For structured human-in-the-loop interactions, the HumanResponse TypedDict provides a standardized response format with:

type: One of "accept", "ignore", "response", or "edit".
args: The response payload -- None for accept/ignore, str for text responses, or ActionRequest for edits.

Usage

State inspection is used between the interrupt and resume phases of a human-in-the-loop workflow:

Graph runs until interrupt.
Client calls get_state(config) to retrieve the snapshot.
Client presents the snapshot data to the human (e.g., pending tool calls, interrupt values).
Human decides on action (approve, reject, edit, respond).
Client optionally calls update_state(config, values) to modify state.
Client resumes the graph with stream(Command(resume=...), config) or stream(None, config).

Theoretical Basis

State inspection and mutation implement several key concepts in human-in-the-loop systems:

State snapshots: A StateSnapshot is a complete, read-only view of the graph's execution state at a specific point in time. It includes not just the data (channel values) but also the control flow state (next nodes, pending tasks, interrupts). This dual view is essential for human decision-making.
State mutation as intervention: The update_state() method allows a human to intervene in the graph's execution by directly modifying its state. The as_node parameter preserves the graph's routing semantics by making the update appear to come from a specific node.
Node attribution: The as_node parameter in update_state() determines which node's output channels the update is applied to. This affects subsequent conditional edge routing. For example, updating state as_node="agent" means the routing logic after the "agent" node will evaluate with the modified state.
Human response types: The HumanResponse TypedDict categorizes human responses into four types (accept, ignore, response, edit), providing a structured vocabulary for the human's decision. This maps to common patterns in approval workflows.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment