Bound prompt size
A graph accumulates a long conversation and needs to keep prompts within the selected model's context window.
AI Agents · Function
trim_messages
trimMessages reduces a conversation history to fit an LLM's context window. Configure the retention strategy, token budget, and valid message boundaries before invoking the model.
How it works
trimMessages selects a bounded portion of a message list before an LLM call. With the last-message strategy, it retains the newest messages up to the configured token budget while the boundary options help preserve valid conversation structure.
Syntax
trimMessages(messages, { strategy, maxTokens, startOn, endOn })Parameters
| Name | Type | Description |
|---|---|---|
messages | BaseMessage[] | The message list to trim, such as state.messages. |
strategy | string | Controls which side of the history is retained; the documented example uses "last". |
maxTokens | number | Maximum number of tokens to retain. |
startOn | string | Message type at which the retained segment may begin. |
endOn | string[] | Message types at which the retained segment may end. |
Returns
A trimmed message list suitable for passing to the model.
Key points
- Token counting provides the basis for deciding when history is approaching the model's context limit.
- The strategy determines which side of the history is retained; the JavaScript example uses the recent-message approach.
- Apply trimming immediately before the model invocation rather than storing only the shortened history as the canonical state.
- The sample permits the retained segment to end on either a human or tool message.
Common mistakes
- Choose a token budget below the model's context limit so the resulting prompt remains acceptable.
- The limit is token-based; it is not simply a count of message objects.
Example: Trim graph messages before an LLM call
import { trimMessages } from "@langchain/core/messages";
import { StateSchema, MessagesValue, GraphNode } from "@langchain/langgraph";
const State = new StateSchema({ messages: MessagesValue });
const callModel: GraphNode<typeof State> = async (state) => {
const messages = trimMessages(state.messages, {
strategy: "last",
maxTokens: 128,
startOn: "human",
endOn: ["human", "tool"],
});
const response = await model.invoke(messages);
return { messages: [response] };
};Keeps a bounded recent message history before invoking the model.
When to use it
Keep a valid recent exchange
A model call should use recent dialogue while preserving human and tool message boundaries.
Prepare node input
A node receives the complete state history but should send only a budgeted subset to the LLM.
Interview questions
QWhat problem does trimMessages solve?
It trims the message history before invoking the model, using a token budget and a strategy such as retaining the last messages. The JavaScript example uses strategy: "last" and maxTokens: 128.
Follow-up: How can boundary options help? Set startOn and endOn to message roles that form valid boundaries, such as starting on human and ending on human or tool messages.
QHow does the example limit retained history?
strategy: "last" keeps the recent portion of the conversation, while maxTokens limits the retained history. This reduces the chance that the prompt exceeds the model's context window.
Follow-up: What should be adjusted for a different model? Recalculate the budget for that model's supported context window and token-counting behavior.
QWhat do startOn and endOn control?
The example passes startOn: "human" and endOn: ["human", "tool"]. These options constrain where trimming may begin and end, helping avoid cutting the history at unsuitable message boundaries.
Follow-up: Why might tool messages matter? A tool result can be part of the latest interaction, so retaining it may preserve the context needed for the next model call.
Related
MessagesValueGraphNodeBaseMessagemodel.invoke