Message-based graph state
Build a conversational workflow where each node contributes messages to a shared conversation state.
AI Agents · Const
MessagesAnnotation
MessagesAnnotation is a prebuilt LangGraph state annotation for accumulating messages across graph nodes. It supports standard messages and special modifiers such as RemoveMessage.
How it works
MessagesAnnotation is a prebuilt LangGraph state annotation for a messages array. It combines messages returned by nodes and supports both ordinary messages and RemoveMessage-based modifications.
Syntax
const graph = new StateGraph(MessagesAnnotation)Returns
A state annotation whose state contains a messages array and whose reducer combines returned messages.
Key points
- It supplies a ready-made state definition centered on accumulating messages returned by graph nodes.
- Its message reducer understands normal messages as well as removal modifiers.
- The public import comes from the main
@langchain/langgraphpackage. - Pass the annotation directly to
StateGraphto make it the graph's state schema. - Nodes may update the state with one message or with multiple messages in the
messagesfield.
Common mistakes
- Treat the state as message-aware rather than as a plain array: special RemoveMessage values are supported alongside standard messages.
Example: Use MessagesAnnotation as graph state
import { MessagesAnnotation, StateGraph, START, END } from "@langchain/langgraph";
const graph = new StateGraph(MessagesAnnotation)
.addNode("reply", (state) => ({
messages: [{ role: "ai", content: `Received: ${state.messages.at(-1)?.content}` }],
}))
.addEdge(START, "reply")
.addEdge("reply", END)
.compile();
const result = await graph.invoke({
messages: [{ role: "user", content: "Hello" }],
});
console.log(result.messages.at(-1)?.content);Creates a graph whose state uses MessagesAnnotation, appends an AI response, and invokes the compiled graph.
When to use it
Agent and tool workflows
Implement agent loops in which model responses, tool calls, and tool results travel through one state key.
Custom state extensions
Extend message state with application-specific fields by spreading MessagesAnnotation.spec into a larger annotation schema.
Interview questions
QWhat does MessagesAnnotation provide?
MessagesAnnotation is a prebuilt state annotation that combines messages returned by graph nodes. A StateGraph can receive it directly, so nodes read and update the typed messages state key.
Follow-up: How can a graph add other state fields? Answer: create a root annotation that spreads MessagesAnnotation.spec and adds annotations for the additional fields.
QHow do nodes update the messages state?
A node can return either one message or an array under the messages key. The annotation combines that returned content with the existing message state rather than replacing the conversation by default.
Follow-up: What should a node return when it has no message update? Answer: return a partial state object without messages, leaving the existing message state unchanged.
QHow is MessagesAnnotation used in a StateGraph?
Import it from @langchain/langgraph and pass it to new StateGraph(MessagesAnnotation). After adding nodes and edges, compile the graph before invoking it.
Follow-up: How can tool execution be added? Answer: route tool-call-producing AI messages to a tool node, then return tool messages through the same messages state key.
Related
StateGraphAnnotationRemoveMessageToolNodeBaseMessage