The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
docs(core): refresh `content.py` docstrings (#34546)
Mason Daugherty2bbe4216e0f6
diff --git a/libs/core/langchain_core/messages/content.py b/libs/core/langchain_core/messages/content.pyindex 27a1323ed1..82fe73eb87 100644--- a/libs/core/langchain_core/messages/content.py+++ b/libs/core/langchain_core/messages/content.py@@ -1,18 +1,14 @@"""Standard, multimodal content blocks for Large Language Model I/O.-!!! warning- This module is under active development. The API is unstable and subject to- change in future releases.--This module provides standardized data structures for representing inputs to and-outputs from LLMs. The core abstraction is the **Content Block**, a `TypedDict`.+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.+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 ofblocks into the format required by its API.@@ -25,16 +21,27 @@ without losing the benefits of type checking and validation.Furthermore, provider-specific fields **within** a standard block are fully supportedby default in the `extras` field of each block. This allows for additional metadata-to be included without breaking the standard structure.+to be included without breaking the standard structure. For example, Google's thought+signature:++```python+AIMessage(+ content=[+ {+ "type": "text",+ "text": "J'adore la programmation.",+ "extras": {"signature": "EpoWCpc..."}, # Thought signature+ }+ ], ...+)+```-!!! warning- Do not heavily rely on the `extras` field for provider-specific data! This field- is subject to deprecation in future releases as we move towards PEP 728.!!! note+Following widespread adoption of [PEP 728](https://peps.python.org/pep-0728/), we- will 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+ 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 addingprovider-specific metadata.@@ -72,30 +79,10 @@ to be included without breaking the standard structure.openai_data = my_block["openai_metadata"] # Type: Any```- PEP 728 is enabled with `# type: ignore[call-arg]` comments to suppress- warnings from type checkers that don't yet support it. The functionality works- correctly in Python 3.13+ and will be fully supported as the ecosystem catches- up.--**Key Block Types**--The module defines several types of content blocks, including:--- `TextContentBlock`: Standard text output.-- `Citation`: For annotations that link text output to a source document.-- `ToolCall`: For function calling.-- `ReasoningContentBlock`: To capture a model's thought process.-- Multimodal data:- - `ImageContentBlock`- - `AudioContentBlock`- - `VideoContentBlock`- - `PlainTextContentBlock` (e.g. .txt or .md files)- - `FileContentBlock` (e.g. PDFs, etc.)-**Example Usage**```python-# Direct construction:+# Direct constructionfrom langchain_core.messages.content import TextContentBlock, ImageContentBlockmultimodal_message: AIMessage(@@ -109,7 +96,7 @@ multimodal_message: AIMessage(])-# Using factories:+# Using factoriesfrom langchain_core.messages.content import create_text_block, create_image_blockmultimodal_message: AIMessage(@@ -124,6 +111,7 @@ multimodal_message: AIMessage(```Factory functions offer benefits such as:+- Automatic ID generation (when not provided)- No need to manually specify the `type` field"""@@ -139,30 +127,30 @@ class Citation(TypedDict):"""Annotation for citing data from a document.!!! note+`start`/`end` indices refer to the **response text**,not the source text. This means that the indices are relative to the model'sresponse, not the original document (as specified in the `url`).!!! note "Factory function"+`create_citation` may also be used as a factory to create a `Citation`.Benefits include:* Automatic ID generation (when not provided)* Required arguments strictly validated at creation time-"""type: Literal["citation"]"""Type of the content block. Used for discrimination."""id: NotRequired[str]- """Content block identifier.+ """Unique identifier for this content block.Either:- - Generated by the provider (e.g., OpenAI's file ID)+ - Generated by the provider- Generated by LangChain upon creation (`UUID4` prefixed with `'lc_'`))-"""url: NotRequired[str]@@ -200,13 +188,12 @@ class NonStandardAnnotation(TypedDict):"""Type of the content block. Used for discrimination."""id: NotRequired[str]- """Content block identifier.+ """Unique identifier for this content block.Either:- - Generated by the provider (e.g., OpenAI's file ID)+ - Generated by the provider- Generated by LangChain upon creation (`UUID4` prefixed with `'lc_'`))-"""value: dict[str, Any]@@ -224,25 +211,24 @@ class TextContentBlock(TypedDict):from a language model or the text of a user message.!!! note "Factory function"+`create_text_block` may also be used as a factory to create a`TextContentBlock`. Benefits include:* Automatic ID generation (when not provided)* Required arguments strictly validated at creation time-"""type: Literal["text"]"""Type of the content block. Used for discrimination."""id: NotRequired[str]- """Content block identifier.+ """Unique identifier for this content block.Either:- - Generated by the provider (e.g., OpenAI's file ID)+ - Generated by the provider- Generated by LangChain upon creation (`UUID4` prefixed with `'lc_'`))-"""text: str@@ -270,12 +256,12 @@ class ToolCall(TypedDict):and an identifier of "123".!!! note "Factory function"+`create_tool_call` may also be used as a factory to create a`ToolCall`. Benefits include:* Automatic ID generation (when not provided)* Required arguments strictly validated at creation time-"""type: Literal["tool_call"]@@ -286,7 +272,6 @@ class ToolCall(TypedDict):An identifier is needed to associate a tool call request with a toolcall result in events when multiple concurrent tool calls are made.-"""# TODO: Consider making this NotRequired[str] in the future.@@ -332,8 +317,8 @@ class ToolCallChunk(TypedDict):An identifier is needed to associate a tool call request with a toolcall result in events when multiple concurrent tool calls are made.-"""+ # TODO: Consider making this NotRequired[str] in the future.name: str | None"""The name of the tool to be called."""@@ -353,7 +338,6 @@ class InvalidToolCall(TypedDict):Here we add an `error` key to surface errors made during generation(e.g., invalid JSON arguments.)-"""# TODO: Consider making fields NotRequired[str] in the future.@@ -366,8 +350,8 @@ class InvalidToolCall(TypedDict):An identifier is needed to associate a tool call request with a toolcall result in events when multiple concurrent tool calls are made.-"""+ # TODO: Consider making this NotRequired[str] in the future.name: str | None"""The name of the tool to be called."""@@ -423,7 +407,13 @@ class ServerToolCallChunk(TypedDict):"""JSON substring of the arguments to the tool call."""id: NotRequired[str]- """An identifier associated with the tool call."""+ """Unique identifier for this server tool call chunk.++ Either:++ - Generated by the provider+ - Generated by LangChain upon creation (`UUID4` prefixed with `'lc_'`))+ """index: NotRequired[int | str]"""Index of block in aggregate response. Used during streaming."""@@ -439,7 +429,13 @@ class ServerToolResult(TypedDict):"""Used for discrimination."""id: NotRequired[str]- """An identifier associated with the server tool result."""+ """Unique identifier for this server tool result.++ Either:++ - Generated by the provider+ - Generated by LangChain upon creation (`UUID4` prefixed with `'lc_'`))+ """tool_call_id: str"""ID of the corresponding server tool call."""@@ -461,25 +457,24 @@ class ReasoningContentBlock(TypedDict):"""Reasoning output from a LLM.!!! note "Factory function"+`create_reasoning_block` may also be used as a factory to create a`ReasoningContentBlock`. Benefits include:* Automatic ID generation (when not provided)* Required arguments strictly validated at creation time-"""type: Literal["reasoning"]"""Type of the content block. Used for discrimination."""id: NotRequired[str]- """Content block identifier.+ """Unique identifier for this content block.Either:- - Generated by the provider (e.g., OpenAI's file ID)+ - Generated by the provider- Generated by LangChain upon creation (`UUID4` prefixed with `'lc_'`))-"""reasoning: NotRequired[str]@@ -487,7 +482,6 @@ class ReasoningContentBlock(TypedDict):Either the thought summary or the raw reasoning text itself. This is often parsedfrom `<think>` tags in the model's response.-"""index: NotRequired[int | str]@@ -504,35 +498,38 @@ class ImageContentBlock(TypedDict):"""Image data.!!! note "Factory function"+`create_image_block` may also be used as a factory to create an`ImageContentBlock`. Benefits include:* Automatic ID generation (when not provided)* Required arguments strictly validated at creation time-"""type: Literal["image"]"""Type of the content block. Used for discrimination."""id: NotRequired[str]- """Content block identifier.+ """Unique identifier for this content block.Either:- - Generated by the provider (e.g., OpenAI's file ID)+ - Generated by the provider- Generated by LangChain upon creation (`UUID4` prefixed with `'lc_'`))-"""file_id: NotRequired[str]- """ID of the image file, e.g., from a file storage system."""+ """Reference to the image in an external file storage system.++ For example, OpenAI or Anthropic's Files API.+ """mime_type: NotRequired[str]- """MIME type of the image. Required for base64.+ """MIME type of the image.- [Examples from IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#image)+ Required for base64 data.+ [Examples from IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#image)"""index: NotRequired[int | str]@@ -552,35 +549,38 @@ class VideoContentBlock(TypedDict):"""Video data.!!! note "Factory function"+`create_video_block` may also be used as a factory to create a`VideoContentBlock`. Benefits include:* Automatic ID generation (when not provided)* Required arguments strictly validated at creation time-"""type: Literal["video"]"""Type of the content block. Used for discrimination."""id: NotRequired[str]- """Content block identifier.+ """Unique identifier for this content block.Either:- - Generated by the provider (e.g., OpenAI's file ID)+ - Generated by the provider- Generated by LangChain upon creation (`UUID4` prefixed with `'lc_'`))-"""file_id: NotRequired[str]- """ID of the video file, e.g., from a file storage system."""+ """Reference to the video in an external file storage system.++ For example, OpenAI or Anthropic's Files API.+ """mime_type: NotRequired[str]- """MIME type of the video. Required for base64.+ """MIME type of the video.- [Examples from IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#video)+ Required for base64 data.+ [Examples from IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#video)"""index: NotRequired[int | str]@@ -600,34 +600,38 @@ class AudioContentBlock(TypedDict):"""Audio data.!!! note "Factory function"+`create_audio_block` may also be used as a factory to create an`AudioContentBlock`. Benefits include:+* Automatic ID generation (when not provided)* Required arguments strictly validated at creation time-"""type: Literal["audio"]"""Type of the content block. Used for discrimination."""id: NotRequired[str]- """Content block identifier.+ """Unique identifier for this content block.Either:- - Generated by the provider (e.g., OpenAI's file ID)+ - Generated by the provider- Generated by LangChain upon creation (`UUID4` prefixed with `'lc_'`))-"""file_id: NotRequired[str]- """ID of the audio file, e.g., from a file storage system."""+ """Reference to the audio file in an external file storage system.++ For example, OpenAI or Anthropic's Files API.+ """mime_type: NotRequired[str]- """MIME type of the audio. Required for base64.+ """MIME type of the audio.- [Examples from IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#audio)+ Required for base64 data.+ [Examples from IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#audio)"""index: NotRequired[int | str]@@ -647,42 +651,49 @@ class PlainTextContentBlock(TypedDict):"""Plaintext data (e.g., from a `.txt` or `.md` document).!!! note+A `PlainTextContentBlock` existed in `langchain-core<1.0.0`. Although thename has carried over, the structure has changed significantly. The only sharedkeys between the old and new versions are `type` and `text`, though the`type` value has changed from `'text'` to `'text-plain'`.!!! note+Title and context are optional fields that may be passed to the model. SeeAnthropic [example](https://platform.claude.com/docs/en/build-with-claude/citations#citable-vs-non-citable-content).!!! note "Factory function"+`create_plaintext_block` may also be used as a factory to create a`PlainTextContentBlock`. Benefits include:* Automatic ID generation (when not provided)* Required arguments strictly validated at creation time-"""type: Literal["text-plain"]"""Type of the content block. Used for discrimination."""id: NotRequired[str]- """Content block identifier.+ """Unique identifier for this content block.Either:- - Generated by the provider (e.g., OpenAI's file ID)+ - Generated by the provider- Generated by LangChain upon creation (`UUID4` prefixed with `'lc_'`))-"""file_id: NotRequired[str]- """ID of the plaintext file, e.g., from a file storage system."""+ """Reference to the plaintext file in an external file storage system.++ For example, OpenAI or Anthropic's Files API.+ """mime_type: Literal["text/plain"]- """MIME type of the file. Required for base64."""+ """MIME type of the file.++ Required for base64 data.+ """index: NotRequired[int | str]"""Index of block in aggregate response. Used during streaming."""@@ -717,35 +728,44 @@ class FileContentBlock(TypedDict):`PlainTextContentBlock`).!!! note "Factory function"+`create_file_block` may also be used as a factory to create a`FileContentBlock`. Benefits include:* Automatic ID generation (when not provided)* Required arguments strictly validated at creation time-"""type: Literal["file"]"""Type of the content block. Used for discrimination."""id: NotRequired[str]- """Content block identifier.+ """Unique identifier for this content block.++ Used for tracking and referencing specific blocks (e.g., during streaming).++ Not to be confused with `file_id`, which references an external file in a+ storage system.Either:- - Generated by the provider (e.g., OpenAI's file ID)+ - Generated by the provider- Generated by LangChain upon creation (`UUID4` prefixed with `'lc_'`))-"""file_id: NotRequired[str]- """ID of the file, e.g., from a file storage system."""+ """Reference to the file in an external file storage system.++ For example, a file ID from OpenAI's Files API or another cloud storage provider.+ This is distinct from `id`, which identifies the content block itself.+ """mime_type: NotRequired[str]- """MIME type of the file. Required for base64.+ """MIME type of the file.- [Examples from IANA](https://www.iana.org/assignments/media-types/media-types.xhtml)+ Required for base64 data.+ [Examples from IANA](https://www.iana.org/assignments/media-types/media-types.xhtml)"""index: NotRequired[int | str]@@ -780,25 +800,24 @@ class NonStandardContentBlock(TypedDict):`value` field.!!! note "Factory function"+`create_non_standard_block` may also be used as a factory to create a`NonStandardContentBlock`. Benefits include:* Automatic ID generation (when not provided)* Required arguments strictly validated at creation time-"""type: Literal["non_standard"]"""Type of the content block. Used for discrimination."""id: NotRequired[str]- """Content block identifier.+ """Unique identifier for this content block.Either:- - Generated by the provider (e.g., OpenAI's file ID)+ - Generated by the provider- Generated by LangChain upon creation (`UUID4` prefixed with `'lc_'`))-"""value: dict[str, Any]@@ -855,7 +874,7 @@ KNOWN_BLOCK_TYPES = {"non_standard",# citation and non_standard_annotation intentionally omitted}-"""These are block types known to `langchain-core>=1.0.0`.+"""These are block types known to `langchain-core >= 1.0.0`.If a block has a type not in this set, it is considered to be provider-specific."""@@ -895,7 +914,6 @@ def is_data_content_block(block: dict) -> bool:Returns:`True` if the content block is a data content block, `False` otherwise.-"""if block.get("type") not in _get_data_content_block_types():return False@@ -940,17 +958,21 @@ def create_text_block(Args:text: The text content of the block.- id: Content block identifier. Generated automatically if not provided.+ id: Content block identifier.++ Generated automatically if not provided.annotations: `Citation`s and other annotations for the text.- index: Index of block in aggregate response. Used during streaming.+ index: Index of block in aggregate response.++ Used during streaming.Returns:A properly formatted `TextContentBlock`.!!! note+The `id` is generated automatically if not provided, using a UUID4 formatprefixed with `'lc_'` to indicate it is a LangChain-generated ID.-"""block = TextContentBlock(type="text",@@ -985,9 +1007,15 @@ def create_image_block(url: URL of the image.base64: Base64-encoded image data.file_id: ID of the image file from a file storage system.- mime_type: MIME type of the image. Required for base64 data.- id: Content block identifier. Generated automatically if not provided.- index: Index of block in aggregate response. Used during streaming.+ mime_type: MIME type of the image.++ Required for base64 data.+ id: Content block identifier.++ Generated automatically if not provided.+ index: Index of block in aggregate response.++ Used during streaming.Returns:A properly formatted `ImageContentBlock`.@@ -997,9 +1025,9 @@ def create_image_block(`mime_type`.!!! note+The `id` is generated automatically if not provided, using a UUID4 formatprefixed with `'lc_'` to indicate it is a LangChain-generated ID.-"""if not any([url, base64, file_id]):msg = "Must provide one of: url, base64, or file_id"@@ -1041,9 +1069,15 @@ def create_video_block(url: URL of the video.base64: Base64-encoded video data.file_id: ID of the video file from a file storage system.- mime_type: MIME type of the video. Required for base64 data.- id: Content block identifier. Generated automatically if not provided.- index: Index of block in aggregate response. Used during streaming.+ mime_type: MIME type of the video.++ Required for base64 data.+ id: Content block identifier.++ Generated automatically if not provided.+ index: Index of block in aggregate response.++ Used during streaming.Returns:A properly formatted `VideoContentBlock`.@@ -1053,9 +1087,9 @@ def create_video_block(`mime_type`.!!! note+The `id` is generated automatically if not provided, using a UUID4 formatprefixed with `'lc_'` to indicate it is a LangChain-generated ID.-"""if not any([url, base64, file_id]):msg = "Must provide one of: url, base64, or file_id"@@ -1101,9 +1135,15 @@ def create_audio_block(url: URL of the audio.base64: Base64-encoded audio data.file_id: ID of the audio file from a file storage system.- mime_type: MIME type of the audio. Required for base64 data.- id: Content block identifier. Generated automatically if not provided.- index: Index of block in aggregate response. Used during streaming.+ mime_type: MIME type of the audio.++ Required for base64 data.+ id: Content block identifier.++ Generated automatically if not provided.+ index: Index of block in aggregate response.++ Used during streaming.Returns:A properly formatted `AudioContentBlock`.@@ -1113,9 +1153,9 @@ def create_audio_block(`mime_type`.!!! note+The `id` is generated automatically if not provided, using a UUID4 formatprefixed with `'lc_'` to indicate it is a LangChain-generated ID.-"""if not any([url, base64, file_id]):msg = "Must provide one of: url, base64, or file_id"@@ -1161,9 +1201,15 @@ def create_file_block(url: URL of the file.base64: Base64-encoded file data.file_id: ID of the file from a file storage system.- mime_type: MIME type of the file. Required for base64 data.- id: Content block identifier. Generated automatically if not provided.- index: Index of block in aggregate response. Used during streaming.+ mime_type: MIME type of the file.++ Required for base64 data.+ id: Content block identifier.++ Generated automatically if not provided.+ index: Index of block in aggregate response.++ Used during streaming.Returns:A properly formatted `FileContentBlock`.@@ -1173,9 +1219,9 @@ def create_file_block(`mime_type`.!!! note+The `id` is generated automatically if not provided, using a UUID4 formatprefixed with `'lc_'` to indicate it is a LangChain-generated ID.-"""if not any([url, base64, file_id]):msg = "Must provide one of: url, base64, or file_id"@@ -1225,16 +1271,20 @@ def create_plaintext_block(file_id: ID of the plaintext file from a file storage system.title: Title of the text data.context: Context or description of the text content.- id: Content block identifier. Generated automatically if not provided.- index: Index of block in aggregate response. Used during streaming.+ id: Content block identifier.++ Generated automatically if not provided.+ index: Index of block in aggregate response.++ Used during streaming.Returns:A properly formatted `PlainTextContentBlock`.!!! note+The `id` is generated automatically if not provided, using a UUID4 formatprefixed with `'lc_'` to indicate it is a LangChain-generated ID.-"""block = PlainTextContentBlock(type="text-plain",@@ -1277,16 +1327,20 @@ def create_tool_call(Args:name: The name of the tool to be called.args: The arguments to the tool call.- id: An identifier for the tool call. Generated automatically if not provided.- index: Index of block in aggregate response. Used during streaming.+ id: An identifier for the tool call.++ Generated automatically if not provided.+ index: Index of block in aggregate response.++ Used during streaming.Returns:A properly formatted `ToolCall`.!!! note+The `id` is generated automatically if not provided, using a UUID4 formatprefixed with `'lc_'` to indicate it is a LangChain-generated ID.-"""block = ToolCall(type="tool_call",@@ -1315,16 +1369,20 @@ def create_reasoning_block(Args:reasoning: The reasoning text or thought summary.- id: Content block identifier. Generated automatically if not provided.- index: Index of block in aggregate response. Used during streaming.+ id: Content block identifier.++ Generated automatically if not provided.+ index: Index of block in aggregate response.++ Used during streaming.Returns:A properly formatted `ReasoningContentBlock`.!!! note+The `id` is generated automatically if not provided, using a UUID4 formatprefixed with `'lc_'` to indicate it is a LangChain-generated ID.-"""block = ReasoningContentBlock(type="reasoning",@@ -1360,15 +1418,17 @@ def create_citation(start_index: Start index in the response text where citation applies.end_index: End index in the response text where citation applies.cited_text: Excerpt of source text being cited.- id: Content block identifier. Generated automatically if not provided.+ id: Content block identifier.++ Generated automatically if not provided.Returns:A properly formatted `Citation`.!!! note+The `id` is generated automatically if not provided, using a UUID4 formatprefixed with `'lc_'` to indicate it is a LangChain-generated ID.-"""block = Citation(type="citation", id=ensure_id(id))@@ -1400,16 +1460,20 @@ def create_non_standard_block(Args:value: Provider-specific content data.- id: Content block identifier. Generated automatically if not provided.- index: Index of block in aggregate response. Used during streaming.+ id: Content block identifier.++ Generated automatically if not provided.+ index: Index of block in aggregate response.++ Used during streaming.Returns:A properly formatted `NonStandardContentBlock`.!!! note+The `id` is generated automatically if not provided, using a UUID4 formatprefixed with `'lc_'` to indicate it is a LangChain-generated ID.-"""block = NonStandardContentBlock(type="non_standard",