> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Implementing State Reducers
> Explains how LangGraph uses state reducers to control merging, accumulation, and cleanup of shared graph state.
State reducers in LangGraph are the gatekeepers for your shared graph state. They define exactly how the global state should change in response to node outputs, ensuring predictable, consistent updates across the graph.
Why it matters: without reducers, nodes can overwrite or duplicate data, resulting in an unreliable state and hard-to-debug behavior.
## How reducers introduce discipline
A reducer is a simple function that receives the current state and a node's output, then returns the updated state. This is the place to enforce rules like:
* Only add a field if it doesn't already exist.
* Append results to a list instead of replacing the list.
* Prune temporary or sensitive values before they persist.
Think of the reducer as an editor: it inspects node outputs and applies business rules before those outputs are committed.
LangGraph uses the reducer after each node runs to decide what actually becomes part of the global state. This keeps node implementations simple—nodes return outputs, and reducers control how those outputs are merged into the graph.
## Field-level reducers (custom merging)
By default, LangGraph performs a shallow merge when a node returns a field. For many workflows—chat history, tool logs, or aggregated analytics—you want accumulation instead of replacement. Field-level reducers let you define exactly how a single key is merged.
Example: annotate a `messages` field with a reducer that appends new messages rather than replacing the list.
```python theme={null}
from typing_extensions import TypedDict, Annotated
from langgraph.graph.message import add_messages
class GraphState(TypedDict):
messages: Annotated[list, add_messages]
```
Why use field-level reducers? They enable granular control: treat some keys as accumulators (history, logs) and others as unique values (intent, status).
## Example: custom merge for tool results
Below is a concrete reducer example that accumulates tool results instead of overwriting them, plus a sample node that returns the `tool_results` field.
```python theme={null}
from typing_extensions import TypedDict, Annotated
def merge_tool_results(old, new):
# Accumulate results instead of overwriting
return (old or []) + (new or [])
class GraphState(TypedDict):
question: str
tool_results: Annotated[list, merge_tool_results]
def search_web(state: GraphState) -> dict:
# Example implementation: call a search tool and return its results for the
# "tool_results" field. Replace tavily.search with your own tool invocation.
results = tavily.search(query=state["question"], max_results=3)["results"]
return {"tool_results": results}
# Create a graph builder that uses this state shape
builder = StateGraph(GraphState)
```
## Benefits and common reducer patterns
Reducers are plain functions—easy to write, test, and reuse. They help with:
* Accumulation (lists of messages, logs, search results)
* Idempotence (avoid duplicate entries)
* Cleanup (remove or redact temporary or sensitive fields)
* Centralized business logic (same reducer reused across graphs)
| Pattern | Use case | Example |
| -----------: | ------------------------------------------ | --------------------------------------------------- |
| Accumulate | Keep chat history or logs | `messages: Annotated[list, add_messages]` |
| Merge lists | Combine tool outputs over time | `tool_results: Annotated[list, merge_tool_results]` |
| Prune/Redact | Remove diagnostics or transient fields | Reducer that returns `None` or filters keys |
| Replace | Single authoritative value (intent/status) | Default merge or reducer that returns `new` |
## Reuse and modularity
Because reducers are normal functions, you can import them across graphs to keep merging logic centralized. This enforces consistent state behavior across different flows and makes testing straightforward.
This separation promotes modular design: the graph describes structure and control flow, while reducers encapsulate state semantics. Nodes stay focused on producing outputs; reducers define how those outputs become part of the canonical state.
Use field-level reducers to centralize accumulation and cleanup logic (e.g., chat history, tool logs, diagnostic traces). This avoids ad-hoc state manipulation inside nodes and prevents accidental overwrites.
## Best practices
* Define reducers for any field that represents accumulated history or logs.
* Keep reducers small and focused so they are easy to unit test.
* Use reducers to strip or redact sensitive data before it becomes persistent.
* Reuse reducers across graphs to maintain consistent state behavior.
## Summary
State reducers are foundational for predictable state evolution in LangGraph. They let you implement intelligent merging, prevent accidental overwrites, and keep your nodes simple. Use field-level reducers to centralize accumulation, cleanup, and deduplication logic so your graph's shared state remains reliable and auditable.
## Links and references
* [LangGraph documentation](https://langgraph.example/docs)
* Python: `typing_extensions` documentation
* Pattern references: accumulation, idempotence, and cleanup techniques in stateful systems