Stateful agent workflows
Build an agent workflow from state-reading and state-writing nodes connected by edges.
AI Agents · Class
StateGraph
StateGraph is the builder for stateful workflows whose nodes read shared state and return partial updates. Add nodes and edges, optionally configure reducers, then compile the graph before invoking it.
How it works
StateGraph builds a workflow whose nodes read and partially update shared state. Define the state schema, add nodes and edges, then compile the builder before invoking the resulting graph; reducers can combine updates when multiple nodes write the same key.
Syntax
new StateGraph<SD, S, U, N, I, O, C, NodeReturnType, InterruptType, WriterType>(stateDefinition)Parameters
| Name | Type | Description |
|---|---|---|
SD | State definition | State definition used to type the graph's state and updates; the documentation exposes the constructor through the generic state-definition parameter. |
S | State | The graph's state type. |
U | Update type | The type of updates returned by nodes. |
N | Node-name type | The node-name type. |
I | Input type | The input state type. |
O | Output type | The output state type. |
C | Context type | The context type. |
NodeReturnType | Node return type | The node return type. |
InterruptType | Interrupt type | The interrupt type. |
WriterType | Writer type | The writer type. |
Returns
StateGraph<SD, S, U, N, I, O, C, NodeReturnType, InterruptType, WriterType>
Key points
- StateGraph models workflows around a shared state that nodes read and update.
- Node functions consume the declared state and return only a partial update.
- State fields may define reducers to control how updates are aggregated.
- Reducers receive the existing value and an incoming update, then return the combined value.
- Annotation is the related API to use when declaring StateGraph state channels.
- The builder must be compiled after its structure is configured.
Common mistakes
- Calling StateGraph methods does not make the workflow executable; compile it before use.
Example: Minimal StateGraph
import { Annotation, StateGraph } from "@langchain/langgraph";
const State = Annotation.Root({
count: Annotation<number>,
});
const graph = new StateGraph(State)
.addNode("increment", (state) => ({ count: state.count + 1 }))
.addEdge("__start__", "increment")
.addEdge("increment", "__end__")
.compile();
const result = await graph.invoke({ count: 0 });
console.log(result);Defines annotated state, adds a node and edges, compiles the graph, and invokes the resulting executable graph.
When to use it
Reducer-based aggregation
Accumulate or combine values when several nodes update the same field.
Typed graph interfaces
Define a graph with typed input and output state boundaries.
Planning and tool-use control flow
Create branching, looping, or tool-oriented execution paths with graph edges.
Interview questions
QWhat is StateGraph and what is its basic lifecycle?
StateGraph is the builder for a graph in which nodes communicate through shared state. A node receives the defined state and returns a partial state update; after nodes and edges are configured, compile the graph before using it.
Follow-up: How are concurrent writes to one state key combined? If the key has a reducer, its reducer aggregates the values received from multiple nodes; otherwise the channel keeps the latest value according to its configuration.
QHow do nodes update StateGraph state?
A node reads the graph's state and returns only the fields it wants to update, rather than reconstructing the entire state object. This enables independent nodes to update selected state keys.
Follow-up: What type should a reducer implement? It should accept the current value and an update value, with the shape (left: Value, right: UpdateValue) => Value.
QHow is StateGraph state defined?
The constructor is parameterized by a user-defined state schema, commonly created with Annotation. Annotation can define channels directly or attach reducers to fields, and the graph is then built with nodes and edges.
Follow-up: What does compilation produce? It produces a compiled graph, which is the executable result of the StateGraph builder and should be used for invocation.
Related
AnnotationCompiledStateGraphCompiledGraphSend