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.
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).
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
}
], ...
)Following widespread adoption of PEP 728, we
intend to add extra_items=Any as a param to Content Blocks. This will signify to
type checkers that additional provider-specific fields are allowed outside of the
extras field, and that will become the new standard approach to adding
provider-specific metadata.
Example with PEP 728 provider-specific fields:
# 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: AnyExample 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:
type fieldDerivations of standard content blocks from Google (VertexAI) content.
Derivations of standard content blocks from OpenAI content.
Derivations of standard content blocks from Google (GenAI) content.
Derivations of standard content blocks from Amazon (Bedrock Converse) content.
Derivations of standard content blocks from Bedrock content.
Derivations of standard content blocks from Groq content.
Derivations of standard content blocks from Anthropic content.
Derivations of standard content blocks from LangChain v0 multimodal content.