ai

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

Merge multiple message contents.

Best-effort parsing of tool chunks.

Best-effort parsing of tools.

Create an invalid tool call.

Create a tool call.

Create a tool call chunk.

Merge dictionaries.

Merge many dicts, handling specific scenarios where a key exists in both dictionaries but has a value of None in 'left'. In such cases, the method uses the value from 'right' for that key in the merged dictionary.

Add many lists, handling None.

Parse a JSON string that may be missing closing braces.

Add multiple AIMessageChunks together.

Recursively add two UsageMetadata objects.

Recursively subtract two UsageMetadata objects.

Token counts cannot be negative so the actual operation is max(left - right, 0).

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.

Allowance for errors made by LLM.

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

Represents an AI's request to call a tool.

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.

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).

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-4", "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