messages

'Merge' two statuses. If either value passed is 'error', it will return 'error'. Else it will return 'success'.

Collapses an array of tool call chunks into complete tool calls.

This function groups tool call chunks by their id and/or index, then attempts to parse and validate the accumulated arguments for each group. Successfully parsed tool calls are returned as valid ToolCall objects, while malformed ones are returned as InvalidToolCall objects.

The default text splitter function that splits text by newlines.

Filter messages based on name, type or id.

This function is used by memory classes to get a string representation of the chat message history, based on the message content and role.

Produces compact output like:

Human: What's the weather?
AI: Let me check...[tool_calls]
Tool: 72°F and sunny

This avoids token inflation from metadata when stringifying message objects directly.

Immediately-invoked function expression.

Type guard to check if a value is a valid Message object.

Transforms an array of BaseMessage instances into an array of StoredMessage instances. It does this by calling the toDict method on each BaseMessage, which returns a StoredMessage. This function is used to prepare chat messages for storage.

Transforms an array of StoredMessage instances into an array of BaseMessage instances. It uses the mapV1MessageToStoredMessage function to ensure all messages are in the StoredMessage format, then creates new instances of the appropriate BaseMessage subclass based on the type of each message. This function is used to prepare stored messages for use in a chat context.

Merge consecutive Messages of the same type.

NOTE: ToolMessages are not merged, as each has a distinct tool call id that can't be merged.

Trim messages to be below a token count.

Base class for all types of messages in a conversation. It includes properties like content, name, and additional_kwargs. It also includes methods like toDict() and _getType().

Represents a chunk of an AI message, which can be concatenated with other AI message chunks.

Base class for all types of messages in a conversation. It includes properties like content, name, and additional_kwargs. It also includes methods like toDict() and _getType().

Represents a chunk of a message, which can be concatenated with other message chunks. It includes a method _merge_kwargs_dict() for merging additional keyword arguments from another BaseMessageChunk into this one. It also overrides the __add__() method to support concatenation of BaseMessageChunk instances.

Represents a chat message in a conversation.

Represents a chunk of a chat message, which can be concatenated with other chat message chunks.

Represents a function message in a conversation.

Represents a chunk of a function message, which can be concatenated with other function message chunks.

Represents a human message in a conversation.

Represents a chunk of a human message, which can be concatenated with other human message chunks.

Message responsible for deleting other messages.

Represents a system message in a conversation.

Represents a chunk of a system message, which can be concatenated with other system message chunks.

Represents a tool message in a conversation.

Represents a chunk of a tool message, which can be concatenated with other tool message chunks.

Options for controlling merge behavior in _mergeDicts.

Represents a message object that organizes context for an LLM.

Core interface that defines the structure of messages.

Represents the input and output types of a tool that can be used in messages.

Represents a structured set of tools by mapping tool names to definitions that can be used in messages.

Standard message structured used to define the most basic message structure that's used throughout the library.

This is also the message structure that's used when a message structure is not provided.

Marker parameter for objects that tools can return directly.

If a custom BaseTool is invoked with a ToolCall and the output of custom code is not an instance of DirectToolOutput, the output will automatically be coerced to a string and wrapped in a ToolMessage.

A chunk of a tool call (e.g., as part of a stream). When merging ToolCallChunks (e.g., via AIMessageChunk.add), all string attributes are concatenated. Chunks are only merged if their values of index are equal and not None.

Infers the content type for a specific message type from a message structure.

This utility type determines the appropriate content type based on the message structure's output version and the specified message type. The content type varies depending on the output version (see MessageOutputVersion)

Infers the content blocks for a specific message type in a message structure.

This utility type extracts the content block type that corresponds to a given message type from the message structure's content definition.

Infers the properties for a specific message type from a message structure.

This utility type extracts the properties object that corresponds to a given message type from the message structure's properties definition, and excludes the reserved "content" and "type" properties to avoid conflicts with the core message structure.

If the specified type is not defined in the message structure's properties, it returns a generic Record<string, unknown> type to allow for arbitrary properties.

Infers the type of a specific property for a message type from a message structure.

This utility type extracts the type of a single property by name from the properties object that corresponds to a given message type. If the specified property key does not exist in the type's properties, it returns never.

Infers the response metadata type for a specific message type from a message structure.

This utility type extracts the response_metadata property type for a given message type.

Helper type to infer a union of ToolCall types from the tools defined in a MessageStructure. This is used to type the tool_calls array in AIMessage based on the available tools.

Helper type to infer a union of tool output types from the tools defined in a MessageStructure. This is used to type the content of ToolMessage based on the available tool outputs.

Merges two content definition objects from message structures.

This utility type combines content definitions from two message structures, handling the merging of content block types for each message type. The merge logic follows these rules:

• For keys that exist in both T and U: Merges the content blocks using discriminated union merging based on the "type" property. This allows combining different content block types (e.g., text + image) for the same message type.
• For keys that exist only in T: Uses T's content definition as-is
• For keys that exist only in U: Uses U's content definition as-is

Merges two discriminated unions A and B based on a discriminator key (defaults to "type"). For each possible value of the discriminator across both unions:

• If B has a member with that discriminator value, use B's member
• Otherwise use A's member with that discriminator value This effectively merges the unions while giving B's members precedence over A's members.

Merges two message structures A and B into a combined structure. This is a type utility that handles merging of tools, content blocks, and properties from two message structures. The resulting type is usable as its own message structure.

Recursively merges two object types T and U, with U taking precedence over T.

This utility type performs a deep merge of two object types:

• For keys that exist in both T and U:
  • If both values are objects (Record<string, unknown>), recursively merge them
  • Otherwise, U's value takes precedence
• For keys that exist only in T, use T's value
• For keys that exist only in U, use U's value

Merges two output version types from message structures.

This utility type determines the resulting output version when combining two message structures. The merge logic follows these rules:

• If both T and U are undefined, defaults to "v0" for backwards compatibility
• If T is undefined but U is defined, uses U's version
• If U is undefined but T is defined, uses T's version
• If both T and U are defined, U takes precedence (later structure wins)

Represents a tool call block within a message structure by mapping tool names to their corresponding tool call formats, including the input arguments and an optional identifier.

Takes a message structure type T and normalizes it by merging it with the standard message structure. If T is already a standard message structure, returns T unchanged.

This ensures that any custom message structure includes all the standard message structure fields by default while allowing overrides and extensions.

Breakdown of input token counts.

Does not need to sum to full input token count. Does not need to have all keys.

Represents the output version format for message content.

This type determines how the content field is structured in a message:

• "v0": Content is represented as a simple string or array of content blocks
  • provides backward compatibility with simpler content representations
• "v1": Content follows the structured ContentBlock format with typed discriminated unions
  • enables full type safety and structured content block handling

Represents the possible types of messages in the system. Includes standard message types ("ai", "human", "tool", "system") and allows for custom string types that are non-null.

Breakdown of output token counts.

Does not need to sum to full output token count. Does not need to have all keys.

Usage metadata for a message, such as token counts.