pydantic_ai.messages
The structure of ModelMessage can be shown as a graph:
graph RL
SystemPromptPart(SystemPromptPart) --- ModelRequestPart
UserPromptPart(UserPromptPart) --- ModelRequestPart
ToolReturnPart(ToolReturnPart) --- ModelRequestPart
RetryPromptPart(RetryPromptPart) --- ModelRequestPart
ToolAvailabilityDeltaPart(ToolAvailabilityDeltaPart) --- ModelRequestPart
TextPart(TextPart) --- ModelResponsePart
ToolCallPart(ToolCallPart) --- ModelResponsePart
ThinkingPart(ThinkingPart) --- ModelResponsePart
ModelRequestPart("ModelRequestPart<br>(Union)") --- ModelRequest
ModelRequest("ModelRequest(parts=list[...])") --- ModelMessage
ModelResponsePart("ModelResponsePart<br>(Union)") --- ModelResponse
ModelResponse("ModelResponse(parts=list[...])") --- ModelMessage("ModelMessage<br>(Union)")
A system prompt, generally written by the application developer.
This gives the model context and guidance on how to respond.
The content of the prompt.
Type: str
The timestamp of the prompt.
Type: datetime Default: field(default_factory=_now_utc)
The ref of the dynamic system prompt function that generated this part.
Only set if system prompt is dynamic, see system_prompt for more information.
Type: str | None Default: None
Part type identifier, this is available on all parts as a discriminator.
Type: Literal[‘system-prompt’] Default: 'system-prompt'
Bases: ABC
Abstract base class for any URL-based file.
The URL of the file.
Type: str
Controls whether the file is downloaded and how SSRF protection is applied:
- If
False, the URL is sent directly to providers that support it. For providers that don’t, the file is downloaded with SSRF protection (blocks private IPs and cloud metadata). - If
True, the file is always downloaded with SSRF protection (blocks private IPs and cloud metadata). - If
'allow-local', the file is always downloaded, allowing private IPs but still blocking cloud metadata.
Type: ForceDownloadMode Default: False
Vendor-specific metadata for the file.
Supported by:
GoogleModel:VideoUrl.vendor_metadatais used asvideo_metadata: https://ai.google.dev/gemini-api/docs/video-understanding#customize-video-processing, andvendor_metadata['media_resolution']is forwarded as the per-Partmedia_resolutionfield for any file type: https://ai.google.dev/gemini-api/docs/media-resolutionOpenAIChatModel,OpenAIResponsesModel:ImageUrl.vendor_metadata['detail']is used asdetailsetting for imagesXaiModel:ImageUrl.vendor_metadata['detail']is used asdetailsetting for imagesGroqModel:ImageUrl.vendor_metadata['detail']is used asdetailsetting for imagesMistralModel:ImageUrl.vendor_metadata['detail']is used asdetailsetting for images
Type: dict[str, Any] | None Default: None
Return the media type of the file, based on the URL or the provided media_type.
Type: str
The identifier of the file, such as a unique ID.
This identifier can be provided to the model in a message to allow it to refer to this file in a tool call argument,
and the tool can look up the file in question by iterating over the message history and finding the matching FileUrl.
This identifier is only automatically passed to the model when the FileUrl is returned by a tool.
If you’re passing the FileUrl as a user message, it’s up to you to include a separate text part with the identifier,
e.g. “This is file <identifier>:” preceding the FileUrl.
It’s also included in inline-text delimiters for providers that require inlining text documents, so the model can distinguish multiple files.
Type: str
The file format.
Type: str
Bases: FileUrl
A URL to a video.
The URL of the video.
Type: str
Type identifier, this is available on all parts as a discriminator.
Type: Literal[‘video-url’] Default: 'video-url'
True if the URL has a YouTube domain.
Type: bool
The file format of the video.
The choice of supported formats were based on the Bedrock Converse API. Other APIs don’t require to use a format.
Type: VideoFormat
Bases: FileUrl
A URL to an audio file.
The URL of the audio file.
Type: str
Type identifier, this is available on all parts as a discriminator.
Type: Literal[‘audio-url’] Default: 'audio-url'
The file format of the audio file.
Type: AudioFormat
Bases: FileUrl
A URL to an image.
The URL of the image.
Type: str
Type identifier, this is available on all parts as a discriminator.
Type: Literal[‘image-url’] Default: 'image-url'
The file format of the image.
The choice of supported formats were based on the Bedrock Converse API. Other APIs don’t require to use a format.
Type: ImageFormat
Bases: FileUrl
The URL of the document.
The URL of the document.
Type: str
Type identifier, this is available on all parts as a discriminator.
Type: Literal[‘document-url’] Default: 'document-url'
The file format of the document.
The choice of supported formats were based on the Bedrock Converse API. Other APIs don’t require to use a format.
Type: DocumentFormat
String content that is tagged with additional metadata.
This is useful for including metadata that can be accessed programmatically by the application, but is not sent to the LLM.
The content that is sent to the LLM.
Type: str
Additional data that can be accessed programmatically by the application but is not sent to the LLM.
ModelMessagesTypeAdapter preserves this field, but as application-only data it is not
guaranteed to survive a round-trip through the UI adapters; see
Storing and loading messages.
Type: Any Default: None
Type identifier, this is available on all parts as a discriminator.
Type: Literal[‘text-content’] Default: 'text-content'
Binary content, e.g. an audio or image file.
The binary file data.
Use .base64 to get the base64-encoded string.
Type: bytes
The media type of the binary data.
Type: AudioMediaType | ImageMediaType | DocumentMediaType | str
Vendor-specific metadata for the file.
Supported by:
GoogleModel:BinaryContent.vendor_metadatais used asvideo_metadata: https://ai.google.dev/gemini-api/docs/video-understanding#customize-video-processing, andBinaryContent.vendor_metadata['media_resolution']is forwarded as the per-Partmedia_resolutionfield: https://ai.google.dev/gemini-api/docs/media-resolutionOpenAIChatModel,OpenAIResponsesModel:BinaryContent.vendor_metadata['detail']is used asdetailsetting for imagesXaiModel:BinaryContent.vendor_metadata['detail']is used asdetailsetting for imagesGroqModel:BinaryContent.vendor_metadata['detail']is used asdetailsetting for imagesMistralModel:BinaryContent.vendor_metadata['detail']is used asdetailsetting for images
Type: dict[str, Any] | None Default: None
Type identifier, this is available on all parts as a discriminator.
Type: Literal[‘binary’] Default: 'binary'
Identifier for the binary content, such as a unique ID.
This identifier can be provided to the model in a message to allow it to refer to this file in a tool call argument,
and the tool can look up the file in question by iterating over the message history and finding the matching BinaryContent.
This identifier is only automatically passed to the model when the BinaryContent is returned by a tool.
If you’re passing the BinaryContent as a user message, it’s up to you to include a separate text part with the identifier,
e.g. “This is file <identifier>:” preceding the BinaryContent.
It’s also included in inline-text delimiters for providers that require inlining text documents, so the model can distinguish multiple files.
Type: str
Convert the BinaryContent to a data URI.
Type: str
Return the binary data as a base64-encoded string. Default encoding is UTF-8.
Type: str
Return True if the media type is an audio type.
Type: bool
Return True if the media type is an image type.
Type: bool
Return True if the media type is a video type.
Type: bool
Return True if the media type is a document type.
Type: bool
The file format of the binary content.
Type: str
@staticmethod
def narrow_type(bc: BinaryContent) -> BinaryContent | BinaryImage
Narrow the type of the BinaryContent to BinaryImage if it’s an image.
@classmethod
def from_data_uri(cls, data_uri: str) -> BinaryContent
Create a BinaryContent from a data URI.
@classmethod
def from_path(cls, path: PathLike[str]) -> BinaryContent
Create a BinaryContent from a path.
Defaults to ‘application/octet-stream’ if the media type cannot be inferred.
FileNotFoundError— if the file does not exist.PermissionError— if the file cannot be read.
Bases: BinaryContent
Binary content that’s guaranteed to be an image.
Bases: BinaryContent
Binary content that’s guaranteed to be audio.
A cache point marker for prompt caching.
Can be inserted into UserPromptPart.content to mark cache boundaries. Models that don’t support caching will filter these out.
Supported by:
- Anthropic
- Amazon Bedrock (Converse API)
- OpenAI (GPT-5.6 models)
- OpenRouter (Anthropic and Gemini models via
OpenRouterModel, plus OpenAI GPT-5.6 models when usingOpenAIChatModelorOpenAIResponsesModelwithOpenRouterProvider)
Type identifier, this is available on all parts as a discriminator.
Type: Literal[‘cache-point’] Default: 'cache-point'
The cache time-to-live, either “5m” (5 minutes) or “1h” (1 hour).
Supported by:
- Anthropic — see https://docs.claude.com/en/docs/build-with-claude/prompt-caching#1-hour-cache-duration for more information.
- Amazon Bedrock (Converse API) — see https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html for more information.
- OpenAI ignores this per-marker value and uses the request-wide
openai_prompt_cache_options['ttl']setting instead. - OpenRouter with Anthropic models (automatically omitted for Gemini models, which do not support explicit TTL).
Type: Literal[‘5m’, ‘1h’] Default: '5m'
A reference to a file uploaded to a provider’s file storage by ID.
This allows referencing files that have been uploaded via provider-specific file APIs rather than providing the file content directly.
Supported by:
AnthropicModelOpenAIChatModelOpenAIResponsesModelBedrockConverseModelGoogleModel(Gemini API: Files API URIs, Google Cloud: GCSgs://URIs)XaiModel
The provider-specific file identifier.
For most providers, this is the file ID returned by the provider’s upload API.
For GoogleModel (Google Cloud), this must be a GCS URI (gs://bucket/path).
For GoogleModel (Gemini API), this must be a Google Files API URI (https://generativelanguage.googleapis.com/...).
For BedrockConverseModel, this must be an S3 URI (s3://bucket/key).
Type: str
The provider this file belongs to.
This is required because file IDs are not portable across providers, and using a file ID with the wrong provider will always result in an error.
Tip: Use model.system to get the provider name dynamically.
Type: UploadedFileProviderName
Vendor-specific metadata for the file.
The expected shape of this dictionary depends on the provider:
Supported by:
GoogleModel: used asvideo_metadatafor video files, andUploadedFile.vendor_metadata['media_resolution']is forwarded as the per-Partmedia_resolutionfield: https://ai.google.dev/gemini-api/docs/media-resolutionOpenAIResponsesModel:UploadedFile.vendor_metadata['detail']is used asdetailsetting for image files
Type: dict[str, Any] | None Default: None
Type identifier, this is available on all parts as a discriminator.
Type: Literal[‘uploaded-file’] Default: 'uploaded-file'
Return the media type of the file, inferred from file_id if not explicitly provided.
Note: Inference relies on the file extension in file_id.
For opaque file IDs (e.g., 'file-abc123'), the media type will default to 'application/octet-stream'.
Inference relies on Python’s mimetypes module, whose results may vary across platforms.
Required by some providers (e.g., Bedrock) for certain file types.
Type: str
The identifier of the file, such as a unique ID.
This identifier can be provided to the model in a message to allow it to refer to this file in a tool call argument,
and the tool can look up the file in question by iterating over the message history and finding the matching UploadedFile.
This identifier is only automatically passed to the model when the UploadedFile is returned by a tool.
If you’re passing the UploadedFile as a user message, it’s up to you to include a separate text part with the identifier,
e.g. “This is file <identifier>:” preceding the UploadedFile.
Type: str
A general-purpose media-type-to-format mapping.
Maps media types to format strings (e.g. 'image/png' -> 'png'). Covers image, video,
audio, and document types. Currently used by Bedrock, which requires explicit format strings.
Type: str
Bases: Generic[_ToolReturnValueT]
A structured tool return that separates the tool result from additional content sent to the model.
Can be parameterized with a type to enable return schema generation:
ToolReturn[User]— generates a return schema forUserToolReturn(bare) — no return schema generated
The return value to be used in the tool response.
Type: ToolReturnContent
Content sent to the model as a separate UserPromptPart.
Use this when you want content to appear outside the tool result message.
For multimodal content that should be sent natively in the tool result,
return it directly from the tool function or include it in return_value.
Type: str | Sequence[UserContent] | None Default: None
Additional data accessible by the application but not sent to the LLM.
Type: Any Default: None
Names of deferred tools made available by this tool call.
The names are recorded verbatim in message history in a sibling
ToolAvailabilityDeltaPart, then filtered
against the currently served tool definitions at render time. A name that matches no deferred
tool, such as a typo or an always-visible tool, is a silent no-op by design.
Type: list[str] | None Default: None
A user prompt, generally written by the end user.
Content comes from the user_prompt parameter of Agent.run,
Agent.run_sync, and Agent.run_stream.
The content of the prompt.
Type: str | Sequence[UserContent]
The timestamp of the prompt.
Type: datetime Default: field(default_factory=_now_utc)
Part type identifier, this is available on all parts as a discriminator.
Type: Literal[‘user-prompt’] Default: 'user-prompt'
Base class for tool return parts.
The name of the tool that was called.
Type: str
The tool return content, which may include multimodal files.
Type: ToolReturnContent
The tool call identifier, this is used by some models including OpenAI.
In case the tool call id is not provided by the model, Pydantic AI will generate a random one.
Type: str Default: field(default_factory=_generate_tool_call_id)
Discriminator for the typed subclass of this part (e.g. 'tool-search').
None for any part without a typed subclass — including all user-defined tools and all
native tools without a dedicated typed call/return shape. Subclasses that pin this to a
ToolPartKind literal:
ToolSearchCallPart/ToolSearchReturnPart—'tool-search'NativeToolSearchCallPart/NativeToolSearchReturnPart—'tool-search'
Type: ToolPartKind | None Default: None
Additional data accessible by the application but not sent to the LLM.
Type: Any Default: None
The timestamp, when the tool returned.
Type: datetime Default: field(default_factory=_now_utc)
The outcome of the tool call.
'success': The tool executed successfully.'failed': The tool call failed — the tool raised an error during execution (the common case), or an args validator or tool hook reported a failure viaToolFailed.'denied': The tool call was denied — either by the approval mechanism or by aHandleDeferredToolCallshandler returningToolDenied.'interrupted': The tool call did not produce a result because the run was interrupted (e.g. a cancelled stream or a crash mid-execution); synthesized during message-history repair.
Only 'failed' is mapped to a provider’s native error channel (e.g. Anthropic is_error,
Bedrock status='error'). A denial is a deliberate policy decision rather than a runtime error,
while an interruption means no result was produced. Both are sent as ordinary results; their
content tells the model what happened without suggesting a transient tool failure.
Type: Literal[‘success’, ‘failed’, ‘denied’, ‘interrupted’] Default: 'success'
The multimodal file parts from content (ImageUrl, AudioUrl, DocumentUrl, VideoUrl, BinaryContent).
Type: list[MultiModalContent]
def content_items(*, mode: Literal['raw'] = 'raw') -> list[ToolReturnContent]
def content_items(
*,
mode: Literal['str'],
wrap_if_error: bool = True,
) -> list[str | MultiModalContent]
def content_items(
*,
mode: Literal['jsonable'],
wrap_if_error: bool = True,
) -> list[Any | MultiModalContent]
Return content as a flat list for iteration, with optional serialization.
list[ToolReturnContent] | list[str | MultiModalContent] | list[Any | MultiModalContent]
mode : Literal[‘raw’, ‘str’, ‘jsonable’] Default: 'raw'
Controls serialization of non-file items:
'raw': No serialization. Returns items as-is.'str': Non-file items are serialized to strings viatool_return_ta. File items (MultiModalContent) pass through unchanged.'jsonable': Non-file items are serialized to JSON-compatible Python objects viatool_return_ta. File items pass through unchanged.
wrap_if_error : bool Default: True
Whether to wrap failed tool returns in an {"error": ...} object (ignored in
'raw' mode). When True (the default), a failed return’s non-file data collapses into a
single wrapped error item so providers without a native error channel still see the failure
explicitly; files pass through unchanged. Set this to False when the provider has a native
error channel (e.g. Anthropic is_error) and should receive the content unwrapped.
def model_response_str(*, wrap_if_error: bool = True) -> str
Return a string representation of the data content for the model.
This excludes multimodal files - use .files to get those separately.
wrap_if_error : bool Default: True
Whether to wrap failed tool returns in an {"error": ...} object.
Set this to False when the provider has a native error channel.
def model_response_object(*, wrap_if_error: bool = True) -> dict[str, Any]
Return a dictionary representation of the data content, wrapping non-dict types appropriately.
This excludes multimodal files - use .files to get those separately.
Gemini supports JSON dict return values, but no other JSON types, hence we wrap anything else in a dict.
wrap_if_error : bool Default: True
Whether to wrap failed tool returns in an {"error": ...} object.
Set this to False when the provider has a native error channel.
def structured_content() -> dict[str, Any] | list[Any] | None
Return content as structured JSON data (a dict or list), or None if it has none.
A JSON string is parsed; already-structured content is returned as-is; a plain/non-JSON
string, scalar, or multimodal content yields None (there is no structured payload). A
read-side companion to files and
model_response_object; some
UI wire formats (e.g. AG-UI) transmit tool results as JSON strings, so
narrow_type uses it to recover the
structured payload a typed return subclass expects.
dict[str, Any] | list[Any] | None
def model_response_str_and_user_content(
*,
wrap_if_error: bool = True,
) -> tuple[str, list[UserContent]]
Build a text-only tool result with multimodal files extracted for a trailing user message.
For providers whose tool result API only accepts text. Multimodal files are referenced by identifier in the tool result text (‘See file {id}.’) and included in full in the returned file content list (‘This is file {id}:’ followed by the file).
tuple[str, list[UserContent]]
wrap_if_error : bool Default: True
Whether to wrap failed tool returns in an {"error": ...} object.
Set this to False when the provider has a native error channel.
def has_content() -> bool
Return True if the tool return has content.
Bases: BaseToolReturnPart
A tool return message, this encodes the result of running a tool.
Part type identifier, this is available on all parts as a discriminator.
Type: Literal[‘tool-return’] Default: 'tool-return'
@staticmethod
def narrow_type(
part: ToolReturnPart,
*,
tool_kind: ToolPartKind | None = None,
) -> ToolReturnPart
Promote a base ToolReturnPart to its typed subclass when its tool_kind is registered.
Best-effort: returns the part unchanged when the tool_kind (kwarg or on the part) resolves to
no registered subclass, and strips an unsubstantiated tool_kind when the part’s data doesn’t
validate against that subclass — keeping it on a base part would break a
ModelMessagesTypeAdapter round-trip. For
direct construction; Pydantic deserialization promotes automatically via the discriminated union.
Bases: BaseToolReturnPart
A tool return message from a native tool.
For native tools with a stable cross-provider shape (currently tool_search), a
NativeToolReturnPart may be promoted to a typed subclass like
NativeToolSearchReturnPart
with a narrowed content TypedDict. See NativeToolCallPart for the pattern.
The name of the provider that generated the response.
Required to be set when provider_details is set.
Type: str | None Default: None
Additional data returned by the provider that can’t be mapped to standard fields.
This is used for data that is required to be sent back to APIs, as well as data users may want to access programmatically.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: dict[str, Any] | None Default: None
Part type identifier, this is available on all parts as a discriminator.
Type: Literal[‘builtin-tool-return’] Default: 'builtin-tool-return'
@staticmethod
def narrow_type(
part: NativeToolReturnPart,
*,
tool_kind: ToolPartKind | None = None,
) -> NativeToolReturnPart
Promote a base NativeToolReturnPart to its typed subclass when its tool_kind is registered.
Best-effort: returns the part unchanged when the tool_kind (kwarg or on the part) resolves to
no registered subclass, and strips an unsubstantiated tool_kind when the part’s data doesn’t
validate against that subclass — keeping it on a base part would break a
ModelMessagesTypeAdapter round-trip. For
direct construction; Pydantic deserialization promotes automatically via the discriminated union.
A message back to a model asking it to try again.
This can be sent for a number of reasons:
- Pydantic validation of tool arguments failed, here content is derived from a Pydantic
ValidationError - a tool raised a
ModelRetryexception - no tool was found for the tool name
- the model returned plain text when a structured response was expected
- Pydantic validation of a structured response failed, here content is derived from a Pydantic
ValidationError - an output validator raised a
ModelRetryexception
Details of why and how the model should retry.
If the retry was triggered by a ValidationError, this will be a list of
error details.
Type: list[pydantic_core.ErrorDetails] | str
The name of the tool that was called, if any.
Type: str | None Default: None
The tool call identifier, this is used by some models including OpenAI.
In case the tool call id is not provided by the model, Pydantic AI will generate a random one.
Type: str Default: field(default_factory=_generate_tool_call_id)
The timestamp, when the retry was triggered.
Type: datetime Default: field(default_factory=_now_utc)
Part type identifier, this is available on all parts as a discriminator.
Type: Literal[‘retry-prompt’] Default: 'retry-prompt'
@classmethod
def from_error(
cls,
error: pydantic_core.ValidationError | ModelRetry,
*,
tool_name: str | None = None,
tool_call_id: str | None = None,
) -> RetryPromptPart
Build the retry prompt for a failed tool call or output validation.
This is the exact message the model receives when the error is handled by the agent loop, so anything else presenting the failure (e.g. instrumentation spans) must build it the same way.
def model_response() -> str
Return a string message describing why the retry is requested.
A single instruction block with metadata about its origin.
Instructions are composed of one or more parts, each of which can be static (from a literal string) or dynamic (from a function, template, or toolset). This distinction allows model implementations to make intelligent caching decisions — e.g. Anthropic’s prompt caching can cache the static prefix while leaving dynamic instructions uncached.
The text content of this instruction block.
Type: str
Whether this instruction came from a dynamic source (function, template, or toolset).
Static instructions (dynamic=False) come from literal strings passed to Agent(instructions=...).
Dynamic instructions (dynamic=True) come from @agent.instructions functions, TemplateStr,
or toolset get_instructions() methods.
Type: bool Default: False
Part type identifier, used as a discriminator for deserialization.
Type: Literal[‘instruction’] Default: 'instruction'
@staticmethod
def join(parts: Sequence[InstructionPart]) -> str | None
Join instruction parts into a single string, separated by double newlines.
@staticmethod
def sorted(parts: Sequence[InstructionPart]) -> list[InstructionPart]
Sort instruction parts with static (dynamic=False) before dynamic, preserving relative order.
Records that the set of tools available to the model changed at this point.
Additions only. Withdrawing a tool is not supported yet, because no provider can be told about one
without also invalidating the prompt cache this part exists to protect: Anthropic rejects a
reference to a tool the request doesn’t declare, so a withdrawn tool has to leave the tools
array, and that is itself the invalidation. The name says availability rather than addition so
removals can join once they can be done cache-safely — see
https://github.com/pydantic/pydantic-ai/issues/6985.
Names of tools this point in history reveals.
A reveal is what the model has been shown; whether the tool is callable is the broader availability question, which for a capability-owned tool also asks whether its owning capability is loaded.
Type: Annotated[list[str], pydantic.Field(validation_alias=(pydantic.AliasChoices(tools_added, added)))] Default: field(default_factory=(lambda: []))
The tool call associated with the change, if any.
Type: str | None Default: None
Part type identifier, this is available on all parts as a discriminator.
Type: Literal[‘tool-availability-delta’] Default: 'tool-availability-delta'
def otel_message_parts(
settings: InstrumentationSettings,
) -> list[_otel_messages.MessagePart]
Render the change as trace content.
Tool names are recorded regardless of include_content: they aren’t user content, they’re
already visible in the request’s tool definitions, and a run where the model suddenly can
call something is unreadable without them.
list[_otel_messages.MessagePart]
A request generated by Pydantic AI and sent to a model, e.g. a message from the Pydantic AI app to the model.
The parts of the user message.
Type: Sequence[ModelRequestPart]
The timestamp when the request was sent to the model.
Type: datetime | None Default: None
The instructions string for this request, rendered from structured instruction parts.
Type: str | None Default: None
Message type identifier, this is available on all parts as a discriminator.
Type: Literal[‘request’] Default: 'request'
The unique identifier of the agent run in which this message originated.
Type: str | None Default: None
The unique identifier of the conversation this message belongs to.
A conversation spans potentially multiple agent runs that share message history.
Emitted as the gen_ai.conversation.id OpenTelemetry span attribute on the agent run.
Type: str | None Default: None
Additional data that can be accessed programmatically by the application but is not sent to the LLM.
Type: dict[str, Any] | None Default: None
Lifecycle state of the request.
Set to 'interrupted' when the request was being assembled (e.g. collecting tool returns) and
the run was abnormally terminated by an exception or cancellation before the request was sent to the model.
Appears in capture_run_messages output so consumers can detect partial state.
Type: ModelRequestState Default: 'complete'
@classmethod
def user_text_prompt(
cls,
user_prompt: str,
*,
instructions: str | None = None,
) -> ModelRequest
Create a ModelRequest with a single user prompt as text.
A plain text response from a model.
The text content of the response.
Type: str
An optional identifier of the text part.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: str | None Default: None
The name of the provider that generated the response.
Required to be set when provider_details or id is set.
Type: str | None Default: None
Additional data returned by the provider that can’t be mapped to standard fields.
This is used for data that is required to be sent back to APIs, as well as data users may want to access programmatically.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: dict[str, Any] | None Default: None
Part type identifier, this is available on all parts as a discriminator.
Type: Literal[‘text’] Default: 'text'
def has_content() -> bool
Return True if the text content is non-empty.
A thinking response from a model.
The thinking content of the response.
Type: str
The identifier of the thinking part.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: str | None Default: None
The signature of the thinking.
Supported by:
- Anthropic (corresponds to the
signaturefield) - Bedrock (corresponds to the
signaturefield) - Google (corresponds to the
thought_signaturefield) - OpenAI (corresponds to the
encrypted_contentfield)
When this field is set, provider_name is required to identify the provider that generated this data.
Type: str | None Default: None
The name of the provider that generated the response.
Signatures are only sent back to the same provider.
Required to be set when provider_details, id or signature is set.
Type: str | None Default: None
Additional data returned by the provider that can’t be mapped to standard fields.
This is used for data that is required to be sent back to APIs, as well as data users may want to access programmatically.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: dict[str, Any] | None Default: None
Part type identifier, this is available on all parts as a discriminator.
Type: Literal[‘thinking’] Default: 'thinking'
def has_content() -> bool
Return True if the thinking content is non-empty.
A compaction part that summarizes previous conversation history.
Compaction parts contain an opaque or readable summary of prior messages, produced by provider-specific compaction mechanisms. They must be round-tripped back to the same provider in subsequent requests.
For Anthropic, content contains a readable text summary.
For OpenAI, content is None and the encrypted data is stored in provider_details.
The compaction summary text, if available.
For Anthropic: a readable text summary of compacted messages.
For OpenAI: None (the compacted content is encrypted and stored in provider_details).
Type: str | None Default: None
The identifier of the compaction part.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: str | None Default: None
The name of the provider that generated the compaction.
Compaction data is only sent back to the same provider.
Required to be set when provider_details or id is set.
Type: str | None Default: None
Additional data returned by the provider that can’t be mapped to standard fields.
For OpenAI: contains encrypted_content and other fields from ResponseCompactionItem.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: dict[str, Any] | None Default: None
Part type identifier, this is available on all parts as a discriminator.
Type: Literal[‘compaction’] Default: 'compaction'
def has_content() -> bool
Return True if the compaction content is non-empty.
A file response from a model.
The file content of the response.
Type: Annotated[BinaryContent, pydantic.AfterValidator(BinaryContent.narrow_type)]
The identifier of the file part.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: str | None Default: None
The name of the provider that generated the response.
Required to be set when provider_details or id is set.
Type: str | None Default: None
Additional data returned by the provider that can’t be mapped to standard fields.
This is used for data that is required to be sent back to APIs, as well as data users may want to access programmatically.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: dict[str, Any] | None Default: None
Part type identifier, this is available on all parts as a discriminator.
Type: Literal[‘file’] Default: 'file'
def has_content() -> bool
Return True if the file content is non-empty.
Spoken audio exchanged during a realtime session, paired with its transcript.
This part is a member of both ModelRequestPart and
ModelResponsePart, distinguished by speaker:
in ModelRequest.parts the speaker is always 'user'; in ModelResponse.parts it is always
'assistant'. This invariant is enforced at runtime when a message is constructed.
Standard (non-realtime) models can’t consume this part directly; when history containing it is
used in an agent run, Model.prepare_messages
converts user-speaker parts to UserPromptParts and
assistant-speaker parts to TextParts.
Whether the audio was spoken by the end user or by the model.
Type: Literal[‘user’, ‘assistant’]
The transcript of the audio. None if transcription was unavailable.
Type: str | None Default: None
The audio data, if retained.
Audio is only retained when the realtime session is configured to do so
(see the audio_retention setting), so this is usually None.
Type: BinaryContent | None Default: None
The offset into this part’s audio where playback was interrupted, in milliseconds.
None when the part was not interrupted. It may also be None for an interrupted turn when
the provider reported the interruption without an offset. This is relative to this part’s audio,
not wall-clock or session-relative time.
Type: int | None Default: None
The provider item ID, used to correlate the part with provider-side conversation items.
Type: str | None Default: None
The name of the provider that generated or transcribed the audio.
Required to be set when provider_details or id is set.
Type: str | None Default: None
Additional data returned by the provider that can’t be mapped to standard fields.
This is used for data that is required to be sent back to APIs, as well as data users may want to access programmatically.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: dict[str, Any] | None Default: None
Part type identifier, this is available on all parts as a discriminator.
Type: Literal[‘speech’] Default: 'speech'
The transcript, or an empty string if transcription was unavailable.
Mirrors TextPart.content so code that renders
message parts generically can treat spoken content like text.
Type: str
def has_content() -> bool
Return True if the part has a transcript or retained audio.
A tool call from a model.
The name of the tool to call.
Type: str
The arguments to pass to the tool.
This is stored either as a JSON string or a Python dictionary depending on how data was received.
Type: str | dict[str, Any] | None Default: None
The tool call identifier, this is used by some models including OpenAI.
In case the tool call id is not provided by the model, Pydantic AI will generate a random one.
Type: str Default: field(default_factory=_generate_tool_call_id)
Discriminator for the typed subclass of this part (e.g. 'tool-search').
See BaseToolReturnPart.tool_kind for
the full semantics.
Type: ToolPartKind | None Default: None
An optional identifier of the tool call part, separate from the tool call ID.
This is used by some APIs like OpenAI Responses.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: str | None Default: None
The name of the provider that generated the response.
Native tool calls are only sent back to the same provider.
Required to be set when provider_details or id is set.
Type: str | None Default: None
Additional data returned by the provider that can’t be mapped to standard fields.
This is used for data that is required to be sent back to APIs, as well as data users may want to access programmatically.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: dict[str, Any] | None Default: None
def args_as_dict(*, raise_if_invalid: bool = False) -> dict[str, Any]
Return the arguments as a Python dictionary.
This is just for convenience with models that require dicts as input.
raise_if_invalid : bool Default: False
If True, a ValueError or AssertionError
caused by malformed or non-object JSON in args will be re-raised. When
False (the default), such JSON is handled gracefully by
returning {'INVALID_JSON': '<raw args>'} so that the value
can still be sent to a model API (e.g. during a retry flow)
without crashing.
def args_as_json_str() -> str
Return the arguments as a JSON string.
This is just for convenience with models that require JSON strings as input.
JSON that’s malformed or doesn’t represent an object is handled gracefully by returning
'{"INVALID_JSON":"<raw args>"}', matching args_as_dict,
so that the value can still be sent to a model API (e.g. during a retry flow) instead of being rejected
by one that requires an object.
Because of that, this is not the way to render args that are still streaming in: a partial fragment that only becomes valid JSON once the following deltas are concatenated would be degraded to the wrapper. Emit those verbatim instead, as the UI event streams do.
def has_content() -> bool
Return True if the tool call has content.
Bases: BaseToolCallPart
A tool call from a model.
Part type identifier, this is available on all parts as a discriminator. Note that this is different from ToolCallPartDelta.part_delta_kind.
Type: Literal[‘tool-call’] Default: 'tool-call'
@staticmethod
def narrow_type(
part: ToolCallPart,
*,
tool_kind: ToolPartKind | None = None,
) -> ToolCallPart
Promote a base ToolCallPart to its typed subclass when its tool_kind is registered.
Best-effort: returns the part unchanged when the tool_kind (kwarg or on the part) resolves to
no registered subclass, and strips an unsubstantiated tool_kind when the part’s data doesn’t
validate against that subclass — keeping it on a base part would break a
ModelMessagesTypeAdapter round-trip. For
direct construction; Pydantic deserialization promotes automatically via the discriminated union.
Bases: BaseToolCallPart
A tool call to a native tool.
For native tools with a stable cross-provider shape (currently tool_search), this base
class can be promoted to a typed subclass with a narrowed args TypedDict. See
NativeToolSearchCallPart for the
canonical example.
Adding a typed subclass for a future native tool (see pydantic_ai._tool_search for
a worked example):
- Add a sibling
pydantic_ai/_<name>.pymodule that defines the cross-providerTypedDicts, theNativeToolCallPart/NativeToolReturnPartsubclasses, and registers their narrowers into_NATIVE_CALL_NARROWERS/_NATIVE_RETURN_NARROWERSkeyed bytool_kind. Subclass overridestool_kind: Literal['<emitter>']to match the emittingAbstractNativeTool.kind, and shadowsargs/contentwith a narrower type. - Late-import the new module from this file (alongside the existing tool-search
import) so registration runs whenever
pydantic_ai.messagesis imported. - Add the subclass to
ModelResponsePart’s discriminated union and to_model_response_part_discriminatorso Pydantic deserialization auto-promotes onmodel_validate/model_validate_json.
Dispatch is by tool_kind, not tool_name. This protects users whose tools happen to
share a name with one of ours from accidentally getting their parts promoted (and
failing shape validation against the typed args/content).
The provider_details field carries genuinely non-portable provider extras
(e.g. Anthropic’s strategy: 'bm25' | 'regex' for tool search). Promote a field
to a typed slot in args / content only when at least two of OpenAI, Anthropic,
and Google support it (cf. issue #3885).
MCP server tools land here with tool_kind='mcp_server' (label stays in
tool_name='mcp_server:<label>'); typed-subclass work for MCP is tracked by
issue #3561.
Part type identifier, this is available on all parts as a discriminator.
Type: Literal[‘builtin-tool-call’] Default: 'builtin-tool-call'
@staticmethod
def narrow_type(
part: NativeToolCallPart,
*,
tool_kind: ToolPartKind | None = None,
) -> NativeToolCallPart
Promote a base NativeToolCallPart to its typed subclass when its tool_kind is registered.
Best-effort: returns the part unchanged when the tool_kind (kwarg or on the part) resolves to
no registered subclass, and strips an unsubstantiated tool_kind when the part’s data doesn’t
validate against that subclass — keeping it on a base part would break a
ModelMessagesTypeAdapter round-trip. For
direct construction; Pydantic deserialization promotes automatically via the discriminated union.
A response from a model, e.g. a message from the model to the Pydantic AI app.
The parts of the model message.
Type: Sequence[ModelResponsePart]
Usage information for this single request, as a RequestUsage.
Run-level usage accumulated across all requests in a run (e.g. requests, tool_calls) lives on the run’s
RunUsage, accessible via result.usage(); a RunUsage should not be assigned to this field.
This has a default to make tests easier, and to support loading old messages where usage will be missing.
Type: RequestUsage Default: field(default_factory=RequestUsage)
The name of the model that generated the response.
Type: str | None Default: None
The timestamp when the response was received locally.
This is always a high-precision local datetime. Provider-specific timestamps
(if available) are stored in provider_details['timestamp'].
Type: datetime Default: field(default_factory=_now_utc)
Message type identifier, this is available on all parts as a discriminator.
Type: Literal[‘response’] Default: 'response'
The name of the LLM provider that generated the response.
Type: str | None Default: None
The base URL of the LLM provider that generated the response.
Type: str | None Default: None
Additional data returned by the provider that can’t be mapped to standard fields.
Type: Annotated[dict[str, Any] | None, pydantic.Field(validation_alias=(pydantic.AliasChoices(provider_details, vendor_details)))] Default: None
request ID as specified by the model provider. This can be used to track the specific request to the model.
Type: Annotated[str | None, pydantic.Field(validation_alias=(pydantic.AliasChoices(provider_response_id, vendor_id)))] Default: None
Reason the model finished generating the response, normalized to OpenTelemetry values.
Type: FinishReason | None Default: None
The unique identifier of the agent run in which this message originated.
Type: str | None Default: None
The unique identifier of the conversation this message belongs to.
A conversation spans potentially multiple agent runs that share message history.
Emitted as the gen_ai.conversation.id OpenTelemetry span attribute on the agent run.
Type: str | None Default: None
Additional data that can be accessed programmatically by the application but is not sent to the LLM.
Type: dict[str, Any] | None Default: None
The state of this response, indicating whether it is final or requires further action.
'complete'— The response is done. This is the default.'incomplete'— A streamed response is still in flight or was stopped before completion.'suspended'— The model paused mid-turn and expects a continuation request. The agent graph will automatically send a continuation request. Set by providers that pause mid-turn (e.g. Anthropicpause_turn) or return background/async responses (e.g. OpenAI background mode).'interrupted'— Generation was explicitly stopped before the model finished. Set when a streaming response is cancelled viaStreamedResponse.cancel(), and when a realtime turn is cut off by a barge-in orRealtimeSession.interrupt()— in which case the cut-off point is recorded on the lastSpeechPart.interrupted_at_ms.
Type: ModelResponseState Default: 'complete'
Get the text in the response, including the transcript of anything spoken.
Get the thinking in the response.
Get the files in the response.
Type: list[BinaryContent]
Get the images in the response.
Type: list[BinaryImage]
Get the tool calls in the response.
Type: list[ToolCallPart]
Get the native tool calls and results in the response.
Type: list[tuple[NativeToolCallPart, NativeToolReturnPart]]
def cost() -> genai_types.PriceCalculation
Calculate the cost of the usage.
Uses genai-prices.
genai_types.PriceCalculation
A partial update (delta) for a TextPart to append new text content.
The incremental text content to add to the existing TextPart content.
Type: str
The name of the provider that generated the response.
This is required to be set when provider_details is set and the initial TextPart does not have a provider_name or it has changed.
Type: str | None Default: None
Additional data returned by the provider that can’t be mapped to standard fields.
This is used for data that is required to be sent back to APIs, as well as data users may want to access programmatically.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: dict[str, Any] | None Default: None
Part delta type identifier, used as a discriminator.
Type: Literal[‘text’] Default: 'text'
def apply(part: ModelResponsePart) -> TextPart
Apply this text delta to an existing TextPart.
TextPart — A new TextPart with updated text content.
part : ModelResponsePart
The existing model response part, which must be a TextPart.
ValueError— Ifpartis not aTextPart.
A partial update (delta) for a ThinkingPart to append new thinking content.
The incremental thinking content to add to the existing ThinkingPart content.
Type: str | None Default: None
Optional signature delta.
Note this is never treated as a delta — it can replace None.
Type: str | None Default: None
Optional provider name for the thinking part.
Signatures are only sent back to the same provider.
Required to be set when provider_details is set and the initial ThinkingPart does not have a provider_name or it has changed.
Type: str | None Default: None
Additional data returned by the provider that can’t be mapped to standard fields.
Can be a dict to merge with existing details, or a callable that takes
the existing details and returns updated details. A callable is a transient
merge callback and does not survive JSON serialization (it is emitted as
null); it is resolved to a concrete dict once the delta is applied to a ThinkingPart.
This is used for data that is required to be sent back to APIs, as well as data users may want to access programmatically.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: ProviderDetailsDelta Default: None
Part delta type identifier, used as a discriminator.
Type: Literal[‘thinking’] Default: 'thinking'
def apply(part: ModelResponsePart) -> ThinkingPart
def apply(
part: ModelResponsePart | ThinkingPartDelta,
) -> ThinkingPart | ThinkingPartDelta
Apply this thinking delta to an existing ThinkingPart.
ThinkingPart | ThinkingPartDelta — A new ThinkingPart with updated thinking content.
part : ModelResponsePart | ThinkingPartDelta
The existing model response part, which must be a ThinkingPart.
ValueError— Ifpartis not aThinkingPart.
A partial update (delta) for a ToolCallPart to modify tool name, arguments, or tool call ID.
Incremental text to add to the existing tool name, if any.
Type: str | None Default: None
Incremental data to add to the tool arguments.
If this is a string, it will be appended to existing JSON arguments. If this is a dict, it will be merged with existing dict arguments.
Type: str | dict[str, Any] | None Default: None
Optional tool call identifier, this is used by some models including OpenAI.
Note this is never treated as a delta — it can replace None, but otherwise if a non-matching value is provided an error will be raised.
Type: str | None Default: None
The name of the provider that generated the response.
This is required to be set when provider_details is set and the initial ToolCallPart does not have a provider_name or it has changed.
Type: str | None Default: None
Additional data returned by the provider that can’t be mapped to standard fields.
This is used for data that is required to be sent back to APIs, as well as data users may want to access programmatically.
When this field is set, provider_name is required to identify the provider that generated this data.
Type: dict[str, Any] | None Default: None
Part delta type identifier, used as a discriminator. Note that this is different from ToolCallPart.part_kind.
Type: Literal[‘tool_call’] Default: 'tool_call'
def as_part() -> ToolCallPart | None
Convert this delta to a fully formed ToolCallPart if possible, otherwise return None.
ToolCallPart | None — A ToolCallPart if tool_name_delta is set, otherwise None.
def apply(part: ModelResponsePart) -> ToolCallPart | NativeToolCallPart
def apply(
part: ModelResponsePart | ToolCallPartDelta,
) -> ToolCallPart | NativeToolCallPart | ToolCallPartDelta
Apply this delta to a part or delta, returning a new part or delta with the changes applied.
ToolCallPart | NativeToolCallPart | ToolCallPartDelta — Either a new ToolCallPart or NativeToolCallPart, or an updated ToolCallPartDelta.
part : ModelResponsePart | ToolCallPartDelta
The existing model response part or delta to update.
ValueError— Ifpartis neither aToolCallPart,NativeToolCallPart, nor aToolCallPartDelta.UnexpectedModelBehavior— If applying JSON deltas to dict arguments or vice versa.
A partial update (delta) for a SpeechPart to append transcript text and/or audio data.
Who is speaking, matching the SpeechPart this delta belongs to.
Realtime sessions are duplex: the user’s transcript and the model’s can stream at the same time,
interleaved delta by delta. Carrying the speaker here means rendering a live transcript needs
nothing but the delta itself — no correlating back to an earlier
PartStartEvent.
None only when a delta wasn’t produced by a realtime session.
Type: Literal[‘user’, ‘assistant’] | None Default: None
Transcript text this delta added, if any.
Type: str | None Default: None
The whole transcript of this turn so far, when this delta carries transcript text.
Render this and a live transcript is correct on every provider, with no accumulating of your own.
Speech recognition is revisable — later audio changes how earlier audio is read — so some
providers correct words they already transcribed rather than only adding to them, which an
appended transcript_delta cannot express. Reading this field means never having to know which
providers do that. It also recovers a consumer that missed an earlier delta.
Type: str | None Default: None
A raw audio chunk (e.g. PCM data), if any.
Suitable for live playback; only accumulated on the part if it is retaining audio (see
SpeechPartDelta.apply).
Type: bytes | None Default: None
Part delta type identifier, used as a discriminator.
Type: Literal[‘speech’] Default: 'speech'
def apply(part: ModelResponsePart) -> SpeechPart
Apply this delta to an existing SpeechPart.
transcript replaces the part’s transcript when set, which is how a provider’s revision of
what it already transcribed is applied; otherwise transcript_delta is appended (a part with
transcript=None gets transcript=transcript_delta). audio_chunk is appended to the part’s
retained audio data, but only if the part already has audio set: a part with audio=None is
not retaining audio, so the chunk is intentionally not stored — it remains available on the
delta itself for live playback.
SpeechPart — A new SpeechPart with the delta applied.
part : ModelResponsePart
The existing model response part, which must be a SpeechPart.
ValueError— Ifpartis not aSpeechPart.
An event indicating that a new part has started.
If multiple PartStartEvents are received with the same index,
the new one should fully replace the old one.
The index of the part within the overall response parts list.
Type: int
The newly started ModelResponsePart.
Type: ModelResponsePart
The kind of the previous part, if any.
This is useful for UI event streams to know whether to group parts of the same kind together when emitting events.
Type: Literal[‘text’, ‘thinking’, ‘tool-call’, ‘builtin-tool-call’, ‘builtin-tool-return’, ‘compaction’, ‘file’, ‘speech’] | None Default: None
Event type identifier, used as a discriminator.
Type: Literal[‘part_start’] Default: 'part_start'
An event indicating a delta update for an existing part.
The index of the part within the overall response parts list.
Type: int
The delta to apply to the specified part.
Type: ModelResponsePartDelta
Event type identifier, used as a discriminator.
Type: Literal[‘part_delta’] Default: 'part_delta'
An event indicating that a part is complete.
The index of the part within the overall response parts list.
Type: int
The complete ModelResponsePart.
Type: ModelResponsePart
The kind of the next part, if any.
This is useful for UI event streams to know whether to group parts of the same kind together when emitting events.
Type: Literal[‘text’, ‘thinking’, ‘tool-call’, ‘builtin-tool-call’, ‘builtin-tool-return’, ‘compaction’, ‘file’, ‘speech’] | None Default: None
Event type identifier, used as a discriminator.
Type: Literal[‘part_end’] Default: 'part_end'
An event indicating the response to the current model request matches the output schema and will produce a result.
The name of the output tool that was called. None if the result is from text content and not from a tool.
The tool call ID, if any, that this result is associated with.
Event type identifier, used as a discriminator.
Type: Literal[‘final_result’] Default: 'final_result'
An event indicating that messages enqueued via enqueue were delivered into the run’s message history.
Emitted at delivery time, carrying the delivered message objects themselves — the same objects
held in the run’s message history, exactly as they landed there (with timestamp / run_id /
conversation_id stamped). A history processor that replaces history with new message objects
does not affect the event, but in-place mutation of a delivered message will be visible through it.
The ID of the enqueue call that produced these messages.
Type: str
The messages delivered into the run’s message history.
Type: tuple[ModelMessage, …]
Event type identifier, used as a discriminator.
Type: Literal[‘enqueued_messages’] Default: 'enqueued_messages'
Base class for events emitted when a tool call is about to be invoked.
Match against this in a case to handle FunctionToolCallEvent
and OutputToolCallEvent together.
The tool call to make.
Type: ToolCallPart
Whether the tool arguments passed validation. See the custom validation docs for more info.
True: Schema validation and custom validation (if configured) both passed; args are guaranteed valid.False: Validation was performed and failed.None: Validation was not performed.
Type: bool | None Default: None
An ID used for matching details about the call to its result.
Type: str
Bases: ToolCallEvent
An event indicating the start to a call to a function tool.
Event type identifier, used as a discriminator.
Type: Literal[‘function_tool_call’] Default: 'function_tool_call'
Bases: ToolCallEvent
An event indicating the start of a call to an output tool (the model’s “submit final answer” call).
Event type identifier, used as a discriminator.
Type: Literal[‘output_tool_call’] Default: 'output_tool_call'
Base class for events emitted when a tool call has been completed.
Match against this in a case to handle FunctionToolResultEvent
and OutputToolResultEvent together.
The tool result part that will be sent back to the model.
Type: ToolReturnPart | RetryPromptPart
An ID used to match the result to its original call.
Type: str
Bases: ToolResultEvent
An event indicating the result of a function tool call.
The content that will be sent to the model as a UserPromptPart following the result.
Type: str | Sequence[UserContent] | None Default: None
Event type identifier, used as a discriminator.
Type: Literal[‘function_tool_result’] Default: 'function_tool_result'
An event indicating tools were made available mid-run, carrying the recorded delta part.
This is request-side because the delta is created while executing a tool, after response-part
streaming has finished. It records the post-dedup change, while ToolReturnPart.tools preserves
the caller’s pre-dedup intent, and is emitted for capability loads as well as tool returns.
The tool availability delta part that will be recorded in message history.
Type: ToolAvailabilityDeltaPart
Event type identifier, used as a discriminator.
Type: Literal[‘tool_availability_delta’] Default: 'tool_availability_delta'
Bases: ToolResultEvent
An event indicating the result of an output tool call.
Event type identifier, used as a discriminator.
Type: Literal[‘output_tool_result’] Default: 'output_tool_result'
An event indicating that tool calls require approval or external execution before the run can continue.
Each deferred call also emits its own FunctionToolCallEvent;
this event additionally carries the batched DeferredToolRequests
so stream consumers can tell which calls are paused waiting for interaction, e.g. to notify a frontend.
It is emitted before any HandleDeferredToolCalls
handler runs. If no handler resolves all of the requests, the run ends with the pending requests as its
DeferredToolRequests output.
See deferred tools docs for more information.
The batch of tool calls that require external execution or approval.
Type: DeferredToolRequests
Event type identifier, used as a discriminator.
Type: Literal[‘deferred_tool_requests’] Default: 'deferred_tool_requests'
An event indicating that deferred tool calls were resolved by a HandleDeferredToolCalls handler.
The resolved calls are then executed through the regular tool-execution pipeline, emitting a
FunctionToolResultEvent for each result.
This event is not emitted when results are instead provided to a new run via deferred_tool_results,
as in that case the caller already knows them.
See deferred tools docs for more information.
The results for the deferred tool calls, keyed by tool call ID.
Type: DeferredToolResults
Event type identifier, used as a discriminator.
Type: Literal[‘deferred_tool_results’] Default: 'deferred_tool_results'
The exchange is over: the model has finished replying and nothing is outstanding.
This is the event to stop consuming on. It is synthesized by the session once no tool calls are still running and no further response is in flight.
Event type identifier, used as a discriminator.
Type: Literal[‘realtime_turn_complete’] Default: 'realtime_turn_complete'
The provider detected that the user started speaking.
Useful for barge-in: stop playing any buffered model audio when this arrives, since the model’s in-progress turn is being interrupted.
Reported by OpenAI, Azure OpenAI, and xAI. Gemini Live does not report speech onset.
Provider id of the user input item this speech segment belongs to, when reported.
Type: str | None Default: None
Event type identifier, used as a discriminator.
Type: Literal[‘realtime_input_speech_start’] Default: 'realtime_input_speech_start'
The provider cut the model’s in-progress response short.
Arrives as soon as the provider interrupts, ahead of its response terminal, so it’s the point at which to flush buffered model audio.
Reported by Gemini Live, which interrupts server-side when it hears the user speak. The other
providers report the user’s speech onset as
RealtimeInputSpeechStartEvent and leave the cancellation
to interrupt, so they never report this.
Event type identifier, used as a discriminator.
Type: Literal[‘realtime_response_interrupted’] Default: 'realtime_response_interrupted'
The provider detected that the user stopped speaking.
Useful as a ‘processing’ indicator: the user’s turn has ended and the model is about to respond.
Provider id of the user input item this speech segment belongs to, when reported.
Used to attach retained input audio (audio_retention='input_audio'/'all') to the right user turn
when turns overlap, since transcripts for different items can finalize out of order.
Type: str | None Default: None
Event type identifier, used as a discriminator.
Type: Literal[‘realtime_input_speech_end’] Default: 'realtime_input_speech_end'
The provider started playing the model’s audio to the listener.
Only reported where the provider, rather than your code, holds the audio on its way to the listener: on a WebRTC sideband the media flows browser ↔ provider, so the session never sees audio and this is its only signal that the model has become audible. An ordinary session owns the audio and knows when it starts playing it, so no provider reports this there.
This is about playback, not generation: the provider produces audio faster than it plays it, so this can arrive well after the audio itself was generated.
Event type identifier, used as a discriminator.
Type: Literal[‘realtime_output_speech_start’] Default: 'realtime_output_speech_start'
The provider stopped playing the model’s audio to the listener.
The counterpart to
RealtimeOutputSpeechStartEvent, and the
honest end of a spoken turn: because the provider generates audio far ahead of playing it, it is
still talking long after
RealtimeTurnCompleteEvent reports the response
finished. Drive a “speaking” indicator from this pair rather than from turn completion.
Event type identifier, used as a discriminator.
Type: Literal[‘realtime_output_speech_end’] Default: 'realtime_output_speech_end'
The provider failed to transcribe a user audio input turn, but the session continues.
This is recoverable; item_id and content_index locate the affected user turn.
Human-readable error message.
Type: str
Provider error category, if any.
Type: str | None Default: None
Provider error code, if any.
Type: str | None Default: None
Provider conversation-item ID for the affected user turn, when available.
Type: str | None Default: None
Content index within the affected user turn, when available.
Type: int | None Default: None
Event type identifier, used as a discriminator.
Type: Literal[‘realtime_input_transcription_error’] Default: 'realtime_input_transcription_error'
The connection dropped and was automatically re-established; inspect state_restored for continuity.
Session configuration (instructions, tools, voice, …) is restored on every reconnect. Conversation state is restored either by the provider’s native session resumption (Gemini Live when enabled, xAI Grok Voice) or by the session replaying its local history into the fresh server-side conversation (OpenAI/Azure OpenAI).
Whether the reconnect carried the conversation through without cutting a turn off, regardless of mechanism — native provider resumption or a local-history replay.
True means nothing in flight was lost: the provider either resumed the in-flight response itself
(Gemini Live, xAI Grok Voice) or there was no turn in progress when the connection dropped.
False means a turn the drop interrupted was settled before continuing — its partial reply is
recorded as an interrupted response and any running tool calls as cancelled returns — so
all_messages() stays a coherent history.
Finalized turns from before the drop survive where the provider restores them (the OpenAI/Azure
OpenAI local replay) and are lost where it does not; either way, treat the interrupted turn as over
and expect the model to stay quiet until the next input.
Type: bool Default: False
Event type identifier, used as a discriminator.
Type: Literal[‘realtime_session_reconnect’] Default: 'realtime_session_reconnect'
A provider-reported error occurred in the session.
Human-readable error message.
Type: str
Provider error category, e.g. invalid_request_error or server_error.
Type: str | None Default: None
Provider error code, if any.
Type: str | None Default: None
Whether the session can continue. A protocol error is recoverable; a dropped connection is not.
Type: bool Default: True
Event type identifier, used as a discriminator.
Type: Literal[‘realtime_session_error’] Default: 'realtime_session_error'
def is_multi_modal_content(obj: Any) -> TypeGuard[MultiModalContent]
Check if obj is a MultiModalContent type, enabling type narrowing.
def parse_tool_kind(value: str) -> ToolPartKind | None
Return value if it’s a known ToolPartKind, else None.
UI adapters call this at the wire boundary to validate an untrusted client-supplied tool_kind
string before setting it on a part, so an unknown value degrades to None rather than asserting a
bogus discriminator.
ToolPartKind | None
def post_compaction_window(messages: Sequence[ModelMessage]) -> list[ModelMessage]
The messages from the latest CompactionPart onward.
After compaction, the summary replaces everything before it, so this window is what the model effectively works from — at part-level precision: within the response that carries the compaction part, parts before it are excluded and parts after it are kept. With no compaction part in the history, the whole history is returned (as a new list).
This is the boundary rule Pydantic AI itself uses when deriving model-visible state from history (discovered tools, loaded capabilities). Capability and toolset authors should apply the same rule to their own derived state — anything the model needs to have seen (announcements, disclosures, catalogs) should be recomputed from this window rather than remembered in instance attributes, so it self-heals when compaction replaces the history that carried it.
Deliberately provider-agnostic, unlike the wire-level trim, which is provider-specific
because it must be exact for the one request it renders. This window feeds run-level state
(RunContext.discovered_tool_names, loaded capabilities) that must stay valid across
FallbackModel failover and mid-run model
switches — at parse time there is no “current” provider to resolve against, so the boundary
has to be the conservative intersection: a compaction part another provider would skip on the
wire still counts.
The execution-availability gate separately anchors its evidence to the provider that served the response being dispatched. Re-disclosure, instruction building, search ranking, and catalogs continue to use this conservative provider-agnostic window because they feed a future request whose provider may differ.
def narrow_message_parts(messages: Sequence[ModelMessage]) -> list[ModelMessage]
Promote each tool call/return part across messages to its typed subclass via its tool_kind.
Best-effort and idempotent: a part whose tool_kind resolves to a registered typed subclass and
whose data validates against it is promoted; a part with no tool_kind, an unregistered one, or
shape-invalid data is left a base part (an unsubstantiated tool_kind is stripped — see
ToolCallPart.narrow_type).
UI adapters reconstruct base parts from the wire format with tool_kind set from client-echoed
metadata, then call this once instead of narrowing each part inline. Pydantic deserialization of a
ModelMessage performs the same promotion via its discriminated-union dispatch; this is the
direct-construction equivalent for callers that build parts by hand.
def sanitize_messages(
messages: Sequence[ModelMessage],
*,
strip_system_prompts: bool = True,
strip_compaction_parts: bool = False,
allowed_file_url_schemes: Collection[str] = ('http', 'https'),
allowed_file_url_force_download: Collection[ForceDownloadMode] = (),
allow_uploaded_files: bool = False,
resolved_tool_call_ids: Collection[str] = (),
) -> list[ModelMessage]
Strip message parts that aren’t safe to honor from untrusted input.
This is the same default sanitization the UI adapters apply to
client-submitted messages before they’re passed to an agent. Use it when loading
message_history from a source the application does not fully trust, such as a browser request.
By default it strips:
SystemPromptParts (disable withstrip_system_prompts=False). The system prompt is the server’s to own; a client that can inject one can override the agent’s behavior. If stripping leaves aModelRequestwith no parts, the request is dropped from history entirely.FileUrlparts whose URL scheme is not inallowed_file_url_schemes(defaulthttp/https). Non-HTTP schemes likes3://orgs://cause the model provider to fetch the object using the server-side IAM role, so they should only be accepted from trusted clients.FileUrl.force_downloadvalues other thanFalsethat aren’t inallowed_file_url_force_download, resetting them toFalse. BothTrueand'allow-local'are reset by default. Applies to file URLs in user content and those nested in tool return parts.UploadedFileitems unlessallow_uploaded_files=True. Like a non-HTTPFileUrl, anUploadedFilereferences an object the model provider fetches using the server-side IAM role. Applies to uploaded files in user content and those nested in tool return parts.ToolCallParts at the end of the history that aren’t inresolved_tool_call_ids. An unresolved tool call at the end of client-supplied history doesn’t correspond to a paused agent run and shouldn’t be executed.NativeToolCallParts are left in place: the provider executes them server-side and pairs each with aNativeToolReturnPartin the same response, and the agent loop never dispatches them, so they aren’t a client-injection risk. If stripping leaves the final response with no parts, the response is dropped from history entirely.- The compaction provenance stamp from
CompactionPart.provider_details. This ensures a client-supplied OpenAI Responses compaction item is never trusted to already carry the leadingSystemPromptParts: they are re-sent to the model even where the provider’s own compaction state would normally let them be skipped. CompactionParts, whenstrip_compaction_parts=True(off by default). Everything before a compaction part is hidden from the model, so passTruewhenever you combine the sanitized history with trusted server-sidemessage_history— a client-supplied compaction part would hide that server-side history. The UI adapters apply this rule automatically when a run combines server-sidemessage_historywith client-submitted messages.
messages : Sequence[ModelMessage]
Messages to sanitize.
strip_system_prompts : bool Default: True
Whether to strip
SystemPromptParts.
strip_compaction_parts : bool Default: False
Whether to drop
CompactionParts entirely. Off by default, for
when the untrusted input is the entire conversation; pass True when the sanitized
history is combined with trusted server-side history.
allowed_file_url_schemes : Collection[str] Default: ('http', 'https')
URL schemes allowed for FileUrl
parts. Defaults to http and https.
allowed_file_url_force_download : Collection[ForceDownloadMode] Default: ()
Additional
FileUrl.force_download values to allow.
False is always allowed. Defaults to no additional values.
allow_uploaded_files : bool Default: False
Whether to honor UploadedFile items
from the untrusted input. Off by default, since an uploaded file references an object the model
provider fetches using the server-side IAM role.
resolved_tool_call_ids : Collection[str] Default: ()
Tool call IDs to preserve when the final response ends with tool calls. Use this for human-in-the-loop resumption when matching tool results are being submitted with the same request.
Reason the model finished generating the response.
Mostly normalized to OpenTelemetry semantic convention values.
Whether the agent should automatically continue is determined by ModelResponse.state, not by this field.
Type: TypeAlias Default: Literal['stop', 'length', 'content_filter', 'tool_call', 'error']
Lifecycle state of a model response.
'complete': the response has been fully received from the model.'incomplete': the response is still being streamed and may receive more parts. Yielded byAgentStream.responseandStreamedRunResult.stream_responsewhile iteration is in flight.'suspended': the model paused mid-turn and expects a continuation request. Used by Anthropicpause_turnand OpenAI background mode. Pydantic AI issues these continuations transparently for bothagent.runandagent.run_stream, merging every segment into a single completedModelResponse, so a finished turn in the message history is never left in this state.'interrupted': generation was explicitly stopped before the model finished. Set when a streamed response is cancelled viaStreamedResponse.cancel(), and when a realtime turn is cut off by a barge-in orRealtimeSession.interrupt()— in which case the cut-off point is recorded on the lastSpeechPart.interrupted_at_ms.
Type: TypeAlias Default: Literal['complete', 'incomplete', 'suspended', 'interrupted']
Lifecycle state of a model request.
Type: TypeAlias Default: Literal['complete', 'interrupted']
Type for the force_download parameter on FileUrl subclasses.
False: The URL is sent directly to providers that support it. For providers that don’t, the file is downloaded with SSRF protection (blocks private IPs and cloud metadata).True: The file is always downloaded with SSRF protection (blocks private IPs and cloud metadata).'allow-local': The file is always downloaded, allowing private IPs but still blocking cloud metadata.
Type: TypeAlias Default: bool | Literal['allow-local']
Type for provider_details input: can be a static dict, a callback to update existing details, or None.
Type: TypeAlias Default: Annotated[dict[str, Any] | Callable[[dict[str, Any] | None], dict[str, Any]] | None, pydantic.PlainSerializer(_serialize_provider_details_delta, return_type=(dict[str, Any] | None), when_used='json')]
Provider names supported by UploadedFile.
The 'google-gla' and 'google-vertex' values are retained for backward compatibility with
message history captured before the v2 provider rename — current code emits 'google' and
'google-cloud' respectively.
Type: TypeAlias Default: Literal['anthropic', 'openai', 'google', 'google-cloud', 'google-gla', 'google-vertex', 'bedrock', 'xai']
Union of all multi-modal content types with a discriminator for Pydantic validation.
Default: Annotated[ImageUrl | AudioUrl | DocumentUrl | VideoUrl | Annotated[BinaryContent, pydantic.AfterValidator(BinaryContent.narrow_type)] | UploadedFile, pydantic.Discriminator('kind')]
A single item of user prompt content: a string, a typed text or multi-modal content part, or a CachePoint marker.
Type: TypeAlias Default: str | TextContent | MultiModalContent | CachePoint
Key used to wrap non-dict tool return values in model_response_object().
Default: 'return_value'
TypeAdapter for ToolReturnContent — used by UI adapters to rehydrate multimodal items
(BinaryContent, ImageUrl, etc.) from raw JSON/dict payloads carried in wire-protocol fields
typed as Any (e.g. Vercel’s ToolOutputAvailablePart.output).
Type: pydantic.TypeAdapter[ToolReturnContent] Default: pydantic.TypeAdapter(ToolReturnContent, config=(pydantic.ConfigDict(defer_build=True)))
Discriminator value for the typed call/return-part subclass associated with a tool.
Set on BaseToolCallPart.tool_kind,
BaseToolReturnPart.tool_kind, and
ToolDefinition.tool_kind. Extended as new
typed-part families (e.g. web search) gain dedicated subclasses.
Distinct from ToolKind (invocation semantics —
'function', 'output', 'external', 'unapproved').
Type: TypeAlias Default: Literal['tool-search', 'capability-load']
Placeholder content for a tool call that was interrupted before producing a result (e.g. by run
cancellation). Shared between the agent graph’s history repair and the UI adapters’ stream closeout
so both synthesize the same outcome='interrupted' return.
Default: 'The tool call was interrupted before a result was produced.'
CompactionPart.provider_details key stamped on compaction items minted by our own compact
call, whose input window explicitly planted the standing prompt. Provenance for
_trim_messages_before_compaction’s standing_prompt_retained fast path: only a stamped item is
trusted to retain the standing prompt; anything else — an externally supplied or spliced history,
or an item produced by a provider-initiated compaction of an ordinary request window — gets the
standing prompt re-inserted.
Default: 'pydantic_ai_standing_prompt_planted'
A message part sent by Pydantic AI to a model.
Default: Annotated[Annotated[SystemPromptPart, pydantic.Tag('system-prompt')] | Annotated[UserPromptPart, pydantic.Tag('user-prompt')] | Annotated[SpeechPart, pydantic.Tag('speech')] | Annotated[ToolSearchReturnPart, pydantic.Tag('tool-search-return')] | Annotated[LoadCapabilityReturnPart, pydantic.Tag('capability-load-return')] | Annotated[ToolReturnPart, pydantic.Tag('tool-return')] | Annotated[RetryPromptPart, pydantic.Tag('retry-prompt')] | Annotated[ToolAvailabilityDeltaPart, pydantic.Tag('tool-availability-delta')], pydantic.Discriminator(_model_request_part_discriminator)]
A message part returned by a model.
Default: Annotated[Annotated[TextPart, pydantic.Tag('text')] | Annotated[ToolSearchCallPart, pydantic.Tag('tool-search-call')] | Annotated[LoadCapabilityCallPart, pydantic.Tag('capability-load-call')] | Annotated[ToolCallPart, pydantic.Tag('tool-call')] | Annotated[NativeToolSearchCallPart, pydantic.Tag('builtin-tool-search-call')] | Annotated[NativeToolCallPart, pydantic.Tag('builtin-tool-call')] | Annotated[NativeToolSearchReturnPart, pydantic.Tag('builtin-tool-search-return')] | Annotated[NativeToolReturnPart, pydantic.Tag('builtin-tool-return')] | Annotated[ThinkingPart, pydantic.Tag('thinking')] | Annotated[CompactionPart, pydantic.Tag('compaction')] | Annotated[FilePart, pydantic.Tag('file')] | Annotated[SpeechPart, pydantic.Tag('speech')], pydantic.Discriminator(_model_response_part_discriminator)]
Any message sent to or returned by a model.
Default: Annotated[ModelRequest | ModelResponse, pydantic.Discriminator('kind')]
Pydantic TypeAdapter for (de)serializing messages.
Default: pydantic.TypeAdapter(list[ModelMessage], config=(pydantic.ConfigDict(defer_build=True, ser_json_bytes='base64', val_json_bytes='base64')))
A partial update (delta) for any model response part.
Default: Annotated[TextPartDelta | ThinkingPartDelta | ToolCallPartDelta | SpeechPartDelta, pydantic.Discriminator('part_delta_kind')]
An event in the model response stream, starting a new part, applying a delta to an existing one, indicating a part is complete, or indicating the final result.
Default: Annotated[PartStartEvent | PartDeltaEvent | PartEndEvent | FinalResultEvent, pydantic.Discriminator('event_kind')]
An event yielded when handling a model response, indicating tool calls and results.
Default: Annotated[FunctionToolCallEvent | FunctionToolResultEvent | ToolAvailabilityDeltaEvent | OutputToolCallEvent | OutputToolResultEvent | DeferredToolRequestsEvent | DeferredToolResultsEvent, pydantic.Discriminator('event_kind')]
An event that occurs only in realtime session streams.
Default: Annotated[RealtimeTurnCompleteEvent | RealtimeInputSpeechStartEvent | RealtimeInputSpeechEndEvent | RealtimeOutputSpeechStartEvent | RealtimeOutputSpeechEndEvent | RealtimeResponseInterruptedEvent | RealtimeInputTranscriptionErrorEvent | RealtimeSessionReconnectEvent | RealtimeSessionErrorEvent, pydantic.Discriminator('event_kind')]
An event in an agent run or realtime session stream.
Default: Annotated[ModelResponseStreamEvent | EnqueuedMessagesEvent | HandleResponseEvent | RealtimeSessionEvent, pydantic.Discriminator('event_kind')]
Bases: TypedDict
Typed arguments for a tool-search call.
Carried on
NativeToolSearchCallPart.args
(native server-side path) and
ToolSearchCallPart.args
(local-fallback path) as the canonical cross-provider shape. Each adapter
normalizes its provider’s wire format into this shape on parse, and rebuilds the
wire format from this shape on emit.
Normalized search inputs.
- Anthropic BM25 / regex: single-item list with the query string.
- OpenAI server-executed
tool_search: the list of tool paths the model picked. - OpenAI client-execution / local
search_toolsfallback: single-item list with the keywords string.
Bases: TypedDict
Typed return value of the framework-managed tool-search builtin.
Carried on
NativeToolSearchReturnPart.content
(native server-side path) and
ToolSearchReturnPart.content
(local-fallback path) as the canonical cross-provider shape.
Matches ordered by relevance. An empty list means “search ran, nothing matched”.
Type: list[ToolSearchMatch]
Optional text shown to the model when no matches were found.
Rendered as text on local fallback / Anthropic custom-callable empty-results path. Stripped on OpenAI client-execution and Anthropic server-side replay (those carry only structural fields).
Type: NotRequired[str]
Bases: ToolCallPart
Typed view of a ToolCallPart for the local search_tools function call.
Used on the local-fallback path (and as the synthetic-injection target on
non-native providers receiving cross-provider history). The native server-side
path uses
NativeToolSearchCallPart
instead.
To detect a tool-search part regardless of execution path (native server-side
vs. local fallback), check part.tool_kind == 'tool-search' — this works
across both call/return and both server/local variants.
Shadows args with the canonical typed shape. The str variant covers the
streaming / partial-args case before parsing completes; once parsed,
args is a ToolSearchArgs
TypedDict.
Default tool name for the typed subclass. Discrimination drives off tool_kind.
Type: Literal[‘search_tools’] Default: 'search_tools'
Tool-search query payload.
Narrows the parent’s str | dict[str, Any] | None to a typed
ToolSearchArgs when parsed. Streaming /
partial-args still arrive as str until they’re complete.
Type: str | ToolSearchArgs | None Default: None
Discriminator for the typed subclass (framework-emitted search_tools call).
Type: Literal[‘tool-search’] Default: 'tool-search'
Typed view of the validated tool-search arguments, or None if not yet parseable.
In non-streaming code (a typed call part on a finalized
ModelResponse), this is always
populated — once a part is narrowed to this typed subclass, its args
have been parsed and validated.
Returns None only in streaming-partial state, where args is still an
in-progress JSON string the model hasn’t finished emitting. For raw
string-tolerant access, use the inherited args_as_dict().
Type: ToolSearchArgs | None
Subfield accessor for typed_args['queries'].
Returns an empty list if args haven’t been parsed yet (streaming-partial,
i.e. typed_args is None).
Bases: ToolReturnPart
Typed view of a ToolReturnPart for the local search_tools function return.
Used on the local-fallback path (and as the synthetic-injection target on
non-native providers receiving cross-provider history). The native server-side
path uses
NativeToolSearchReturnPart
instead.
To detect a tool-search part regardless of execution path (native server-side
vs. local fallback), check part.tool_kind == 'tool-search' — this works
across both call/return and both server/local variants.
Shadows content with a narrower
ToolSearchReturnContent
TypedDict.
Discovered-tools payload.
Narrows the parent’s ToolReturnContent to a typed
ToolSearchReturnContent.
Type: ToolSearchReturnContent Default: field(kw_only=True)
Default tool name for the typed subclass. Discrimination drives off tool_kind.
Type: Literal[‘search_tools’] Default: 'search_tools'
Discriminator for the typed subclass (framework-emitted search_tools return).
Type: Literal[‘tool-search’] Default: 'tool-search'
Subfield accessor for content['discovered_tools'].
Type: list[ToolSearchMatch]
Subfield accessor for content.get('message').
The message is NotRequired on
ToolSearchReturnContent;
returns None when no message was set (e.g. on non-empty match returns).
Records that the set of tools available to the model changed at this point.
Additions only. Withdrawing a tool is not supported yet, because no provider can be told about one
without also invalidating the prompt cache this part exists to protect: Anthropic rejects a
reference to a tool the request doesn’t declare, so a withdrawn tool has to leave the tools
array, and that is itself the invalidation. The name says availability rather than addition so
removals can join once they can be done cache-safely — see
https://github.com/pydantic/pydantic-ai/issues/6985.
Names of tools this point in history reveals.
A reveal is what the model has been shown; whether the tool is callable is the broader availability question, which for a capability-owned tool also asks whether its owning capability is loaded.
Type: Annotated[list[str], pydantic.Field(validation_alias=(pydantic.AliasChoices(tools_added, added)))] Default: field(default_factory=(lambda: []))
The tool call associated with the change, if any.
Type: str | None Default: None
Part type identifier, this is available on all parts as a discriminator.
Type: Literal[‘tool-availability-delta’] Default: 'tool-availability-delta'
def otel_message_parts(
settings: InstrumentationSettings,
) -> list[_otel_messages.MessagePart]
Render the change as trace content.
Tool names are recorded regardless of include_content: they aren’t user content, they’re
already visible in the request’s tool definitions, and a run where the model suddenly can
call something is unreadable without them.
list[_otel_messages.MessagePart]
An event indicating tools were made available mid-run, carrying the recorded delta part.
This is request-side because the delta is created while executing a tool, after response-part
streaming has finished. It records the post-dedup change, while ToolReturnPart.tools preserves
the caller’s pre-dedup intent, and is emitted for capability loads as well as tool returns.
The tool availability delta part that will be recorded in message history.
Type: ToolAvailabilityDeltaPart
Event type identifier, used as a discriminator.
Type: Literal[‘tool_availability_delta’] Default: 'tool_availability_delta'
Bases: NativeToolCallPart
Typed view of a NativeToolCallPart for tool search.
Used on the native server-side tool-search path (Anthropic BM25/regex, OpenAI
Responses) where the provider executes the search and emits a native result.
The local-fallback path uses
ToolSearchCallPart instead.
To detect a tool-search part regardless of execution path (native server-side
vs. local fallback), check part.tool_kind == 'tool-search' — this works
across both call/return and both server/local variants.
Shadows args with a narrower type. The str variant covers the
streaming / partial-args case before parsing completes; once parsed,
args is a ToolSearchArgs
TypedDict.
Default tool name for the typed subclass. Discrimination drives off tool_kind.
Type: Literal[‘tool_search’] Default: 'tool_search'
Tool-search query payload.
Narrows the parent’s str | dict[str, Any] | None to a typed
ToolSearchArgs when parsed. Streaming /
partial-args still arrive as str until they’re complete.
Type: str | ToolSearchArgs | None Default: None
Discriminator for the typed subclass (cross-provider tool-search call).
Type: Literal[‘tool-search’] Default: 'tool-search'
Typed view of the validated tool-search arguments, or None if not yet parseable.
In non-streaming code (a typed call part on a finalized
ModelResponse), this is always
populated — once a part is narrowed to this typed subclass, its args
have been parsed and validated.
Returns None only in streaming-partial state, where args is still an
in-progress JSON string the model hasn’t finished emitting. For raw
string-tolerant access, use the inherited args_as_dict().
Type: ToolSearchArgs | None
Subfield accessor for typed_args['queries'].
Returns an empty list if args haven’t been parsed yet (streaming-partial,
i.e. typed_args is None).
Bases: NativeToolReturnPart
Typed view of a NativeToolReturnPart for tool search.
Used on the native server-side tool-search path (Anthropic BM25/regex, OpenAI
Responses) where the provider executes the search and emits a native result.
The local-fallback path uses
ToolSearchReturnPart instead.
To detect a tool-search part regardless of execution path (native server-side
vs. local fallback), check part.tool_kind == 'tool-search' — this works
across both call/return and both server/local variants.
Shadows content with a narrower
ToolSearchReturnContent
TypedDict.
Discovered-tools payload.
Narrows the parent’s ToolReturnContent to a typed
ToolSearchReturnContent.
Type: ToolSearchReturnContent Default: field(kw_only=True)
Default tool name for the typed subclass. Discrimination drives off tool_kind.
Type: Literal[‘tool_search’] Default: 'tool_search'
Discriminator for the typed subclass (cross-provider tool-search return).
Type: Literal[‘tool-search’] Default: 'tool-search'
Subfield accessor for content['discovered_tools'].
Type: list[ToolSearchMatch]
Subfield accessor for content.get('message').
The message is NotRequired on
ToolSearchReturnContent;
returns None when no message was set (e.g. on non-empty match returns).