Implementing State Reducers

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.

The image illustrates the concept of using state reducers by showing a shared state connected to three nodes (A, B, and C) with issues like "Overwrite" and "Duplicate" indicated.

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.

The image explains a "State Reducer" function, highlighting its roles: adding a field only if it doesn't exist and adding to a list without overwriting.

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.

The image explains "What is a State Reducer?" with a diagram showing nodes A, B, and C, each connected to a state. It illustrates how a "State Reducer" edits and commits state after each node in the LangGraph system.

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.

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).

The image explains state merging in LangGraph, highlighting that data should be merged intelligently rather than overwritten. It describes actions based on node output, such as updating intent or appending messages.

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.

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.

The image is about reusing reducers across graphs, highlighting that reducers are functions that can be imported and plugged into different flows and keep business logic centralized.

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
Python: typing_extensions documentation
Pattern references: accumulation, idempotence, and cleanup techniques in stateful systems

Course Introduction

Foundational Graph Concepts and Toolkit Setup

The Core Workflow: Nodes, Edges, and Routing

State Management and Iterative Loops

Context Management and Short-Term Memory

Long-Term Memory and Stateful Persistence

Human-in-the-Loop (HILT) Architectures

Advanced Control and Debugging UX

Conclusion

Implementing State Reducers

How reducers introduce discipline

Field-level reducers (custom merging)

Example: custom merge for tool results

Benefits and common reducer patterns

Reuse and modularity

Best practices

Summary

Links and references

Watch Video

​How reducers introduce discipline

​Field-level reducers (custom merging)

​Example: custom merge for tool results

​Benefits and common reducer patterns

​Reuse and modularity

​Best practices

​Summary

​Links and references

Watch Video

How reducers introduce discipline

Field-level reducers (custom merging)

Example: custom merge for tool results

Benefits and common reducer patterns

Reuse and modularity

Best practices

Summary

Links and references