Carry tool-call requests
An LLM requests an external operation such as weather lookup or database access.
AI Agents · Class
AIMessage
AIMessage represents an AI response in LangGraph.js. It can include content, typed tool calls, invalid tool calls, usage metadata, and an optional example marker.
How it works
AIMessage is a LangChain message type representing an AI response. In LangGraph.js it can carry ordinary content, tool-call requests, invalid tool calls, usage metadata, and an optional custom tool-call type parameter that enables type-safe handling of tool names and arguments.
Syntax
type AIMessage<ToolCall = DefaultToolCall> = BaseMessage & { example?: boolean; invalid_tool_calls?: InvalidToolCall[]; tool_calls?: ToolCall[]; type: "ai"; usage_metadata?: UsageMetadata; };Parameters
| Name | Type | Description |
|---|---|---|
ToolCall | type parameter | Optional generic type describing the tool-call objects stored in the message; it defaults to DefaultToolCall. |
Returns
An AIMessage value: a BaseMessage with AI-specific fields and an optional, parameterized tool-call collection.
Key points
- A response may contain zero or more structured tool-call requests.
- Parsing failures can be retained as invalid tool-call entries.
- The message can carry model usage information alongside the response.
- The generic tool-call type is optional and falls back to the standard DefaultToolCall type.
Common mistakes
- If no custom tool-call type is supplied, the generic uses the default tool-call shape.
- Custom tool-call types should be modeled as a discriminated union so narrowing by tool name produces the intended argument type.
Example: Typed AIMessage tool call
import { AIMessage } from "@langchain/core/messages";
type WeatherToolCall = {
name: "get_weather";
args: { location: string };
id: string;
type: "tool_call";
};
type MyToolCalls = WeatherToolCall;
const message: AIMessage<MyToolCalls> = new AIMessage({
content: "",
tool_calls: [{
name: "get_weather",
args: { location: "San Francisco" },
id: "call_1",
type: "tool_call",
}],
});
for (const tool of message.tool_calls ?? []) {
if (tool.name === "get_weather") console.log(tool.args.location);
}Creates an AI message with a typed weather tool call and safely reads its location.
When to use it
Model custom tool-call unions
A TypeScript application needs compile-time checking of tool names and argument objects.
Attach usage metadata
An application records token counts or other provider usage details with each model response.
Interview questions
QWhat distinguishes AIMessage from a generic base message?
AIMessage is a type alias combining BaseMessage with AI-specific fields. Its discriminator is type: "ai", and it can include tool_calls, invalid_tool_calls, usage_metadata, and an optional example flag.
Follow-up: How would you preserve type safety for several tools? Define a discriminated union of tool-call variants and pass that union as the AIMessage generic parameter.
QWhat is the purpose of AIMessage<ToolCall>?
The generic parameter controls the type of tool calls stored on the message. It defaults to DefaultToolCall, but callers can provide a custom type to make tool names and argument objects type-safe.
Follow-up: What does narrowing look like? Check a discriminating field such as tool.name, then TypeScript narrows the corresponding args shape.
QHow should code consume tool calls safely?
A tool-call collection is optional, so code should check whether tool_calls exists before iterating it. Once present, each call exposes the custom tool-call structure selected by the generic parameter.
Follow-up: How should malformed requests be represented? Use invalid_tool_calls when the response contains tool-call data that could not be parsed into valid calls.
Related
BaseMessageDefaultToolCallInvalidToolCallToolCallUsageMetadata