langgraph-state-management
Design state schemas, implement reducers, configure persistence, and debug state issues for LangGraph applications. Use when users want to (1) design or define state schemas for LangGraph graphs, (2) implement reducer functions for state accumulation, (3) configure persistence with checkpointers (InMemorySaver/MemorySaver, SqliteSaver, PostgresSaver), (4) debug state update issues or unexpected state behavior, (5) migrate state schemas between versions, (6) validate state schema structure, (7) choose between TypedDict and MessagesState patterns, (8) implement custom reducers for lists, dicts, or sets, (9) use the Overwrite type to bypass reducers, (10) set up thread-based persistence for multi-turn conversations, or (11) inspect checkpoints for debugging.
soba-labs · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add soba-labs/langchain-agent-skills --skill langgraph-state-management技能说明
name: langgraph-state-management description: Design state schemas, implement reducers, configure persistence, and debug state issues for LangGraph applications. Use when users want to (1) design or define state schemas for LangGraph graphs, (2) implement reducer functions for state accumulation, (3) configure persistence with checkpointers (InMemorySaver/MemorySaver, SqliteSaver, PostgresSaver), (4) debug state update issues or unexpected state behavior, (5) migrate state schemas between versions, (6) validate state schema structure, (7) choose between TypedDict and MessagesState patterns, (8) implement custom reducers for lists, dicts, or sets, (9) use the Overwrite type to bypass reducers, (10) set up thread-based persistence for multi-turn conversations, or (11) inspect checkpoints for debugging.
LangGraph State Management
State Design Workflow
Follow this workflow when designing or modifying state for a LangGraph application:
- Identify data requirements — What data flows through the graph?
- Choose a schema pattern — Match the use case to a template
- Define reducers — Decide how concurrent updates merge
- Configure persistence — Select and set up a checkpointer
- Validate and test — Run schema validation and reducer tests
Quick Start
Python — Minimal Chat State
from langgraph.graph import StateGraph, START, END, MessagesState
from langchain_core.messages import AIMessage
class State(MessagesState):
pass
def chat_node(state: State):
return {"messages": [AIMessage(content="Hello!")]}
graph = StateGraph(State).add_node("chat", chat_node)
graph.add_edge(START, "chat").add_edge("chat", END)
app = graph.compile()
Python — Subclass MessagesState
For convenience, subclass the built-in MessagesState (includes messages with add_messages reducer):
from langgraph.graph import MessagesState
class State(MessagesState):
documents: list[str]
query: str
TypeScript — StateSchema with Zod
import { StateGraph, StateSchema, MessagesValue, ReducedValue, START, END } from "@langchain/langgraph";
import { AIMessage } from "@langchain/core/messages";
import { z } from "zod/v4";
const State = new StateSchema({
messages: MessagesValue,
documents: z.array(z.string()).default(() => []),
count: new ReducedValue(
z.number().default(0),
{ reducer: (current, update) => current + update }
),
});
const graph = new StateGraph(State)
.addNode("chat", (state) => ({ messages: [new AIMessage("Hello!")] }))
.addEdge(START, "chat")
.addEdge("chat", END)
.compile();
Schema Patterns
Choose the pattern matching the application type. See references/schema-patterns.md for complete examples with both Python and TypeScript.
| Pattern | Use Case | Key Fields |
|---|---|---|
| Chat | Conversational agents | Built-in messages from MessagesState |
| Research | Information gathering | query, search_results, summary |
| Workflow | Task orchestration | task, status (Literal), steps_completed |
| Tool-Calling | Agents with tools | messages, tool_calls_made, should_continue |
| RAG | Retrieval-augmented generation | query, retrieved_docs, response |
Template files are available in assets/ for each pattern:
assets/chat_state.py— Chat applicationassets/research_state.py— Research agentassets/workflow_state.py— Workflow orchestrationassets/tool_calling_state.py— Tool-calling agent
For RAG state patterns, use reference examples in references/schema-patterns.md.
Reducers
Reducers control how state updates merge when nodes write to the same field.
Key Concepts
- No reducer → value is overwritten (last-write-wins)
- With reducer → values are merged using the reducer function
- A reducer takes
(existing_value, new_value)and returns the merged result
Python: Annotated Type with Reducer
from typing import Annotated
import operator
from langgraph.graph import MessagesState
class State(MessagesState):
# Overwrite (no reducer)
query: str
# Sum integers
count: Annotated[int, operator.add]
# Custom reducer
results: Annotated[list[str], lambda left, right: left + right]
TypeScript: ReducedValue and MessagesValue
const State = new StateSchema({
query: z.string(), // Last-write-wins
messages: MessagesValue, // Built-in message reducer
count: new ReducedValue( // Custom reducer
z.number().default(0),
{ reducer: (current, update) => current + update }
),
});
Built-in Reducers
| Reducer | Import | Behavior |
|---|---|---|
add_messages | langgraph.graph.message | Append, update by ID, delete |
operator.add | operator | Numeric addition or list concatenation |
MessagesValue | @langchain/langgraph | JS equivalent of add_messages |
Bypass Reducers with Overwrite
Replace accumulated state instead of merging:
from langgraph.types import Overwrite
def reset_messages(state: State):
return {"messages": Overwrite(["fresh start"])}
Delete Messages
from langchain_core.messages import RemoveMessage
from langgraph.graph.message import REMOVE_ALL_MESSAGES
# Delete specific message
{"messages": [RemoveMessage(id="msg_123")]}
# Delete all messages
{"messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES)]}
For advanced reducer patterns (deduplication, deep merge, conditional update, size-limited accumulators), see references/reducers.md.
Persistence
Persistence enables multi-turn conversations, human-in-the-loop, time travel, and crash recovery.
Choosing a Backend
| Backend | Package | Use Case |
|---|---|---|
| InMemorySaver | langgraph-checkpoint |