messages

LangChain auto-generated ID prefix for messages and content blocks.

Internal tracing/callback system identifier.

Used for:

• Tracing. Every LangChain operation (LLM call, chain execution, tool use, etc.) gets a unique run_id (UUID)
• Enables tracking parent-child relationships between operations

A type representing any defined Message or MessageChunk type.

Import an attribute from a module located in a package.

This utility function is used in custom __getattr__ methods within __init__.py files to dynamically import attributes.

Ensure the ID is a valid string, generating a new UUID if not provided.

Auto-generated UUIDs are prefixed by 'lc_' to indicate they are LangChain-generated IDs.

Merge multiple message contents.

Convert a Message to a dictionary.

Convert a sequence of Messages to a list of dictionaries.

Format standard data content block to format expected by OpenAI.

"Standard data content block" can include old-style LangChain v0 blocks (URLContentBlock, Base64ContentBlock, IDContentBlock) or new ones.

Convert ImageContentBlock to format expected by OpenAI Chat Completions.

Check if the provided content block is a data content block.

Returns True for both v0 (old-style) and v1 (new-style) multimodal data blocks.

Convert a sequence of messages to a list of messages.

Convert LangChain messages into OpenAI message dicts.

Filter messages based on name, type or id.

Convert a sequence of messages to strings and concatenate them into one string.

Merge consecutive Messages of the same type.

Convert a message chunk to a Message.

Convert a sequence of messages from dicts to Message objects.

Trim messages to be below a token count.

trim_messages can be used to reduce the size of a chat history to a specified token or message count.

In either case, if passing the trimmed chat history back into a chat model directly, the resulting chat history should usually satisfy the following properties:

1. The resulting chat history should be valid. Most chat models expect that chat history starts with either (1) a HumanMessage or (2) a SystemMessage followed by a HumanMessage. To achieve this, set start_on='human'. In addition, generally a ToolMessage can only appear after an AIMessage that involved a tool call.
2. It includes recent messages and drops old messages in the chat history. To achieve this set the strategy='last'.
3. Usually, the new chat history should include the SystemMessage if it was present in the original chat history since the SystemMessage includes special instructions to the chat model. The SystemMessage is almost always the first message in the history if present. To achieve this set the include_system=True.

Message from an AI.

An AIMessage is returned from a chat model as a response to a prompt.

This message represents the output of the model and consists of both the raw output as returned by the model and standardized fields (e.g., tool calls, usage metadata) added by the LangChain framework.

Message chunk from an AI (yielded when streaming).

Breakdown of input token counts.

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

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.

This is a standard representation of token usage that is consistent across models.

Base abstract message class.

Messages are the inputs and outputs of a chat model.

Examples include HumanMessage, AIMessage, and SystemMessage.

Message chunk, which can be concatenated with other Message chunks.

Message that can be assigned an arbitrary speaker (i.e. role).

Chat Message chunk.

Audio data.

Annotation for citing data from a document.

File data that doesn't fit into other multimodal block types.

This block is intended for files that are not images, audio, or plaintext. For example, it can be used for PDFs, Word documents, etc.

If the file is an image, audio, or plaintext, you should use the corresponding content block type (e.g., ImageContentBlock, AudioContentBlock, PlainTextContentBlock).

Image data.

Allowance for errors made by LLM.

Here we add an error key to surface errors made during generation (e.g., invalid JSON arguments.)

Provider-specific annotation format.

Provider-specific content data.

This block contains data for which there is not yet a standard type.

The purpose of this block should be to simply hold a provider-specific payload. If a provider's non-standard output includes reasoning and tool calls, it should be the adapter's job to parse that payload and emit the corresponding standard ReasoningContentBlock and ToolCalls.

Has no extras field, as provider-specific data should be included in the value field.

Plaintext data (e.g., from a .txt or .md document).

Reasoning output from a LLM.

Tool call that is executed server-side.

For example: code execution, web search, etc.

A chunk of a server-side tool call (yielded when streaming).

Result of a server-side tool call.

Text output from a LLM.

This typically represents the main text content of a message, such as the response from a language model or the text of a user message.

Video data.

Message for passing the result of executing a tool back to a model.

FunctionMessage are an older version of the ToolMessage schema, and do not contain the tool_call_id field.

The tool_call_id field is used to associate the tool call request with the tool call response. Useful in situations where a chat model is able to request multiple tool calls in parallel.

Function Message chunk.

Message from the user.

A HumanMessage is a message that is passed in from a user to the model.

Human Message chunk.

Message responsible for deleting other messages.

Message for priming AI behavior.

The system message is usually passed in as the first of a sequence of input messages.

