Understanding add_messages

add_messages in LangGraph

add_messages is a reducer function in LangGraph used to append messages to a list.
The messages key is annotated with the add_messages reducer, which instructs LangGraph to append new messages to the existing list.
State keys that are not annotated with a reducer will be overwritten by the latest value during each update.

• Main Functionality
  Merges two lists of messages.
  Maintains an append-only state by default.
  If there are messages with the same id, the existing message is replaced by the new one.

• How It Works
  If a message in right has the same id as one in left, it replaces the corresponding message in left.
  Otherwise, messages from right are appended to the left list.

• Parameters
  left (Messages): The base list of messages.
  right (Messages): The list or single message to be merged into left.

• Returns
  Messages: A new list of messages where the right messages have been merged into the left.

from langchain_core.messages import AIMessage, HumanMessage
from langgraph.graph import add_messages

# Basic usage example
msgs1 = [HumanMessage(content="Hello! The weather is nice today, isn’t it?", id="1")]
msgs2 = [AIMessage(content="Yes, the weather is very sunny.", id="2")]

result1 = add_messages(msgs1, msgs2)
result1

[HumanMessage(content='Hello! The weather is nice today, isn’t it?', additional_kwargs={}, response_metadata={}, id='1'),
 AIMessage(content='Yes, the weather is very sunny.', additional_kwargs={}, response_metadata={}, id='2')]

If a message with the same ID exists, it will be replaced.

from langchain_core.messages import AIMessage, HumanMessage
from langgraph.graph import add_messages

msgs1 = [HumanMessage(content="Hello! The weather is nice today, isn’t it?", id="1")]
msgs2 = [AIMessage(content="Yes, the weather is very sunny.", id="1")]
  
result2 = add_messages(msgs1, msgs2)
print(result2)

[AIMessage(content='Yes, the weather is very sunny.', additional_kwargs={}, response_metadata={}, id='1')]

I’ll now try applying the message flow from the previous post using add_messages directly.

from langchain_core.messages import AIMessage, HumanMessage
from langgraph.graph import add_messages

msgs1 = [SystemMessage(content="You are a helpful assistant that answers questions concisely.", id="1")]
msgs2 = [HumanMessage(content="How's the weather in sf?", id="2")]
merge_msgs = add_messages(msgs1, msgs2)
msgs3 = [AIMessage(
            content='',  # No direct response; instead, it triggers a tool call
            tool_calls=[{
                'name': 'get_weather',       # Name of the tool to be called
                'args': {'city': 'sf'},      # Arguments to be passed to the tool
                'id': 'bnb734sce',           # ID used to map the tool call and its response
                'type': 'tool_call'          # Specifies this is a tool call
            }],
            id="3"
        )]
merge_msgs = add_messages(merge_msgs, msgs3)
msgs4 = [ToolMessage(
            content="It's always sunny in sf!",   # Result of executing the tool
            name='get_weather',                   # Name of the tool that was called
            tool_call_id="bnb734sce",              # ID of the tool call this result corresponds to
            id="4"
        )]
merge_msgs = add_messages(merge_msgs, msgs4)

msgs5 = [AIMessage(content="It's always sunny in San Francisco!", id="5")]
merge_msgs = add_messages(merge_msgs, msgs5)
merge_msgs

[SystemMessage(content='You are a helpful assistant that answers questions concisely.', additional_kwargs={}, response_metadata={}, id='1'),
 HumanMessage(content="How's the weather in sf?", additional_kwargs={}, response_metadata={}, id='2'),
 AIMessage(content='', additional_kwargs={}, response_metadata={}, id='3', tool_calls=[{'name': 'get_weather', 'args': {'city': 'sf'}, 'id': 'bnb734sce', 'type': 'tool_call'}]),
 ToolMessage(content="It's always sunny in sf!", name='get_weather', id='4', tool_call_id='bnb734sce'),
 AIMessage(content="It's always sunny in San Francisco!", additional_kwargs={}, response_metadata={}, id='5')]