# pydantic\_ai.messages

The structure of [`ModelMessage`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelMessage) can be shown as a graph:

```mermaid
graph RL
    SystemPromptPart(SystemPromptPart) --- ModelRequestPart
    UserPromptPart(UserPromptPart) --- ModelRequestPart
    ToolReturnPart(ToolReturnPart) --- ModelRequestPart
    RetryPromptPart(RetryPromptPart) --- 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)")
```

### SystemPromptPart

A system prompt, generally written by the application developer.

This gives the model context and guidance on how to respond.

#### Attributes

##### content

The content of the prompt.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### timestamp

The timestamp of the prompt.

**Type:** [`datetime`](https://docs.python.org/3/library/datetime.html#module-datetime) **Default:** `field(default_factory=_now_utc)`

##### dynamic\_ref

The ref of the dynamic system prompt function that generated this part.

Only set if system prompt is dynamic, see [`system_prompt`](/docs/ai/api/pydantic-ai/agent/#pydantic_ai.agent.Agent.system_prompt) for more information.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### part\_kind

Part type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['system-prompt'\] **Default:** `'system-prompt'`

### FileUrl

**Bases:** `ABC`

Abstract base class for any URL-based file.

#### Attributes

##### url

The URL of the file.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### force\_download

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\_metadata

Vendor-specific metadata for the file.

Supported by:

-   `GoogleModel`: `VideoUrl.vendor_metadata` is used as `video_metadata`: [https://ai.google.dev/gemini-api/docs/video-understanding#customize-video-processing](https://ai.google.dev/gemini-api/docs/video-understanding#customize-video-processing)
-   `OpenAIChatModel`, `OpenAIResponsesModel`: `ImageUrl.vendor_metadata['detail']` is used as `detail` setting for images
-   `XaiModel`: `ImageUrl.vendor_metadata['detail']` is used as `detail` setting for images

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### media\_type

Return the media type of the file, based on the URL or the provided `media_type`.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### identifier

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`](https://docs.python.org/3/library/stdtypes.html#str)

##### format

The file format.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

### VideoUrl

**Bases:** [`FileUrl`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.FileUrl)

A URL to a video.

#### Attributes

##### url

The URL of the video.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### kind

Type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['video-url'\] **Default:** `'video-url'`

##### is\_youtube

True if the URL has a YouTube domain.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool)

##### format

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`

### AudioUrl

**Bases:** [`FileUrl`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.FileUrl)

A URL to an audio file.

#### Attributes

##### url

The URL of the audio file.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### kind

Type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['audio-url'\] **Default:** `'audio-url'`

##### format

The file format of the audio file.

**Type:** `AudioFormat`

### ImageUrl

**Bases:** [`FileUrl`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.FileUrl)

A URL to an image.

#### Attributes

##### url

The URL of the image.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### kind

Type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['image-url'\] **Default:** `'image-url'`

##### format

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`

### DocumentUrl

**Bases:** [`FileUrl`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.FileUrl)

The URL of the document.

#### Attributes

##### url

The URL of the document.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### kind

Type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['document-url'\] **Default:** `'document-url'`

##### format

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`

### TextContent

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.

#### Attributes

##### content

The content that is sent to the LLM.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### metadata

Additional data that can be accessed programmatically by the application but is not sent to the LLM.

**Type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) **Default:** `None`

##### kind

Type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['text-content'\] **Default:** `'text-content'`

### BinaryContent

Binary content, e.g. an audio or image file.

#### Attributes

##### data

The binary file data.

Use `.base64` to get the base64-encoded string.

**Type:** [`bytes`](https://docs.python.org/3/library/stdtypes.html#bytes)

##### media\_type

The media type of the binary data.

**Type:** `AudioMediaType` | `ImageMediaType` | `DocumentMediaType` | [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### vendor\_metadata

Vendor-specific metadata for the file.

Supported by:

-   `GoogleModel`: `BinaryContent.vendor_metadata` is used as `video_metadata`: [https://ai.google.dev/gemini-api/docs/video-understanding#customize-video-processing](https://ai.google.dev/gemini-api/docs/video-understanding#customize-video-processing)
-   `OpenAIChatModel`, `OpenAIResponsesModel`: `BinaryContent.vendor_metadata['detail']` is used as `detail` setting for images
-   `XaiModel`: `BinaryContent.vendor_metadata['detail']` is used as `detail` setting for images

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### kind

Type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['binary'\] **Default:** `'binary'`

##### identifier

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`](https://docs.python.org/3/library/stdtypes.html#str)

##### data\_uri

Convert the `BinaryContent` to a data URI.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### base64

Return the binary data as a base64-encoded string. Default encoding is UTF-8.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### is\_audio

Return `True` if the media type is an audio type.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool)

##### is\_image

Return `True` if the media type is an image type.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool)

##### is\_video

Return `True` if the media type is a video type.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool)

##### is\_document

Return `True` if the media type is a document type.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool)

##### format

The file format of the binary content.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

#### Methods

##### narrow\_type

`@staticmethod`

```python
def narrow_type(bc: BinaryContent) -> BinaryContent | BinaryImage
```

Narrow the type of the `BinaryContent` to `BinaryImage` if it's an image.

###### Returns

[`BinaryContent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.BinaryContent) | [`BinaryImage`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.BinaryImage)

##### from\_data\_uri

`@classmethod`

```python
def from_data_uri(cls, data_uri: str) -> BinaryContent
```

Create a `BinaryContent` from a data URI.

###### Returns

[`BinaryContent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.BinaryContent)

##### from\_path

`@classmethod`

```python
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.

###### Returns

[`BinaryContent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.BinaryContent)

###### Raises

-   `FileNotFoundError` -- if the file does not exist.
-   `PermissionError` -- if the file cannot be read.

### BinaryImage

**Bases:** [`BinaryContent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.BinaryContent)

Binary content that's guaranteed to be an image.

### CachePoint

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)

#### Attributes

##### kind

Type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['cache-point'\] **Default:** `'cache-point'`

##### ttl

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](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](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html) for more information.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['5m', '1h'\] **Default:** `'5m'`

### UploadedFile

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:

-   [`AnthropicModel`](/docs/ai/api/models/anthropic/#pydantic_ai.models.anthropic.AnthropicModel)
-   [`OpenAIChatModel`](/docs/ai/api/models/openai/#pydantic_ai.models.openai.OpenAIChatModel)
-   [`OpenAIResponsesModel`](/docs/ai/api/models/openai/#pydantic_ai.models.openai.OpenAIResponsesModel)
-   [`BedrockConverseModel`](/docs/ai/api/models/bedrock/#pydantic_ai.models.bedrock.BedrockConverseModel)
-   [`GoogleModel`](/docs/ai/api/models/google/#pydantic_ai.models.google.GoogleModel) (Gemini API: [Files API](https://ai.google.dev/gemini-api/docs/files) URIs, Google Cloud: GCS `gs://` URIs)
-   [`XaiModel`](/docs/ai/api/models/xai/#pydantic_ai.models.xai.XaiModel)

#### Attributes

##### file\_id

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`](https://docs.python.org/3/library/stdtypes.html#str)

##### provider\_name

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\_metadata

Vendor-specific metadata for the file.

The expected shape of this dictionary depends on the provider:

Supported by:

-   `GoogleModel`: used as `video_metadata` for video files

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### kind

Type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['uploaded-file'\] **Default:** `'uploaded-file'`

##### media\_type

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`](https://docs.python.org/3/library/stdtypes.html#str)

##### identifier

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`](https://docs.python.org/3/library/stdtypes.html#str)

##### format

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`](https://docs.python.org/3/library/stdtypes.html#str)

### ToolReturn

**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 for `User`
-   `ToolReturn` (bare) -- no return schema generated

#### Attributes

##### return\_value

The return value to be used in the tool response.

**Type:** `ToolReturnContent`

##### content

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`Sequence`](https://docs.python.org/3/library/typing.html#typing.Sequence)\[`UserContent`\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### metadata

Additional data accessible by the application but not sent to the LLM.

**Type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) **Default:** `None`

### UserPromptPart

A user prompt, generally written by the end user.

Content comes from the `user_prompt` parameter of [`Agent.run`](/docs/ai/api/pydantic-ai/agent/#pydantic_ai.agent.AbstractAgent.run), [`Agent.run_sync`](/docs/ai/api/pydantic-ai/agent/#pydantic_ai.agent.AbstractAgent.run_sync), and [`Agent.run_stream`](/docs/ai/api/pydantic-ai/agent/#pydantic_ai.agent.AbstractAgent.run_stream).

#### Attributes

##### content

The content of the prompt.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`Sequence`](https://docs.python.org/3/library/typing.html#typing.Sequence)\[`UserContent`\]

##### timestamp

The timestamp of the prompt.

**Type:** [`datetime`](https://docs.python.org/3/library/datetime.html#module-datetime) **Default:** `field(default_factory=_now_utc)`

##### part\_kind

Part type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['user-prompt'\] **Default:** `'user-prompt'`

### BaseToolReturnPart

Base class for tool return parts.

#### Attributes

##### tool\_name

The name of the tool that was called.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### content

The tool return content, which may include multimodal files.

**Type:** `ToolReturnContent`

##### tool\_call\_id

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`](https://docs.python.org/3/library/stdtypes.html#str) **Default:** `field(default_factory=_generate_tool_call_id)`

##### tool\_kind

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`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolPartKind) literal:

-   `ToolSearchCallPart` / `ToolSearchReturnPart` -- `'tool-search'`
-   `NativeToolSearchCallPart` / `NativeToolSearchReturnPart` -- `'tool-search'`

**Type:** `ToolPartKind` | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### metadata

Additional data accessible by the application but not sent to the LLM.

**Type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) **Default:** `None`

##### timestamp

The timestamp, when the tool returned.

**Type:** [`datetime`](https://docs.python.org/3/library/datetime.html#module-datetime) **Default:** `field(default_factory=_now_utc)`

##### outcome

The outcome of the tool call.

-   `'success'`: The tool executed successfully.
-   `'failed'`: The tool raised an error during execution.
-   `'denied'`: The tool call was denied by the approval mechanism.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['success', 'failed', 'denied'\] **Default:** `'success'`

##### files

The multimodal file parts from `content` (`ImageUrl`, `AudioUrl`, `DocumentUrl`, `VideoUrl`, `BinaryContent`).

**Type:** [`list`](https://docs.python.org/3/glossary.html#term-list)\[[`MultiModalContent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.MultiModalContent)\]

#### Methods

##### content\_items

```python
def content_items(mode: Literal['raw'] = 'raw') -> list[ToolReturnContent]
def content_items(mode: Literal['str']) -> list[str | MultiModalContent]
def content_items(mode: Literal['jsonable']) -> list[Any | MultiModalContent]
```

Return content as a flat list for iteration, with optional serialization.

###### Returns

[`list`](https://docs.python.org/3/glossary.html#term-list)\[`ToolReturnContent`\] | [`list`](https://docs.python.org/3/glossary.html#term-list)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`MultiModalContent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.MultiModalContent)\] | [`list`](https://docs.python.org/3/glossary.html#term-list)\[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any) | [`MultiModalContent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.MultiModalContent)\]

###### Parameters

**`mode`** : [`Literal`](https://docs.python.org/3/library/typing.html#typing.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 via `tool_return_ta`. File items (`MultiModalContent`) pass through unchanged.
-   `'jsonable'`: Non-file items are serialized to JSON-compatible Python objects via `tool_return_ta`. File items pass through unchanged.

##### model\_response\_str

```python
def model_response_str() -> str
```

Return a string representation of the data content for the model.

This excludes multimodal files - use `.files` to get those separately.

###### Returns

[`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### model\_response\_object

```python
def model_response_object() -> 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.

###### Returns

[`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\]

##### model\_response\_str\_and\_user\_content

```python
def model_response_str_and_user_content() -> 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).

###### Returns

[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`list`](https://docs.python.org/3/glossary.html#term-list)\[`UserContent`\]\]

##### has\_content

```python
def has_content() -> bool
```

Return `True` if the tool return has content.

###### Returns

[`bool`](https://docs.python.org/3/library/functions.html#bool)

### ToolReturnPart

**Bases:** [`BaseToolReturnPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.BaseToolReturnPart)

A tool return message, this encodes the result of running a tool.

#### Attributes

##### part\_kind

Part type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['tool-return'\] **Default:** `'tool-return'`

#### Methods

##### narrow\_type

`@staticmethod`

```python
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.

Returns the input unchanged when neither the `tool_kind` kwarg nor `part.tool_kind` resolves to a registered subclass. Pass `tool_kind` to inject the discriminator inline -- the narrower applies it as part of its single dataclass clone, dropping the need for an upstream `replace(part, tool_kind=...)`. Use this on direct construction; Pydantic deserialization promotes automatically via the discriminated-union dispatch on [`ModelRequestPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelRequestPart).

###### Returns

[`ToolReturnPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolReturnPart)

### NativeToolReturnPart

**Bases:** [`BaseToolReturnPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.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.

#### Attributes

##### provider\_name

The name of the provider that generated the response.

Required to be set when `provider_details` is set.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_details

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`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### part\_kind

Part type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['builtin-tool-return'\] **Default:** `'builtin-tool-return'`

#### Methods

##### narrow\_type

`@staticmethod`

```python
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.

Returns the input unchanged when neither the `tool_kind` kwarg nor `part.tool_kind` resolves to a registered subclass. Pass `tool_kind` to inject the discriminator inline -- the narrower applies it as part of its single dataclass clone. Use this on direct construction; Pydantic deserialization promotes automatically via the discriminated-union dispatch on [`ModelResponsePart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelResponsePart).

###### Returns

[`NativeToolReturnPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.NativeToolReturnPart)

### RetryPromptPart

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`](https://docs.pydantic.dev/latest/api/pydantic-core/pydantic_core/#pydantic_core.ValidationError)
-   a tool raised a [`ModelRetry`](/docs/ai/api/pydantic-ai/exceptions/#pydantic_ai.exceptions.ModelRetry) exception
-   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`](https://docs.pydantic.dev/latest/api/pydantic-core/pydantic_core/#pydantic_core.ValidationError)
-   an output validator raised a [`ModelRetry`](/docs/ai/api/pydantic-ai/exceptions/#pydantic_ai.exceptions.ModelRetry) exception

#### Attributes

##### content

Details of why and how the model should retry.

If the retry was triggered by a [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic-core/pydantic_core/#pydantic_core.ValidationError), this will be a list of error details.

**Type:** [`list`](https://docs.python.org/3/glossary.html#term-list)\[[`pydantic_core.ErrorDetails`](https://docs.pydantic.dev/latest/api/pydantic-core/pydantic_core/#pydantic_core.ErrorDetails)\] | [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### tool\_name

The name of the tool that was called, if any.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### tool\_call\_id

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`](https://docs.python.org/3/library/stdtypes.html#str) **Default:** `field(default_factory=_generate_tool_call_id)`

##### timestamp

The timestamp, when the retry was triggered.

**Type:** [`datetime`](https://docs.python.org/3/library/datetime.html#module-datetime) **Default:** `field(default_factory=_now_utc)`

##### part\_kind

Part type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['retry-prompt'\] **Default:** `'retry-prompt'`

#### Methods

##### model\_response

```python
def model_response() -> str
```

Return a string message describing why the retry is requested.

###### Returns

[`str`](https://docs.python.org/3/library/stdtypes.html#str)

### InstructionPart

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.

#### Attributes

##### content

The text content of this instruction block.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### dynamic

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`](https://docs.python.org/3/library/functions.html#bool) **Default:** `False`

##### part\_kind

Part type identifier, used as a discriminator for deserialization.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['instruction'\] **Default:** `'instruction'`

#### Methods

##### join

`@staticmethod`

```python
def join(parts: Sequence[InstructionPart]) -> str | None
```

Join instruction parts into a single string, separated by double newlines.

###### Returns

[`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None)

##### sorted

`@staticmethod`

```python
def sorted(parts: Sequence[InstructionPart]) -> list[InstructionPart]
```

Sort instruction parts with static (`dynamic=False`) before dynamic, preserving relative order.

###### Returns

[`list`](https://docs.python.org/3/glossary.html#term-list)\[[`InstructionPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.InstructionPart)\]

### ModelRequest

A request generated by Pydantic AI and sent to a model, e.g. a message from the Pydantic AI app to the model.

#### Attributes

##### parts

The parts of the user message.

**Type:** [`Sequence`](https://docs.python.org/3/library/typing.html#typing.Sequence)\[[`ModelRequestPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelRequestPart)\]

##### timestamp

The timestamp when the request was sent to the model.

**Type:** [`datetime`](https://docs.python.org/3/library/datetime.html#module-datetime) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### instructions

The instructions string for this request, rendered from structured instruction parts.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### kind

Message type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['request'\] **Default:** `'request'`

##### run\_id

The unique identifier of the agent run in which this message originated.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### conversation\_id

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### metadata

Additional data that can be accessed programmatically by the application but is not sent to the LLM.

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

#### Methods

##### user\_text\_prompt

`@classmethod`

```python
def user_text_prompt(
    cls,
    user_prompt: str,
    instructions: str | None = None,
) -> ModelRequest
```

Create a `ModelRequest` with a single user prompt as text.

###### Returns

[`ModelRequest`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelRequest)

### TextPart

A plain text response from a model.

#### Attributes

##### content

The text content of the response.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### id

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_name

The name of the provider that generated the response.

Required to be set when `provider_details` or `id` is set.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_details

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`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### part\_kind

Part type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['text'\] **Default:** `'text'`

#### Methods

##### has\_content

```python
def has_content() -> bool
```

Return `True` if the text content is non-empty.

###### Returns

[`bool`](https://docs.python.org/3/library/functions.html#bool)

### ThinkingPart

A thinking response from a model.

#### Attributes

##### content

The thinking content of the response.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### id

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### signature

The signature of the thinking.

Supported by:

-   Anthropic (corresponds to the `signature` field)
-   Bedrock (corresponds to the `signature` field)
-   Google (corresponds to the `thought_signature` field)
-   OpenAI (corresponds to the `encrypted_content` field)

When this field is set, `provider_name` is required to identify the provider that generated this data.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_name

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_details

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`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### part\_kind

Part type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['thinking'\] **Default:** `'thinking'`

#### Methods

##### has\_content

```python
def has_content() -> bool
```

Return `True` if the thinking content is non-empty.

###### Returns

[`bool`](https://docs.python.org/3/library/functions.html#bool)

### CompactionPart

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

#### Attributes

##### content

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### id

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_name

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_details

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`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### part\_kind

Part type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['compaction'\] **Default:** `'compaction'`

#### Methods

##### has\_content

```python
def has_content() -> bool
```

Return `True` if the compaction content is non-empty.

###### Returns

[`bool`](https://docs.python.org/3/library/functions.html#bool)

### FilePart

A file response from a model.

#### Attributes

##### content

The file content of the response.

**Type:** [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)\[[`BinaryContent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.BinaryContent), [`pydantic.AfterValidator`](https://docs.pydantic.dev/latest/api/pydantic/functional_validators/#pydantic.functional_validators.AfterValidator)(`BinaryImage.narrow_type`)\]

##### id

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_name

The name of the provider that generated the response.

Required to be set when `provider_details` or `id` is set.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_details

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`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### part\_kind

Part type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['file'\] **Default:** `'file'`

#### Methods

##### has\_content

```python
def has_content() -> bool
```

Return `True` if the file content is non-empty.

###### Returns

[`bool`](https://docs.python.org/3/library/functions.html#bool)

### BaseToolCallPart

A tool call from a model.

#### Attributes

##### tool\_name

The name of the tool to call.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### args

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### tool\_call\_id

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`](https://docs.python.org/3/library/stdtypes.html#str) **Default:** `field(default_factory=_generate_tool_call_id)`

##### tool\_kind

Discriminator for the typed subclass of this part (e.g. `'tool-search'`).

See [`BaseToolReturnPart.tool_kind`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.BaseToolReturnPart.tool_kind) for the full semantics.

**Type:** `ToolPartKind` | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### id

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_name

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_details

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`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

#### Methods

##### args\_as\_dict

```python
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.

###### Returns

[`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\]

###### Parameters

**`raise_if_invalid`** : [`bool`](https://docs.python.org/3/library/functions.html#bool) _Default:_ `False`

If `True`, a `ValueError` or `AssertionError` caused by malformed JSON in `args` will be re-raised. When `False` (the default), malformed 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.

##### args\_as\_json\_str

```python
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.

###### Returns

[`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### has\_content

```python
def has_content() -> bool
```

Return `True` if the tool call has content.

###### Returns

[`bool`](https://docs.python.org/3/library/functions.html#bool)

### ToolCallPart

**Bases:** [`BaseToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.BaseToolCallPart)

A tool call from a model.

#### Attributes

##### part\_kind

Part type identifier, this is available on all parts as a discriminator. Note that this is different from `ToolCallPartDelta.part_delta_kind`.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['tool-call'\] **Default:** `'tool-call'`

#### Methods

##### narrow\_type

`@staticmethod`

```python
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.

Returns the input unchanged when neither the `tool_kind` kwarg nor `part.tool_kind` resolves to a registered subclass. Pass `tool_kind` to inject the discriminator inline -- the narrower applies it as part of its single dataclass clone, dropping the need for an upstream `replace(part, tool_kind=...)`. Use this on direct construction; Pydantic deserialization promotes automatically via the discriminated-union dispatch on [`ModelResponsePart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelResponsePart).

###### Returns

[`ToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolCallPart)

### NativeToolCallPart

**Bases:** [`BaseToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.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):

1.  Add a sibling `pydantic_ai/_<name>.py` module that defines the cross-provider `TypedDict`s, the `NativeToolCallPart` / `NativeToolReturnPart` subclasses, and registers their narrowers into `_NATIVE_CALL_NARROWERS` / `_NATIVE_RETURN_NARROWERS` keyed by `tool_kind`. Subclass overrides `tool_kind: Literal['<emitter>']` to match the emitting [`AbstractNativeTool.kind`](/docs/ai/api/pydantic-ai/native_tools/#pydantic_ai.native_tools.AbstractNativeTool.kind), and shadows `args` / `content` with a narrower type.
2.  Late-import the new module from this file (alongside the existing tool-search import) so registration runs whenever `pydantic_ai.messages` is imported.
3.  Add the subclass to `ModelResponsePart`'s discriminated union and to `_model_response_part_discriminator` so Pydantic deserialization auto-promotes on `model_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](https://github.com/pydantic/pydantic-ai/issues/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](https://github.com/pydantic/pydantic-ai/issues/3561).

#### Attributes

##### part\_kind

Part type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['builtin-tool-call'\] **Default:** `'builtin-tool-call'`

#### Methods

##### narrow\_type

`@staticmethod`

```python
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.

Returns the input unchanged when neither the `tool_kind` kwarg nor `part.tool_kind` resolves to a registered subclass. Pass `tool_kind` to inject the discriminator inline -- the narrower applies it as part of its single dataclass clone. Use this on direct construction; Pydantic deserialization promotes automatically via the discriminated-union dispatch on [`ModelResponsePart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelResponsePart).

###### Returns

[`NativeToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.NativeToolCallPart)

### ModelResponse

A response from a model, e.g. a message from the model to the Pydantic AI app.

#### Attributes

##### parts

The parts of the model message.

**Type:** [`Sequence`](https://docs.python.org/3/library/typing.html#typing.Sequence)\[[`ModelResponsePart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelResponsePart)\]

##### usage

Usage information for the request.

This has a default to make tests easier, and to support loading old messages where usage will be missing.

**Type:** [`RequestUsage`](/docs/ai/api/pydantic-ai/usage/#pydantic_ai.usage.RequestUsage) **Default:** `field(default_factory=RequestUsage)`

##### model\_name

The name of the model that generated the response.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### timestamp

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`](https://docs.python.org/3/library/datetime.html#module-datetime) **Default:** `field(default_factory=_now_utc)`

##### kind

Message type identifier, this is available on all parts as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['response'\] **Default:** `'response'`

##### provider\_name

The name of the LLM provider that generated the response.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_url

The base URL of the LLM provider that generated the response.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_details

Additional data returned by the provider that can't be mapped to standard fields.

**Type:** [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)\[[`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None), [`pydantic.Field`](https://docs.pydantic.dev/latest/api/pydantic/fields/#pydantic.fields.Field)(`validation_alias`\=([`pydantic.AliasChoices`](https://docs.pydantic.dev/latest/api/pydantic/aliases/#pydantic.aliases.AliasChoices)(`provider_details`, `vendor_details`)))\] **Default:** `None`

##### provider\_response\_id

request ID as specified by the model provider. This can be used to track the specific request to the model.

**Type:** [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None), [`pydantic.Field`](https://docs.pydantic.dev/latest/api/pydantic/fields/#pydantic.fields.Field)(`validation_alias`\=([`pydantic.AliasChoices`](https://docs.pydantic.dev/latest/api/pydantic/aliases/#pydantic.aliases.AliasChoices)(`provider_response_id`, `vendor_id`)))\] **Default:** `None`

##### finish\_reason

Reason the model finished generating the response, normalized to OpenTelemetry values.

**Type:** [`FinishReason`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.FinishReason) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### run\_id

The unique identifier of the agent run in which this message originated.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### conversation\_id

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### metadata

Additional data that can be accessed programmatically by the application but is not sent to the LLM.

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### state

Lifecycle state of the response. See [`ModelResponseState`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelResponseState).

**Type:** [`ModelResponseState`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelResponseState) **Default:** `'complete'`

##### text

Get the text in the response.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None)

##### thinking

Get the thinking in the response.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None)

##### files

Get the files in the response.

**Type:** [`list`](https://docs.python.org/3/glossary.html#term-list)\[[`BinaryContent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.BinaryContent)\]

##### images

Get the images in the response.

**Type:** [`list`](https://docs.python.org/3/glossary.html#term-list)\[[`BinaryImage`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.BinaryImage)\]

##### tool\_calls

Get the tool calls in the response.

**Type:** [`list`](https://docs.python.org/3/glossary.html#term-list)\[[`ToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolCallPart)\]

##### native\_tool\_calls

Get the native tool calls and results in the response.

**Type:** [`list`](https://docs.python.org/3/glossary.html#term-list)\[[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`NativeToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.NativeToolCallPart), [`NativeToolReturnPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.NativeToolReturnPart)\]\]

##### builtin\_tool\_calls

Deprecated: use [`native_tool_calls`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelResponse.native_tool_calls) instead.

**Type:** [`list`](https://docs.python.org/3/glossary.html#term-list)\[[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`NativeToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.NativeToolCallPart), [`NativeToolReturnPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.NativeToolReturnPart)\]\]

#### Methods

##### price

`@deprecated`

```python
def price() -> genai_types.PriceCalculation
```

###### Returns

`genai_types.PriceCalculation`

##### cost

```python
def cost() -> genai_types.PriceCalculation
```

Calculate the cost of the usage.

Uses [`genai-prices`](https://github.com/pydantic/genai-prices).

###### Returns

`genai_types.PriceCalculation`

##### otel\_events

```python
def otel_events(settings: InstrumentationSettings) -> list[LogRecord]
```

Return OpenTelemetry events for the response.

###### Returns

[`list`](https://docs.python.org/3/glossary.html#term-list)\[`LogRecord`\]

### TextPartDelta

A partial update (delta) for a `TextPart` to append new text content.

#### Attributes

##### content\_delta

The incremental text content to add to the existing `TextPart` content.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### provider\_name

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_details

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`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### part\_delta\_kind

Part delta type identifier, used as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['text'\] **Default:** `'text'`

#### Methods

##### apply

```python
def apply(part: ModelResponsePart) -> TextPart
```

Apply this text delta to an existing `TextPart`.

###### Returns

[`TextPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.TextPart) -- A new `TextPart` with updated text content.

###### Parameters

**`part`** : [`ModelResponsePart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelResponsePart)

The existing model response part, which must be a `TextPart`.

###### Raises

-   `ValueError` -- If `part` is not a `TextPart`.

### ThinkingPartDelta

A partial update (delta) for a `ThinkingPart` to append new thinking content.

#### Attributes

##### content\_delta

The incremental thinking content to add to the existing `ThinkingPart` content.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### signature\_delta

Optional signature delta.

Note this is never treated as a delta -- it can replace None.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_name

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_details

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.

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\_kind

Part delta type identifier, used as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['thinking'\] **Default:** `'thinking'`

#### Methods

##### apply

```python
def apply(part: ModelResponsePart) -> ThinkingPart
def apply(
    part: ModelResponsePart | ThinkingPartDelta,
) -> ThinkingPart | ThinkingPartDelta
```

Apply this thinking delta to an existing `ThinkingPart`.

###### Returns

[`ThinkingPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ThinkingPart) | [`ThinkingPartDelta`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ThinkingPartDelta) -- A new `ThinkingPart` with updated thinking content.

###### Parameters

**`part`** : [`ModelResponsePart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelResponsePart) | [`ThinkingPartDelta`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ThinkingPartDelta)

The existing model response part, which must be a `ThinkingPart`.

###### Raises

-   `ValueError` -- If `part` is not a `ThinkingPart`.

### ToolCallPartDelta

A partial update (delta) for a `ToolCallPart` to modify tool name, arguments, or tool call ID.

#### Attributes

##### tool\_name\_delta

Incremental text to add to the existing tool name, if any.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### args\_delta

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### tool\_call\_id

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_name

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`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### provider\_details

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`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### part\_delta\_kind

Part delta type identifier, used as a discriminator. Note that this is different from `ToolCallPart.part_kind`.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['tool\_call'\] **Default:** `'tool_call'`

#### Methods

##### as\_part

```python
def as_part() -> ToolCallPart | None
```

Convert this delta to a fully formed `ToolCallPart` if possible, otherwise return `None`.

###### Returns

[`ToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolCallPart) | [`None`](https://docs.python.org/3/library/constants.html#None) -- A `ToolCallPart` if `tool_name_delta` is set, otherwise `None`.

##### apply

```python
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.

###### Returns

[`ToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolCallPart) | [`NativeToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.NativeToolCallPart) | [`ToolCallPartDelta`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolCallPartDelta) -- Either a new `ToolCallPart` or `NativeToolCallPart`, or an updated `ToolCallPartDelta`.

###### Parameters

**`part`** : [`ModelResponsePart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelResponsePart) | [`ToolCallPartDelta`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolCallPartDelta)

The existing model response part or delta to update.

###### Raises

-   `ValueError` -- If `part` is neither a `ToolCallPart`, `NativeToolCallPart`, nor a `ToolCallPartDelta`.
-   `UnexpectedModelBehavior` -- If applying JSON deltas to dict arguments or vice versa.

### PartStartEvent

An event indicating that a new part has started.

If multiple `PartStartEvent`s are received with the same index, the new one should fully replace the old one.

#### Attributes

##### index

The index of the part within the overall response parts list.

**Type:** [`int`](https://docs.python.org/3/library/functions.html#int)

##### part

The newly started `ModelResponsePart`.

**Type:** [`ModelResponsePart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelResponsePart)

##### previous\_part\_kind

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`](https://docs.python.org/3/library/typing.html#typing.Literal)\['text', 'thinking', 'tool-call', 'builtin-tool-call', 'builtin-tool-return', 'compaction', 'file'\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### event\_kind

Event type identifier, used as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['part\_start'\] **Default:** `'part_start'`

### PartDeltaEvent

An event indicating a delta update for an existing part.

#### Attributes

##### index

The index of the part within the overall response parts list.

**Type:** [`int`](https://docs.python.org/3/library/functions.html#int)

##### delta

The delta to apply to the specified part.

**Type:** [`ModelResponsePartDelta`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelResponsePartDelta)

##### event\_kind

Event type identifier, used as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['part\_delta'\] **Default:** `'part_delta'`

### PartEndEvent

An event indicating that a part is complete.

#### Attributes

##### index

The index of the part within the overall response parts list.

**Type:** [`int`](https://docs.python.org/3/library/functions.html#int)

##### part

The complete `ModelResponsePart`.

**Type:** [`ModelResponsePart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelResponsePart)

##### next\_part\_kind

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`](https://docs.python.org/3/library/typing.html#typing.Literal)\['text', 'thinking', 'tool-call', 'builtin-tool-call', 'builtin-tool-return', 'compaction', 'file'\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### event\_kind

Event type identifier, used as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['part\_end'\] **Default:** `'part_end'`

### FinalResultEvent

An event indicating the response to the current model request matches the output schema and will produce a result.

#### Attributes

##### tool\_name

The name of the output tool that was called. `None` if the result is from text content and not from a tool.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None)

##### tool\_call\_id

The tool call ID, if any, that this result is associated with.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None)

##### event\_kind

Event type identifier, used as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['final\_result'\] **Default:** `'final_result'`

### ToolCallEvent

Base class for events emitted when a tool call is about to be invoked.

Match against this in a `case` to handle [`FunctionToolCallEvent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.FunctionToolCallEvent) and [`OutputToolCallEvent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.OutputToolCallEvent) together.

#### Attributes

##### part

The tool call to make.

**Type:** [`ToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolCallPart)

##### args\_valid

Whether the tool arguments passed validation. See the [custom validation docs](https://ai.pydantic.dev/tools-advanced/#args-validator) 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`](https://docs.python.org/3/library/functions.html#bool) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### tool\_call\_id

An ID used for matching details about the call to its result.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

### FunctionToolCallEvent

**Bases:** [`ToolCallEvent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolCallEvent)

An event indicating the start to a call to a function tool.

#### Attributes

##### event\_kind

Event type identifier, used as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['function\_tool\_call'\] **Default:** `'function_tool_call'`

##### call\_id

An ID used for matching details about the call to its result.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

### OutputToolCallEvent

**Bases:** [`ToolCallEvent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolCallEvent)

An event indicating the start of a call to an output tool (the model's "submit final answer" call).

#### Attributes

##### event\_kind

Event type identifier, used as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['output\_tool\_call'\] **Default:** `'output_tool_call'`

### ToolResultEvent

Base class for events emitted when a tool call has been completed.

Match against this in a `case` to handle [`FunctionToolResultEvent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.FunctionToolResultEvent) and [`OutputToolResultEvent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.OutputToolResultEvent) together.

#### Attributes

##### part

The tool result part that will be sent back to the model.

**Type:** [`ToolReturnPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolReturnPart) | [`RetryPromptPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.RetryPromptPart)

##### tool\_call\_id

An ID used to match the result to its original call.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

### FunctionToolResultEvent

**Bases:** [`ToolResultEvent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolResultEvent)

An event indicating the result of a function tool call.

#### Attributes

##### event\_kind

Event type identifier, used as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['function\_tool\_result'\] **Default:** `'function_tool_result'`

##### content

The content that will be sent to the model as a UserPromptPart following the result.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`Sequence`](https://docs.python.org/3/library/typing.html#typing.Sequence)\[`UserContent`\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `content`

##### result

The tool result part that will be sent back to the model.

**Type:** [`ToolReturnPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolReturnPart) | [`RetryPromptPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.RetryPromptPart)

### OutputToolResultEvent

**Bases:** [`ToolResultEvent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolResultEvent)

An event indicating the result of an output tool call.

#### Attributes

##### event\_kind

Event type identifier, used as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['output\_tool\_result'\] **Default:** `'output_tool_result'`

### BuiltinToolCallEvent

An event indicating the start to a call to a built-in tool.

#### Attributes

##### part

The built-in tool call to make.

**Type:** [`NativeToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.NativeToolCallPart)

##### event\_kind

Event type identifier, used as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['builtin\_tool\_call'\] **Default:** `'builtin_tool_call'`

### BuiltinToolResultEvent

An event indicating the result of a built-in tool call.

#### Attributes

##### result

The result of the call to the built-in tool.

**Type:** [`NativeToolReturnPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.NativeToolReturnPart)

##### event\_kind

Event type identifier, used as a discriminator.

**Type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\['builtin\_tool\_result'\] **Default:** `'builtin_tool_result'`

### is\_multi\_modal\_content

```python
def is_multi_modal_content(obj: Any) -> TypeGuard[MultiModalContent]
```

Check if obj is a MultiModalContent type, enabling type narrowing.

#### Returns

[`TypeGuard`](https://docs.python.org/3/library/typing.html#typing.TypeGuard)\[[`MultiModalContent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.MultiModalContent)\]

### FinishReason

Reason the model finished generating the response, normalized to OpenTelemetry values.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Literal['stop', 'length', 'content_filter', 'tool_call', 'error']`

### ModelResponseState

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 by `AgentStream.response` and [`StreamedRunResult.stream_response`](/docs/ai/api/pydantic-ai/result/#pydantic_ai.result.StreamedRunResult.stream_response) while iteration is in flight.
-   `'interrupted'`: streaming was explicitly stopped via [`StreamedRunResult.cancel()`](/docs/ai/api/pydantic-ai/result/#pydantic_ai.result.StreamedRunResult.cancel) before the model finished generating.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Literal['complete', 'incomplete', 'interrupted']`

### ForceDownloadMode

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`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `bool | Literal['allow-local']`

### ProviderDetailsDelta

Type for provider\_details input: can be a static dict, a callback to update existing details, or None.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `dict[str, Any] | Callable[[dict[str, Any] | None], dict[str, Any]] | None`

### UploadedFileProviderName

Provider names supported by [`UploadedFile`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.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`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Literal['anthropic', 'openai', 'google', 'google-cloud', 'google-gla', 'google-vertex', 'bedrock', 'xai']`

### MultiModalContent

Union of all multi-modal content types with a discriminator for Pydantic validation.

**Default:** `Annotated[ImageUrl | AudioUrl | DocumentUrl | VideoUrl | BinaryContent | UploadedFile, pydantic.Discriminator('kind')]`

### RETURN\_VALUE\_KEY

Key used to wrap non-dict tool return values in `model_response_object()`.

**Default:** `'return_value'`

### ToolPartKind

Discriminator value for the typed call/return-part subclass associated with a tool.

Set on [`BaseToolCallPart.tool_kind`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.BaseToolCallPart.tool_kind), [`BaseToolReturnPart.tool_kind`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.BaseToolReturnPart.tool_kind), and [`ToolDefinition.tool_kind`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ToolDefinition.tool_kind). Extended as new typed-part families (e.g. web search) gain dedicated subclasses.

Distinct from [`ToolKind`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ToolKind) (invocation semantics -- `'function'`, `'output'`, `'external'`, `'unapproved'`).

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Literal['tool-search', 'capability-load']`

### ModelRequestPart

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[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')], pydantic.Discriminator(_model_request_part_discriminator)]`

### ModelResponsePart

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')], pydantic.Discriminator(_model_response_part_discriminator)]`

### ModelMessage

Any message sent to or returned by a model.

**Default:** `Annotated[ModelRequest | ModelResponse, pydantic.Discriminator('kind')]`

### ModelMessagesTypeAdapter

Pydantic [`TypeAdapter`](https://docs.pydantic.dev/latest/api/pydantic/type_adapter/#pydantic.type_adapter.TypeAdapter) for (de)serializing messages.

**Default:** `pydantic.TypeAdapter(list[ModelMessage], config=(pydantic.ConfigDict(defer_build=True, ser_json_bytes='base64', val_json_bytes='base64')))`

### ModelResponsePartDelta

A partial update (delta) for any model response part.

**Default:** `Annotated[TextPartDelta | ThinkingPartDelta | ToolCallPartDelta, pydantic.Discriminator('part_delta_kind')]`

### ModelResponseStreamEvent

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')]`

### HandleResponseEvent

An event yielded when handling a model response, indicating tool calls and results.

**Default:** `Annotated[FunctionToolCallEvent | FunctionToolResultEvent | OutputToolCallEvent | OutputToolResultEvent | BuiltinToolCallEvent | BuiltinToolResultEvent, pydantic.Discriminator('event_kind')]`

### AgentStreamEvent

An event in the agent stream: model response stream events and response-handling events.

**Default:** `Annotated[ModelResponseStreamEvent | HandleResponseEvent, pydantic.Discriminator('event_kind')]`