If you’ve already spent some time exploring LangGraph and how reducers manage state, you’re probably starting to see how everything fits together.
But there’s one reducer you’ll use more than any other, add_messages.
This one is the workhorse behind your agent’s memory. Every time your AI sends or receives a message, add_messages quietly steps in to update the conversation history and keep everything in sync.
Before we dive in, here’s something you’ll love:
Learn LangChain the clear, concise, and practical way.
Whether you’re just starting out or already building, Langcasts gives you guides, tips, hands-on walkthroughs, and in-depth classes to help you master every piece of the AI puzzle. No fluff, just actionable learning to get you building smarter and faster. Start your AI journey today at Langcasts.com.
In this quick guide, we’ll walk through what add_messages does, how it works, and how to use it to manage message flow in your LangGraph projects.
If you’re totally new to LangGraph or reducers, check out these two quick reads first:
Otherwise, let’s jump right into how add_messages actually keeps your agent’s conversations alive.
What add_messages Does
add_messages is a built-in LangGraph reducer that updates your agent’s message history by adding new messages to the existing state.
That’s it. No magic, just a clean way to keep track of every message in a conversation so your agent remembers what’s already happened.
You can think of it as your agent’s note-taker.
Every time someone speaks — whether it’s the user, the assistant, or a system message, add_messages records that message in order so the context stays consistent.
In LangGraph, a message is just a small dictionary that looks like this:
{"role": "user", "content": "Hello!"}
When you use add_messages, it takes your current list of messages and appends the new one:
Before:
messages = [{"role": "user", "content": "Hi!"}]
After add_messages("How are you?"):
[
{"role": "user", "content": "Hi!"},
{"role": "user", "content": "How are you?"}
]
This small reducer is what helps your LangGraph agent maintain the flow of a conversation. Without it, each new message would feel like starting from scratch.
Next, we’ll look at how add_messages actually works and what happens behind the scenes when it updates your graph’s state.
Under the Hood: How It Works
Now that you know what add_messages does, let’s see how it works behind the scenes.
When you call add_messages, two things happen:
- It looks at the current state of your LangGraph agent.
- It appends new messages to the existing message list.
You give it a state and a message or list of messages, and it returns a new state with those messages added in.
Nothing fancy, just clean state management that makes conversation tracking reliable.
Here’s a quick example:
from langgraph.reducers import add_messages
state = {"messages": []}
new_state = add_messages(
state,
{"role": "user", "content": "Hello, AI!"}
)
print(new_state)
Output:
{'messages': [{'role': 'user', 'content': 'Hello, AI!'}]}
If you add another message, it simply builds on the previous one:
next_state = add_messages(
new_state,
{"role": "assistant", "content": "Hi there! How can I help you?"}
)
print(next_state)
Output:
{
'messages': [
{'role': 'user', 'content': 'Hello, AI!'},
{'role': 'assistant', 'content': 'Hi there! How can I help you?'}
]
}
add_messages always appends new entries while keeping the existing conversation intact.
This makes it perfect for agents that need to remember context across multiple turns.
Next, we’ll walk through how to use add_messages in a real LangGraph workflow and see where it fits in when building an agent.
Using add_messages in Your LangGraph Workflow
You’ve seen what add_messages does in isolation. Now let’s see how it fits inside a typical LangGraph setup.
In most cases, you use add_messages inside a workflow or node that handles interactions between the user and the model. Each time a message is generated or received, the reducer updates the agent’s state to include the new message.
Here’s a simple example that shows how it comes together:
from langgraph.graph import StateGraph
from langgraph.reducers import add_messages
# Step 1: Create a simple state graph
graph = StateGraph()
# Step 2: Define the initial state
state = {"messages": []}
# Step 3: Add a user message
state = add_messages(state, {"role": "user", "content": "Tell me a joke."})
# Step 4: Add the assistant's reply
state = add_messages(state, {"role": "assistant", "content": "Why did the scarecrow win an award? Because he was outstanding in his field!"})
print(state)
Output:
{
"messages": [
{"role": "user", "content": "Tell me a joke."},
{"role": "assistant", "content": "Why did the scarecrow win an award? Because he was outstanding in his field!"}
]
}
This example shows how add_messages quietly keeps your agent’s conversation up to date. Each new message builds on the previous state, which allows LangGraph to maintain context between turns.
You can also use add_messages in custom nodes, like this:
def handle_user_input(state, message):
# Add the user's message
return add_messages(state, {"role": "user", "content": message})
By including add_messages inside a node or after each model response, you ensure that your agent always has a complete record of the conversation to work with.
Next, we’ll look at where add_messages shines and the kinds of problems it solves best in LangGraph workflows.
Where add_messages Shines
add_messages might look simple, but it’s one of the most useful reducers in LangGraph. It plays a key role in keeping your agent’s state consistent and your conversations coherent.
Here are a few places where it really shines:
1. Conversation Tracking
Every message that comes in or goes out needs to be stored somewhere. add_messages handles that automatically, keeping a running log of the entire exchange.
This allows your agent to access past messages and use them for context when generating a response.
2. Memory Management
When paired with memory systems or message filters, add_messages becomes the foundation for long-term conversation handling.
It helps your agent “remember” earlier parts of a chat without you having to manually manage lists or indexes.
3. Multi-Node Workflows
In larger LangGraph setups with several nodes (for example, separate reasoning, planning, and responding nodes), add_messages keeps all message history synchronized.
No matter which node adds a message, the full state stays aligned across the graph.
4. Debugging and Transparency
Since all messages are stored in a structured list, it’s easy to inspect your agent’s message history at any point.
That makes debugging and tracing behavior much simpler, especially in complex workflows.
Next, we’ll cover a few common mistakes and best practices so you can use add_messages effectively without running into problems.
Common Mistakes and Best Practices
Even though add_messages is simple to use, a few small mistakes can cause big headaches if you’re not careful. Here are some common pitfalls to watch for, along with a few best practices to keep your message handling clean and reliable.
❌ Mistake 1: Overwriting Messages Instead of Appending
Some beginners accidentally replace the entire message list instead of adding to it.
For example:
state["messages"] = {"role": "user", "content": "Hi!"} # Wrong
This wipes out your message history.
Always let add_messages handle updates for you:
state = add_messages(state, {"role": "user", "content": "Hi!"}) # Correct
❌ Mistake 2: Using the Wrong Message Format
LangGraph expects messages to follow a simple structure with role and content.
If you forget one of these keys, the reducer might not behave as expected.
# Wrong
add_messages(state, {"text": "Hello!"})
# Correct
add_messages(state, {"role": "user", "content": "Hello!"})
✅ Best Practice 1: Add Multiple Messages at Once When Needed
If you’re adding several messages, pass them as a list:
add_messages(state, [
{"role": "user", "content": "Hi"},
{"role": "assistant", "content": "Hello there!"}
])
This keeps your updates efficient and tidy.
✅ Best Practice 2: Keep Message History Manageable
Over time, long conversations can grow large.
If your agent doesn’t need all previous messages, consider trimming or summarizing the history before adding new ones. This helps keep performance smooth.
✅ Best Practice 3: Use add_messages Consistently
Make add_messages your single source of truth for message updates.
That consistency prevents bugs and ensures every node or function in your workflow is working from the same conversation record.
add_messages might seem small, but it’s a core part of what makes LangGraph conversations work. It quietly keeps your agent’s message history up to date, preserving context and giving your AI the ability to respond naturally across turns.
You’ve seen how it works, how to use it in a workflow, and how to avoid common mistakes. With this reducer in your toolkit, you can manage conversation flow cleanly and focus on building smarter, more context-aware agents.
If you’d like to explore further, check out other reducers like set_messages and clear_messages, or try creating your own custom reducers for more advanced state control.
And if you’re just starting your LangGraph journey, these two guides will help fill in any gaps:
With that, you’re ready to start using add_messages in your own LangGraph projects and see your agents come to life one message at a time.
Top comments (0)