System Message chunk.

Represents an AI's request to call a tool.

Message for passing the result of executing a tool back to a model.

ToolMessage objects contain the result of a tool invocation. Typically, the result is encoded inside the content field.

tool_call_id is used to associate the tool call request with the tool call response. Useful in situations where a chat model is able to request multiple tool calls in parallel.

Tool Message chunk.

A union of all defined Annotation types.

A union of all defined ContentBlock types and aliases.

A union of all defined multimodal data ContentBlock types.

A type representing the various ways a message can be represented.

Message responsible for deleting other messages.

Human message.

Module contains utility functions for working with messages.

Some examples of what you can do with these functions include:

• Convert messages to strings (serialization)
• Convert messages from dicts to Message objects (deserialization)
• Filter messages from a list of messages based on name, type or id etc.

Chat Message.

Function Message.

AI message.

System message.

Base message.

Messages for tools.

Derivations of standard content blocks from provider content.

AIMessage will first attempt to use a provider-specific translator if model_provider is set in response_metadata on the message. Consequently, each provider translator must handle all possible content response types from the provider, including text.

If no provider is set, or if the provider does not have a registered translator, AIMessage will fall back to best-effort parsing of the content into blocks using the implementation in BaseMessage.

A chunk of a tool call (yielded when streaming).

When merging ToolCallChunk objects (e.g., via AIMessageChunk.__add__), all string attributes are concatenated. Chunks are only merged if their values of index are equal and not None.

Example:

left_chunks = [ToolCallChunk(name="foo", args='{"a":', index=0)]
right_chunks = [ToolCallChunk(name=None, args="1}", index=0)]

(
    AIMessageChunk(content="", tool_call_chunks=left_chunks)
    + AIMessageChunk(content="", tool_call_chunks=right_chunks)
).tool_call_chunks == [ToolCallChunk(name="foo", args='{"a":1}', index=0)]

Standard, multimodal content blocks for Large Language Model I/O.

This module provides standardized data structures for representing inputs to and outputs from LLMs. The core abstraction is the Content Block, a TypedDict.

Rationale

Different LLM providers use distinct and incompatible API schemas. This module provides a unified, provider-agnostic format to facilitate these interactions. A message to or from a model is simply a list of content blocks, allowing for the natural interleaving of text, images, and other content in a single ordered sequence.

An adapter for a specific provider is responsible for translating this standard list of blocks into the format required by its API.

Extensibility

Data not yet mapped to a standard block may be represented using the NonStandardContentBlock, which allows for provider-specific data to be included without losing the benefits of type checking and validation.

Furthermore, provider-specific fields within a standard block are fully supported by default in the extras field of each block. This allows for additional metadata to be included without breaking the standard structure. For example, Google's thought signature:

AIMessage(
    content=[
        {
            "type": "text",
            "text": "J'adore la programmation.",
            "extras": {"signature": "EpoWCpc..."},  # Thought signature
        }
    ], ...
)

# Content block definition
# NOTE: `extra_items=Any`
class TextContentBlock(TypedDict, extra_items=Any):
    type: Literal["text"]
    id: NotRequired[str]
    text: str
    annotations: NotRequired[list[Annotation]]
    index: NotRequired[int]

from langchain_core.messages.content import TextContentBlock

# Create a text content block with provider-specific fields
my_block: TextContentBlock = {
    # Add required fields
    "type": "text",
    "text": "Hello, world!",
    # Additional fields not specified in the TypedDict
    # These are valid with PEP 728 and are typed as Any
    "openai_metadata": {"model": "gpt-5.5", "temperature": 0.7},
    "anthropic_usage": {"input_tokens": 10, "output_tokens": 20},
    "custom_field": "any value",
}

# Mutating an existing block to add provider-specific fields
openai_data = my_block["openai_metadata"]  # Type: Any

Example Usage

# Direct construction
from langchain_core.messages.content import TextContentBlock, ImageContentBlock

multimodal_message: AIMessage(
    content_blocks=[
        TextContentBlock(type="text", text="What is shown in this image?"),
        ImageContentBlock(
            type="image",
            url="https://www.langchain.com/images/brand/langchain_logo_text_w_white.png",
            mime_type="image/png",
        ),
    ]
)

# Using factories
from langchain_core.messages.content import create_text_block, create_image_block

multimodal_message: AIMessage(
    content=[
        create_text_block("What is shown in this image?"),
        create_image_block(
            url="https://www.langchain.com/images/brand/langchain_logo_text_w_white.png",
            mime_type="image/png",
        ),
    ]
)

Factory functions offer benefits such as:

• Automatic ID generation (when not provided)
• No need to manually specify the type field