pydantic_ai.messages

Parameters

namespace : str

The package or capability defining the kind, like 'inventory'. Dotted names are allowed.

name : str

The kind’s name within its namespace, like 'lookup'.

args : type[ArgsT_co] | None Default: None

The shape of the tool’s arguments, typically a TypedDict. A tool of this kind must have parameters that fit it, and its call parts are only promoted when their arguments validate against it.

content : type[ContentT_co] | None Default: None

The shape of the tool’s result, typically a TypedDict. A tool of this kind must have a return type that fits it, and its successful return parts are only promoted when their content validates against it.

BaseToolReturnPart

Bases: Generic[ContentT_co]

Base class for tool return parts.

Generic in the shape of typed_content, which a typed tool part declares through its kind.

Attributes

tool_name

The name of the tool that was called.

Type: 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 Default: field(default_factory=_generate_tool_call_id)

tool_kind

What the tool is, independent of its name (e.g. 'tool-search'), or None if the tool declares no kind.

Set from the tool’s ToolDefinition.tool_kind. A part whose data fits the typed subclass registered for its kind is promoted to that subclass; otherwise it stays a base part that keeps the kind, as does a return whose outcome isn’t 'success'. Only core’s own kinds, which deserialization routes straight to their subclass, are stripped from a base part whose data doesn’t fit them. See Typed tool parts.

Type: ToolPartKind | None Default: None

metadata

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

Type: Any Default: None

timestamp

The timestamp, when the tool returned.

Type: datetime Default: field(default_factory=_now_utc)

outcome

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 via ToolFailed.
'denied': The tool call was denied — either by the approval mechanism or by a HandleDeferredToolCalls handler returning ToolDenied.
'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.
'retried': The call has to be made again — its arguments failed validation, the tool raised ModelRetry, or a HandleDeferredToolCalls handler answered it with one. The content is the feedback the model needs to get the call right, and the call still counts against the tool’s retry budget. An output tool’s validation failure lands here too; output that had no call to answer is a RetryFeedbackPart instead.

'failed' and 'retried' are mapped to a provider’s native error channel (e.g. Anthropic is_error, Bedrock status='error') — see ERROR_OUTCOMES. 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’, ‘retried’] Default: 'success'

typed_content

The content validated against the shape the part’s kind declares, or None if it doesn’t fit.

None too when the return isn’t a success: its content is then an error, not the tool’s result. On a base part, or one whose kind declares no content shape, it is the content as is.

Type: ContentT_co | None

files

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

Type: list[MultiModalContent]

Methods

content_items

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.

Returns

list[ToolReturnContent] | list[str | MultiModalContent] | list[Any | MultiModalContent]

Parameters

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 JSON text via tool_return_ta; an item whose JSON form is a string (e.g. a datetime) becomes that string, unquoted. 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.

wrap_if_error : bool Default: True

Whether to wrap errored tool returns (see ERROR_OUTCOMES) in an {"error": ...} object (ignored in 'raw' mode). When True (the default), an errored 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.

model_response_str

def model_response_str(*, wrap_if_error: bool = True) -> str

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

A str is returned as-is and None as ''; any other value as its JSON text, and a value whose JSON form is a string (e.g. a datetime) as that string, unquoted.

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

Returns

Parameters

wrap_if_error : bool Default: True

Whether to wrap errored tool returns (see ERROR_OUTCOMES) in an {"error": ...} object. Set this to False when the provider has a native error channel.

model_response_object

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.

Returns

dict[str, Any]

Parameters

wrap_if_error : bool Default: True

Whether to wrap errored tool returns (see ERROR_OUTCOMES) in an {"error": ...} object. Set this to False when the provider has a native error channel.

structured_content

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.

Returns

dict[str, Any] | list[Any] | None

model_response_str_and_user_content

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.

Each file is framed by _tool_result_provenance_tags so the model can tell it from the user’s own uploads, which travel on the same channel.

Returns

tuple[str, list[UserContent]]

Parameters

wrap_if_error : bool Default: True

Whether to wrap errored tool returns (see ERROR_OUTCOMES) in an {"error": ...} object. Set this to False when the provider has a native error channel.

has_content

def has_content() -> bool

Return True if the tool return has content.

Returns

ToolReturnPart

Bases: BaseToolReturnPart[ContentT_co]

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

Attributes

retry

Why the call has to be made again and which attempt this is, when outcome is 'retried'; None for any other outcome.

See ToolRetryCause for the causes. 'unknown_tool' and 'unavailable_tool' are rejected before the tool is resolved or run, so this is how to tell them apart from a retry the tool itself asked for without matching on content. A retry loaded from a deprecated RetryPromptPart carries None unless its content says it was a validation error, since a message alone can’t say who asked for the retry.

Metadata for your code only: it is never sent to the model, so it doesn’t change the request or the provider’s prompt cache.

Type: RetryInfo[ToolRetryCause] | None Default: None

part_kind

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

Type: Literal[‘tool-return’] Default: 'tool-return'

Methods

__init_subclass__

def __init_subclass__(
    cls,
    *,
    kind: ToolKind[Any, ContentT_co] | None = None,
    **kwargs: Any,
) -> None

Returns

narrow_type

@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, keeping that tool_kind. When the part’s data doesn’t validate against the subclass, the part stays a base part; for core’s own kinds, which deserialization routes straight to their subclass, an unsubstantiated tool_kind is also stripped so the part still round-trips through ModelMessagesTypeAdapter. A return part whose outcome isn’t 'success' is never promoted: its content is an error, not the tool’s result shape.

Returns

ToolReturnPart

NativeToolReturnPart

Bases: BaseToolReturnPart[ContentT_co]

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 | 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[str, Any] | None Default: None

part_kind

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

Type: Literal[‘builtin-tool-return’] Default: 'builtin-tool-return'

Methods

__init_subclass__

def __init_subclass__(
    cls,
    *,
    kind: ToolKind[Any, ContentT_co] | None = None,
    **kwargs: Any,
) -> None

Returns

narrow_type

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

Returns

NativeToolReturnPart

RetryPromptPart

A message back to a model asking it to try again.

Deprecated in favour of the two parts it conflated. A retry that answers a tool call is that call’s own ToolReturnPart with outcome='retried'; one that answers no call is a RetryFeedbackPart. Holding both in one class left a tool-less retry reaching every provider as bare user text the model couldn’t tell from something a person wrote (https://github.com/pydantic/pydantic-ai/issues/6404).

Nothing you already stored has to change: a 'retry-prompt' part in a serialized history loads as whichever of the two it always meant, so old histories keep working and cost no warning. An instance still in memory — one your own code built, or one handed back through DeferredToolResults — is translated the same way before it reaches a model.

Attributes

content

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

tool_name

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

Type: str | 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 Default: field(default_factory=_generate_tool_call_id)

timestamp

The timestamp, when the retry was triggered.

Type: datetime Default: field(default_factory=_now_utc)

part_kind

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

Type: Literal[‘retry-prompt’] Default: 'retry-prompt'

Methods

from_error

@classmethod

def from_error(
    cls,
    error: pydantic_core.ValidationError | ModelRetry,
    *,
    tool_name: str | None = None,
    tool_call_id: str | None = None,
) -> RetryPromptPart

Build a retry prompt from a validation error or a ModelRetry.

Deprecated with the class. ToolReturnPart and RetryFeedbackPart take the same content this builds — a ValidationError’s errors(include_url=False, include_context=False), or a ModelRetry’s message.

Returns

RetryPromptPart

model_response

def model_response() -> str

Return a string message describing why the retry is requested.

Returns

RetryFeedbackPart

Pydantic AI’s own feedback about a model response it couldn’t use.

This part is never bound to a tool call, and deliberately carries no tool fields: it covers the retries where the response as a whole was unusable — structured output failed validation, an output validator or function raised ModelRetry, or the response contained nothing that could serve as output. A tool call that needs retrying answers its own call as a ToolReturnPart with outcome='retried' instead. The deprecated RetryPromptPart was both at once.

The stored part stays model-neutral; each model translates it at prepare_messages time into the part its retry.cause calls for — a fenced UserPromptPart for validation errors or a ModelRetry message, either of which can quote the model’s output, and a mid-conversation SystemPromptPart for the framework’s fixed 'no_output' text. Either way the model can tell the feedback apart from something a person wrote, which is what a retry rendered as bare user text never allowed (https://github.com/pydantic/pydantic-ai/issues/6404), and keeping the presentation out of the history keeps a cached prefix valid across providers.

Attributes

content

Details of why the response couldn’t be used.

If the retry was triggered by a ValidationError, this will be a list of error details, serialized into the fenced block the model is shown.

A string comes from a ModelRetry your own code raised, and goes out in the user voice inside a <retry_feedback> fence, since output validators commonly interpolate the output they reject; or, for a 'no_output' cause, it’s the framework’s own fixed text.

Type: list[pydantic_core.ErrorDetails] | str

retry

What made the response unusable, which decides the voice the feedback reaches the model in, and which output retry this is.

See RetryFeedbackCause for the causes and the voice each one takes. The agent loop fills in attempt and max_retries from the run’s output-retry budget.

Type: RetryInfo[RetryFeedbackCause]

timestamp

The timestamp, when the retry was triggered.

Type: datetime Default: field(default_factory=_now_utc)

part_kind

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

Type: Literal[‘retry-feedback’] Default: 'retry-feedback'

Methods

model_response

def model_response() -> str

Return the text the model is shown, in the voice retry.cause calls for.

Error details serialize the way an errored ToolReturnPart’s content does, so a retry that answers a tool call and one that answers none show the model the same JSON. A 'validation_error' goes in a <validation_errors> fence and a 'model_retry' in a <retry_feedback> fence, each behind one line saying the application is speaking: both can carry the model’s own words, a ModelRetry message because output validators routinely interpolate the output they reject. Only 'no_output' is left unfenced, as its text is fixed and carries nothing the model wrote.

What prepare_messages adds around this is the voice, not the wording: the part type it goes into, and the <system> tagging a provider without a mid-conversation system message needs.

Returns

list[InstructionPart]

otel_message_parts

def otel_message_parts(
    settings: InstrumentationSettings,
) -> list[_otel_messages.MessagePart]

Record the stored feedback as trace content.

The same text the model is shown, the way SystemPromptPart records its own content.

Only pydantic_ai.all_messages on the run span reaches this method, because that attribute is built from the stored history. A model request span’s gen_ai.input.messages is built after prepare_messages has already replaced this part with the part its retry.cause calls for, so it shows the same text at every instrumentation version.

Returns

list[_otel_messages.MessagePart]

AgentInstructionSource

The agent’s own instructions.

There is exactly one agent in scope, so it carries no id.

ToolsetInstructionSource

A toolset with an id.

CapabilityInstructionSource

A capability with an id.

RunInstructionSource

Instructions passed to a run method’s instructions argument.

Only a named InstructionPart is addressed by it, as 'run:<name>': a run’s instructions belong to whoever starts the run, and the name is what says a value passed to a later run of the same conversation is the same block.

InstructionId

The key an instruction part is addressed by: who contributed it, and which of their parts it is.

Attributes

source

Who contributed the part: the agent, a toolset with an id, a capability with an id, or a run.

Type: InstructionSource

name

Which of that source’s parts this is, or None to address everything the source contributes.

Type: str | None Default: None

InstructionPart

A single instruction part 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 part.

Type: 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 Default: False

on_change

How changes to this part are delivered.

'rewrite' replaces the instruction prefix on each request. 'append' preserves the initial prefix and appends full replacements to trusted message history when this block changes, including withdrawal when it stops contributing content. Requires an addressable id; otherwise a warning is emitted and the part uses 'rewrite'. Evaluation frequency and dynamic cache placement are unchanged. Compaction starts a new baseline.

Type: InstructionChangePolicy Default: 'rewrite'

name

What the author calls this part, relative to whatever contributes it.

Name a part relative to what you own — 'limits', not 'toolset:weather:limits' — and the source you contribute through qualifies it into an id. A name cannot contain :, which delimits the segments of an id, and cannot be 'agent', which is the key of the agent’s own instructions.

Naming a part whose source has no identity of its own leaves id as None: there is no source key to qualify the name against, so it says what the part is without making it addressable.

Type: str | None Default: None

id

The stable key this part is addressed by, or None if nothing addresses it.

The framework issues this while collecting instructions, from the author’s name and the identity of the source that contributed the part — declare a name rather than setting this yourself. A consumer reading ModelRequestParameters.instruction_parts can persist configuration against an id, because it survives the reordering and rewording that a part’s position and text do not.

InstructionId.source is who contributed the part:

AgentInstructionSource — the agent’s literal instructions
ToolsetInstructionSource — a toolset with an id
CapabilityInstructionSource — a capability with an id
RunInstructionSource — a named part passed to a run method’s instructions

An id renders and serializes as its segments joined by : — 'agent', 'toolset:weather', or 'capability:budget:remaining'.

Type: SerializedInstructionId Default: None

part_kind

Part type identifier, used as a discriminator for deserialization.

Type: Literal[‘instruction’] Default: 'instruction'

Methods

join

@staticmethod

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

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

Returns

str | None

sorted

@staticmethod

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

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

Returns

InstructionDeltaPart

Replace or withdraw one operator-authored instruction from this point in history onward.

Earlier statements remain in history; the latest statement for an id is effective. This is trusted operator content, so sanitize_messages(strip_system_prompts=True) strips it.

Attributes

id

The id of the block being replaced, as on its InstructionPart.

Serialized as the string it renders to. A change written by a newer version, for a source namespace this one doesn’t know, loads with None here, and the next request opens a new window instead of applying it.

Type: SerializedInstructionId

content

The complete replacement text, or None to withdraw the block.

Type: str | None

base_hash

The SHA-256 hex digest of the block’s text this change replaces, or None if it replaces none.

A model can then send the change as a diff against the text it sent before, and only when that text is still what this change was computed against: if a history processor dropped an earlier change, the hashes differ and the model sends content in full instead.

Type: str | None Default: None

part_kind

Part type identifier, used as a discriminator for deserialization.

Type: Literal[‘instruction-delta’] Default: 'instruction-delta'

Methods

render

def render(*, inline_system: bool = True, previous: str | None = None) -> str

Render this change as a <context> element that replaces the block’s earlier one.

A replacement is rendered as a <context_diff> element instead, holding a unified diff against previous, when previous is the text this change replaces (per base_hash) and the diff is shorter than the full replacement.

Returns

Parameters

inline_system : bool Default: True

Whether the receiving model supports mid-conversation system messages, per its profile’s supports_inline_system_prompts. When False, the model gets this text as <system>-tagged user text, and a withdrawal says that it stays in effect. Defaults to True for callers with no model to ask, such as token estimates and search.

previous : str | None Default: None

The block’s text as the model last received it, if known.

otel_message_parts

def otel_message_parts(
    settings: InstrumentationSettings,
) -> list[_otel_messages.MessagePart]

Render the replacement in traces only when content capture is enabled.

Returns

list[_otel_messages.MessagePart]

ToolAvailabilityDeltaPart

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.

Attributes

tools_added

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: []))

tool_call_id

The tool call associated with the change, if any.

Type: str | None Default: None

part_kind

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

Type: Literal[‘tool-availability-delta’] Default: 'tool-availability-delta'

Methods

otel_message_parts

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.

Returns

list[_otel_messages.MessagePart]

InstructionDigest

A rewrite-mode instruction block as an InstructionBaselinePart records it.

Only what decides whether the block is unchanged: a later request can keep its window’s prefix only if every rewrite-mode block is still the same, in the same place.

Attributes

id

The block’s InstructionPart.id, if it has one.

Type: SerializedInstructionId Default: None

dynamic

The block’s InstructionPart.dynamic, which decides its cache placement.

Type: bool Default: False

content_hash

The SHA-256 hex digest of the block’s content.

Type: str

part_kind

Part type identifier, used as a discriminator for deserialization.

Type: Literal[‘instruction-digest’] Default: 'instruction-digest'

Methods

of

@classmethod

def of(cls, part: InstructionPart) -> InstructionDigest

The digest of a rewrite-mode part.

Returns

InstructionDigest

matches

def matches(part: InstructionPart) -> bool

Whether part is a rewrite-mode block this digest records unchanged.

Returns

InstructionBaselinePart

The instructions a request was sent with, recorded where a run of on_change='append' requests starts.

A request records this when it opens a window: the first request with an on_change='append' block, and each request whose prefix has to change anyway (a rewritten block changed, a block’s policy changed, compaction). Every request in the window is sent the same prefix, with each append-mode block at its value here, followed in history by the InstructionDeltaParts since. An empty instructions list ends the window, so earlier changes stop applying.

It’s never sent to a model: it records what the request’s instructions were made of, so a later request can tell whether it can keep the prefix and what its append-mode blocks said. Like a system prompt, it’s trusted operator content, so sanitize_messages(strip_system_prompts=True) strips it.

Attributes

instructions

The request’s instruction parts, in order.

Append-mode blocks are recorded in full, since their changes are computed against them. Rewrite-mode blocks are recorded as an InstructionDigest, which is enough to tell whether one changed, so a long block that is rewritten on every request isn’t stored again each time.

Type: list[Annotated[Annotated[InstructionPart, pydantic.Tag(instruction)] | Annotated[InstructionDigest, pydantic.Tag(instruction - digest)], pydantic.Discriminator(_baseline_block_kind)]]

part_kind

Part type identifier, used as a discriminator for deserialization.

Type: Literal[‘instruction-baseline’] Default: 'instruction-baseline'

Methods

otel_message_parts

def otel_message_parts(
    settings: InstrumentationSettings,
) -> list[_otel_messages.MessagePart]

Contribute nothing to traces: the instructions it records are reported with the request itself.

Returns

list[_otel_messages.MessagePart]

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.

Building the message promotes each base tool part whose tool_kind has a typed part to that subclass (see Typed tool parts). A list passed in is updated in place rather than copied, so the message keeps holding the very list it was given, as it would without promotion, and code that goes on to change that list changes the message too.

Type: Sequence[ModelRequestPart]

timestamp

The timestamp when the request was sent to the model.

Type: datetime | None Default: None

instructions

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

Type: str | None Default: None

kind

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

Type: Literal[‘request’] Default: 'request'

run_id

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

Type: str | 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 | None Default: None

metadata

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

Type: dict[str, Any] | None Default: None

state

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. In that case parts holds only the tool returns that were collected, and is empty if none were. Appears in capture_run_messages output so consumers can detect partial state.

Type: ModelRequestState Default: 'complete'

Methods

user_text_prompt

@classmethod

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

WebCitationSource

A web page a citation points to.

Attributes

url

The page’s URL.

Type: str

title

The page’s title, if the provider gave one.

Type: str | None Default: None

excerpts

Passages from the source that back the cited text.

Depending on the provider, this is the exact cited text or a longer retrieved chunk. It can include text from your own documents, so choose whether to log it or show it to users.

Type: list[str] Default: field(default_factory=(list[str]))

kind

Source type identifier, used as a discriminator for deserialization.

Type: Literal[‘web’] Default: 'web'

DocumentCitationSource

Any other source a citation points to, such as a document you sent or a file in the provider’s file store.

Attributes

document_id

The provider’s ID for the file or document, if it has one. It’s not a local path.

Type: str | None Default: None

title

The document’s title or filename, if the provider gave one.

Type: str | None Default: None

excerpts

Passages from the source that back the cited text.

Depending on the provider, this is the exact cited text or a longer retrieved chunk. It can include text from your own documents, so choose whether to log it or show it to users.

Type: list[str] Default: field(default_factory=(list[str]))

kind

Source type identifier, used as a discriminator for deserialization.

Type: Literal[‘document’] Default: 'document'

ContentCitationAnchor

The text the citation’s sources support, as positions in the part’s content.

Attributes

start

The position of the first character, counting from 0.

Type: int

end

The position after the last character, so content[start:end] is the range.

Type: int

kind

Anchor type identifier, used as a discriminator for deserialization.

Type: Literal[‘content’] Default: 'content'

MarkerCitationAnchor

A marker the model wrote, such as [1] or a link, as positions in the part’s content.

Attributes

start

The position of the first character, counting from 0.

Type: int

end

The position after the last character, so content[start:end] is the range.

Type: int

kind

Anchor type identifier, used as a discriminator for deserialization.

Type: Literal[‘marker’] Default: 'marker'

Citation

Links part of a model’s answer to the sources that back it.

Attributes

sources

Where the information came from.

Type: list[CitationSource]

anchor

Which part of the text the citation is about, or None when the provider didn’t say.

Type: CitationAnchor | None Default: None

TextPart

A plain text response from a model.

Attributes

content

The text content of the response.

Type: 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 | 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 | None Default: None

provider_details

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

Type: dict[str, Any] | None Default: None

citations

The citations for this text, if any.

Anything else the provider returned about them, such as page numbers or confidence scores, is in provider_details['citations'].

Type: list[Citation] | None Default: None

part_kind

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

Type: Literal[‘text’] Default: 'text'

Methods

has_content

def has_content() -> bool

Return True if the text content is non-empty.

Returns

ThinkingPart

A thinking response from a model.

Attributes

content

The thinking content of the response.

Type: 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 | 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 | 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 | None Default: None

provider_details

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

Type: dict[str, Any] | None Default: None

part_kind

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

Type: Literal[‘thinking’] Default: 'thinking'

Methods

has_content

def has_content() -> bool

Return True if the thinking content is non-empty.

Returns

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 | 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 | 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 | 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[str, Any] | None Default: None

part_kind

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

Type: Literal[‘compaction’] Default: 'compaction'

Methods

has_content

def has_content() -> bool

Return True if the compaction content is non-empty.

Returns

FilePart

A file response from a model.

Attributes

content

The file content of the response.

Type: Annotated[BinaryContent, pydantic.AfterValidator(BinaryContent.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 | 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 | None Default: None

provider_details

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

Type: dict[str, Any] | None Default: None

part_kind

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

Type: Literal[‘file’] Default: 'file'

Methods

has_content

def has_content() -> bool

Return True if the file content is non-empty.

Returns

SpeechPart

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.

Attributes

speaker

Whether the audio was spoken by the end user or by the model.

Type: Literal[‘user’, ‘assistant’]

transcript

The transcript of the audio. None if transcription was unavailable.

Type: str | None Default: None

audio

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

interrupted_at_ms

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

id

The provider item ID, used to correlate the part with provider-side conversation items.

Type: str | None Default: None

provider_name

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

provider_details

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

Type: dict[str, Any] | None Default: None

part_kind

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

Type: Literal[‘speech’] Default: 'speech'

content

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

Methods

has_content

def has_content() -> bool

Return True if the part has a transcript or retained audio.

Returns

BaseToolCallPart

Bases: Generic[ArgsT_co]

A tool call from a model.

Attributes

tool_name

The name of the tool to call.

Type: 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 | dict[str, Any] | 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 Default: field(default_factory=_generate_tool_call_id)

tool_kind

What the tool is, independent of its name (e.g. 'tool-search'), or None if the tool declares no kind.

See BaseToolReturnPart.tool_kind for the full semantics.

Type: ToolPartKind | 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 | 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 | None Default: None

provider_details

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

Type: dict[str, Any] | None Default: None

typed_args

The arguments validated against the shape the part’s kind declares, or None if they don’t fit yet.

None means the arguments are incomplete (still streaming in) or don’t validate: arguments given as a JSON string aren’t validated until this is read, so check for None even on a finalized response. On a base part, or one whose kind declares no arguments shape, it is the arguments as a dictionary. args itself keeps the base type, as it may still hold the raw JSON string.

Type: ArgsT_co | None

Methods

args_as_dict

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[str, Any]

Parameters

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.

args_as_json_str

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.

The string is always compact JSON serialized from args_as_dict, keeping key order, even when args is already a JSON string: a model’s raw arguments may contain whitespace ({"a": 1}), while the same call loaded back from a UI protocol or storage as a dict serializes compactly. Rendering both the same way keeps the request bytes, and with them the provider’s prompt cache, stable across that round trip.

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.

Returns

has_content

def has_content() -> bool

Return True if the tool call has content.

Returns

ToolCallPart

Bases: BaseToolCallPart[ArgsT_co]

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[‘tool-call’] Default: 'tool-call'

Methods

__init_subclass__

def __init_subclass__(
    cls,
    *,
    kind: ToolKind[ArgsT_co, Any] | None = None,
    **kwargs: Any,
) -> None

Returns

narrow_type

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

Returns

ToolCallPart

NativeToolCallPart

Bases: BaseToolCallPart[ArgsT_co]

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>.py module that defines the cross-provider TypedDicts, the kind (with ToolKind._core('<emitter>', args=..., content=...), matching the emitting AbstractNativeTool.kind), and the NativeToolCallPart[Args] / NativeToolReturnPart[Content] subclasses that pass it as their kind class argument. As core kinds are in the deserialization union, each subclass also declares tool_kind: Literal['<emitter>'] = '<emitter>' and shadows args / content with the narrower type. (A kind defined outside core is a namespaced ToolKind, and its parts declare nothing but properties.)
Late-import the new module from this file (alongside the existing tool-search import) so registration runs whenever pydantic_ai.messages is imported.
Optionally, add the subclass to ModelResponsePart’s discriminated union and its _TYPED_PART_TAGS entries so it appears in the message JSON schema. Without that, ModelResponse / ModelRequest still promote it once built.

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.

Attributes

part_kind

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

Type: Literal[‘builtin-tool-call’] Default: 'builtin-tool-call'

Methods

__init_subclass__

def __init_subclass__(
    cls,
    *,
    kind: ToolKind[ArgsT_co, Any] | None = None,
    **kwargs: Any,
) -> None

Returns

TypeGuard[MultiModalContent]

narrow_type

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

Returns

NativeToolCallPart

WorkspaceRef

Serializable identity of a workspace environment, without credentials.

Pass it to a later run as workspace= to continue in that environment.

Attributes

provider

Provider that owns the environment.

Type: str

id

Provider-specific identifier for the environment.

Type: str

ModelRequestAttempt

An attempt at a model request that did not produce the response it is recorded on.

A FallbackModel records one for each model it moved on from, on the response of the model that answered (ModelResponse.failed_attempts), or on the FallbackExceptionGroup when every model failed.

Attributes

model_name

The name of the model that was attempted.

Type: str

provider_name

The name of the provider the attempt was sent to.

Type: str | None Default: None

outcome

How the attempt failed.

'error' — the request raised an exception, described by error.
'rejected' — the model returned a response, and a fallback_on response handler rejected it.

Type: Literal[‘error’, ‘rejected’]

error

The exception the attempt raised, as 'ExceptionType: message', or None if it was rejected.

Type: str | None Default: None

timestamp

When the attempt started.

Type: datetime

duration

How long the attempt took, up to the point it failed or its response was rejected.

Type: timedelta

usage

The usage the provider reported for the attempt, including its cost where it can be calculated.

None when the usage is unknown, as it is for an attempt that raised before returning a response.

Type: RequestUsage | None Default: None

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[ModelResponsePart]

usage

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)

model_name

The name of the model that generated the response.

Type: str | 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 Default: field(default_factory=_now_utc)

kind

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

Type: Literal[‘response’] Default: 'response'

provider_name

The name of the LLM provider that generated the response.

Type: str | None Default: None

provider_url

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

Type: str | None Default: None

provider_details

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

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[str | None, pydantic.Field(validation_alias=(pydantic.AliasChoices(provider_response_id, vendor_id)))] Default: None

finish_reason

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

Type: FinishReason | None Default: None

run_id

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

Type: str | 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 | None Default: None

metadata

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

Type: dict[str, Any] | None Default: None

workspace_ref

The workspace environment the run worked in, so a run continuing this history reuses it.

Each response records the ref when it is produced; the last response is refreshed when the run ends. A run with no attached workspace carries the conversation’s ref forward, unless it was started with workspace='new'. Not sent to the model.

Type: WorkspaceRef | None Default: None

history_digest

A digest of this response’s parts and the history it was created from: the messages before it, as sent.

Set by models that continue server-side state, such as OpenAIResponsesModel with openai_previous_response_id, so a later request continues from this response only while it and the messages before it are unchanged. The metadata fields on messages, tool return parts and user prompt TextContent are never sent to the model, so they’re left out, and changing them doesn’t count as a change. Not sent to the model.

Unless the model was given a key, it’s a plain SHA-256, which anyone holding the stored history can use to test guesses at content that was redacted from it later, such as a PIN or an account number. If you redact history after it was sent, give the model a key. Don’t just clear this field: a response without one is trusted and continued from, and the provider still holds the unredacted copy. If you do strip it, clear provider_response_id on the same responses too, so nothing continues from them.

Computing it serializes the whole history before the response on every request that continues server-side state, so it costs local work proportional to the conversation’s length.

Type: str | None Default: None

failed_attempts

Earlier attempts at this request that failed before this response was produced, in order.

A FallbackModel records the models it moved on from here. Their usage is not included in usage, which is this response’s own, but it does count towards the run’s RunUsage and UsageLimits token and cost limits. A rejected response’s parts are not kept. Not sent to the model.

Type: list[ModelRequestAttempt] | None Default: None

state

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. Anthropic pause_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 via StreamedResponse.cancel(), and when a realtime turn is cut off by a barge-in or RealtimeSession.interrupt() — in which case the cut-off point is recorded on the last SpeechPart.interrupted_at_ms.

Type: ModelResponseState Default: 'complete'

text

Get the text in the response, including the transcript of anything spoken.

Type: str | None

thinking

Get the thinking in the response.

Type: str | None

files

Get the files in the response.

Type: list[BinaryContent]

images

Get the images in the response.

Type: list[BinaryImage]

tool_calls

Get the tool calls in the response.

Type: list[ToolCallPart]

native_tool_calls

Get the native tool calls and results in the response.

Type: list[tuple[NativeToolCallPart, NativeToolReturnPart]]

Methods

cost

def cost() -> genai_types.PriceCalculation

Calculate the cost of the usage.

Uses genai-prices. Raises ValueError when the response omitted usage information, since its cost would be incomplete.

Returns

genai_types.PriceCalculation

TextPartDelta

A partial update (delta) for a TextPart that appends text, citations, or both.

Attributes

content_delta

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

Type: 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 | 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[str, Any] | None Default: None

citations_delta

All of the part’s citations, replacing any it has.

They come in one delta, without text, once the part’s text is complete, and the delta also sets provider_details['citations']. Providers that return citations at the end of the response, such as Google, send it then, which can be after the part’s PartEndEvent.

Type: list[Citation] | None Default: None

part_delta_kind

Part delta type identifier, used as a discriminator.

Type: Literal[‘text’] Default: 'text'

Methods

apply

def apply(part: ModelResponsePart) -> TextPart

Apply this text delta to an existing TextPart.

Returns

TextPart — A new TextPart with updated text content.

Parameters

part : 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 | None Default: None

signature_delta

Optional signature delta.

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

Type: str | 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 | 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. 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_kind

Part delta type identifier, used as a discriminator.

Type: Literal[‘thinking’] Default: 'thinking'

Methods

apply

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

Apply this thinking delta to an existing ThinkingPart.

Returns

ThinkingPart | ThinkingPartDelta — A new ThinkingPart with updated thinking content.

Parameters

part : ModelResponsePart | 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 | 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 | dict[str, Any] | 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 | 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 | 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[str, Any] | 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[‘tool_call’] Default: 'tool_call'

Methods

as_part

def as_part() -> ToolCallPart | None

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

Returns

ToolCallPart | None — A ToolCallPart if tool_name_delta is set, otherwise None.

apply

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 | NativeToolCallPart | ToolCallPartDelta — Either a new ToolCallPart or NativeToolCallPart, or an updated ToolCallPartDelta.

Parameters

part : ModelResponsePart | 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.

SpeechPartDelta

A partial update (delta) for a SpeechPart to append transcript text and/or audio data.

Attributes

speaker

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_delta

Transcript text this delta added, if any.

Type: str | None Default: None

transcript

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

audio_chunk

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_kind

Part delta type identifier, used as a discriminator.

Type: Literal[‘speech’] Default: 'speech'

Methods

apply

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.

Returns

SpeechPart — A new SpeechPart with the delta applied.

Parameters

part : ModelResponsePart

The existing model response part, which must be a SpeechPart.

Raises

ValueError — If part is not a SpeechPart.

PartStartEvent

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.

Attributes

index

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

Type: int

part

The newly started ModelResponsePart.

Type: 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[‘text’, ‘thinking’, ‘tool-call’, ‘builtin-tool-call’, ‘builtin-tool-return’, ‘compaction’, ‘file’, ‘speech’] | None Default: None

event_kind

Event type identifier, used as a discriminator.

Type: 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

delta

The delta to apply to the specified part.

Type: ModelResponsePartDelta

event_kind

Event type identifier, used as a discriminator.

Type: 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

part

The complete ModelResponsePart.

Type: 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[‘text’, ‘thinking’, ‘tool-call’, ‘builtin-tool-call’, ‘builtin-tool-return’, ‘compaction’, ‘file’, ‘speech’] | None Default: None

event_kind

Event type identifier, used as a discriminator.

Type: 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 | None

tool_call_id

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

Type: str | None

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘final_result’] Default: 'final_result'

EnqueuedMessagesEvent

An event indicating that messages enqueued via enqueue were delivered into the run’s message history.

Emitted at delivery time, carrying the delivered content itself — 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 delivered content will be visible through it.

Content enqueued during a tool call goes into the ModelRequest carrying that call’s ToolReturnPart, right after it. Its messages then holds a request of its own with the delivered parts, a view of what was delivered rather than a message in history, and parts holds those parts as they sit in history. Events are emitted in the order their content lands in history.

Attributes

enqueue_id

The ID of the enqueue call that produced this content.

Type: str

messages

The delivered messages: the ones added to the run’s message history, or, for content that went into a tool call’s request, a request of its own holding the delivered parts.

Type: tuple[ModelMessage, …]

parts

The parts added to the request carrying a tool call’s return, as they sit in history, or () when the content was added as its own messages.

Type: tuple[ModelRequestPart, …] Default: ()

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘enqueued_messages’] Default: 'enqueued_messages'

ToolCallEvent

Base class for events emitted when a tool call is about to be invoked, or is settled without being invoked.

A call that isn’t executed in this step still gets a call event, with args_valid=None, followed by the result event carrying the return recorded in message history.

Match against this in a case to handle FunctionToolCallEvent and OutputToolCallEvent together.

Attributes

part

The tool call to make.

Type: ToolCallPart

args_valid

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, because the call isn’t executed in this step. This is the case for a resumed deferred call whose supplied result isn’t ToolApproved (e.g. ToolDenied), and for an output, function or deferred tool call skipped because a final result was already processed. The matching result event carries the return recorded in message history.

Type: bool | None Default: None

tool_call_id

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

Type: str

FunctionToolCallEvent

Bases: ToolCallEvent

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

When args_valid is None, the tool isn’t executed in this step; see ToolCallEvent.args_valid.

Attributes

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘function_tool_call’] Default: 'function_tool_call'

OutputToolCallEvent

Bases: 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[‘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 and OutputToolResultEvent together.

Attributes

part

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

Type: ToolReturnPart

tool_call_id

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

Type: str

FunctionToolResultEvent

Bases: ToolResultEvent

An event indicating the result of a function tool call.

Attributes

content

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

Type: str | Sequence[UserContent] | None Default: None

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘function_tool_result’] Default: 'function_tool_result'

ToolAvailabilityDeltaEvent

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.

Attributes

part

The tool availability delta part that will be recorded in message history.

Type: ToolAvailabilityDeltaPart

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘tool_availability_delta’] Default: 'tool_availability_delta'

OutputToolResultEvent

Bases: ToolResultEvent

An event indicating the result of an output tool call.

Attributes

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘output_tool_result’] Default: 'output_tool_result'

DeferredToolRequestsEvent

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.

Attributes

requests

The batch of tool calls that require external execution or approval.

Type: DeferredToolRequests

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘deferred_tool_requests’] Default: 'deferred_tool_requests'

DeferredToolResultsEvent

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.

Attributes

results

The results for the deferred tool calls, keyed by tool call ID.

Type: DeferredToolResults

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘deferred_tool_results’] Default: 'deferred_tool_results'

RealtimeTurnCompleteEvent

The model exchange is over: what RealtimeSession.wait_for_reply() waits for has come.

It is synthesized by the session when a response ends and the model owes nothing more: no reply to an input sent (text, a tool’s result, a request for a response), no answer to a tool call, and no response still under way. It also ends an exchange a failure ended (a tool raised and its failure didn’t go out to the model, or a tool’s result would pass a usage limit), once. Input transcription can finish after this event. On WebRTC sidebands, provider playback can also continue until RealtimeOutputSpeechEndEvent.

Attributes

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘realtime_turn_complete’] Default: 'realtime_turn_complete'

RealtimeInputSpeechStartEvent

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.

Attributes

item_id

Provider id of the user input item this speech segment belongs to, when reported.

Type: str | None Default: None

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘realtime_input_speech_start’] Default: 'realtime_input_speech_start'

RealtimeResponseInterruptedEvent

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.

Attributes

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘realtime_response_interrupted’] Default: 'realtime_response_interrupted'

RealtimeInputSpeechEndEvent

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.

Attributes

item_id

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_kind

Event type identifier, used as a discriminator.

Type: Literal[‘realtime_input_speech_end’] Default: 'realtime_input_speech_end'

RealtimeOutputSpeechStartEvent

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.

Attributes

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘realtime_output_speech_start’] Default: 'realtime_output_speech_start'

RealtimeOutputSpeechEndEvent

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.

Attributes

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘realtime_output_speech_end’] Default: 'realtime_output_speech_end'

RealtimeInputTranscriptionErrorEvent

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.

Attributes

message

Human-readable error message.

Type: str

type

Provider error category, if any.

Type: str | None Default: None

code

Provider error code, if any.

Type: str | None Default: None

item_id

Provider conversation-item ID for the affected user turn, when available.

Type: str | None Default: None

content_index

Content index within the affected user turn, when available.

Type: int | None Default: None

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘realtime_input_transcription_error’] Default: 'realtime_input_transcription_error'

RealtimeSessionReconnectEvent

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, a stored OpenAI GPT-Live session) or by the session replaying its local history into the fresh server-side conversation (OpenAI/Azure OpenAI, an unstored GPT-Live session).

Attributes

state_restored

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_kind

Event type identifier, used as a discriminator.

Type: Literal[‘realtime_session_reconnect’] Default: 'realtime_session_reconnect'

RealtimeSessionErrorEvent

A provider-reported error occurred in the session.

Attributes

message

Human-readable error message.

Type: str

type

Provider error category, e.g. invalid_request_error or server_error.

It can also be a category Pydantic AI defines for a condition it detects itself: 'tool_calls_abandoned' means Eleven Realtime abandoned tool calls whose results hadn’t been sent yet, so those results won’t reach the model.

Type: str | None Default: None

code

Provider error code, if any.

Type: str | None Default: None

recoverable

Whether the session can continue. A protocol error is recoverable; a dropped connection is not.

Type: bool Default: True

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘realtime_session_error’] Default: 'realtime_session_error'

CustomEvent

An application-defined event emitted into the agent’s event stream.

Emit these from tools or code driving Agent.iter via RunContext.emit or AgentRun.emit to surface progress updates, intermediate results, or status information to consumers of the stream without adding to the model’s context.

Define an event by subclassing this class with typed fields carrying the payload:

from dataclasses import dataclass

from pydantic_ai import CustomEvent


@dataclass(kw_only=True)
class OperationProgressEvent(CustomEvent):
    done: int
    total: int

Subclasses must be dataclasses. Each subclass registers itself under its name — derived from the class name (OperationProgressEvent -> 'operation_progress') unless overridden with a name class argument — so instances round-trip through serialization back to the subclass, and consumers can use isinstance checks instead of matching name strings. Deserializing an event whose name isn’t registered in the current process yields an UnknownCustomEvent.

Attributes

name

The application-defined name of the event.

On registered subclasses it defaults to the registered event name, so it never needs to be passed.

Type: str Default: ''

tool_call_id

The tool call this event is associated with, if any.

Automatically stamped from RunContext.tool_call_id when the event is emitted from within a tool call and doesn’t already set one, so consumers can attribute the event to the originating tool call.

Type: str | None Default: None

tool_name

The name of the tool this event is associated with, if any; stamped like tool_call_id.

Type: str | None Default: None

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘custom’] Default: 'custom'

ui

Whether UI event streams forward this event class to the frontend.

Custom events are application-owned, so they are forwarded by default: the application decided both to emit the event and to serve that frontend. Set ui=False as a class argument on an event that exists only for server-side consumers — metrics, audit logs, an event_stream_handler of your own:

from dataclasses import dataclass

from pydantic_ai import CustomEvent


@dataclass(kw_only=True)
class IndexProgressEvent(CustomEvent, ui=False):
    done: int
    total: int

It still reaches every in-process consumer; only the UI adapters skip it. Subclasses inherit the setting, and because the check happens before the protocol-specific handler, third-party adapters honor it too. An event that needs a different payload for the frontend rather than no payload at all should override to_payload() instead.

The flag lives on the class rather than on the wire, so an event deserialized in a process that hasn’t imported its defining module arrives as an UnknownCustomEvent, whose ui says nothing about what the application declared. Those are not forwarded either, so an event that crosses a process boundary can’t leak a payload its class had opted out of. Import the modules that define your events in the process that serves the frontend, or its custom events won’t reach the frontend at all.

Type: bool Default: True

Methods

to_payload

def to_payload() -> Any

The event’s payload: the subclass’s own typed fields.

This is what the UI adapters send to the frontend (AG-UI CustomEvent.value, Vercel AI data-{name} chunk data), with the same shape whether or not the event was emitted from inside a tool call. Override to customize the payload shape — e.g. to include self.tool_call_id when the frontend needs to attribute the event to a tool call.

Returns

Any

__get_pydantic_core_schema__

@classmethod

def __get_pydantic_core_schema__(
    cls,
    source: Any,
    handler: pydantic.GetCoreSchemaHandler,
) -> pydantic_core.core_schema.CoreSchema

Build this family’s tagged union, instead of the plain dataclass schema pydantic would infer.

The set of event classes isn’t known when this module is imported — applications and capabilities register their own by defining them — so the union can’t be written down as a static Annotated[... , Field(discriminator=...)] the way the closed event types are. This override builds it from the registry each time a schema is generated, and routes a tag no class has registered to UnknownCustomEvent, so an event from a process that imported a module this one didn’t still round-trips instead of failing validation.

Only the family base builds the union; a subclass gets its own dataclass schema, so annotating a concrete event type validates just that event.

Returns

pydantic_core.core_schema.CoreSchema

UnknownCustomEvent

Bases: CustomEvent

A typed custom event whose name isn’t registered in this process.

Produced when deserializing an event emitted by a process that had the defining module imported (e.g. across a durable execution boundary). The payload fields ride in data, and serialization re-flattens them, so a downstream consumer that does have the defining module imported recovers the typed event.

Attributes

data

The original event’s payload fields, or None if it had none.

Only the family’s validator fills this, and it always gathers the wire dict’s unrecognized keys, so the mapping is exactly the payload the defining process serialized.

Type: dict[str, Any] | None Default: None

Methods

to_payload

def to_payload() -> dict[str, Any] | None

The event’s payload: the original event’s fields, preserved in data.

Returns

dict[str, Any] | None

CapabilityEvent

A typed event emitted by a capability into the agent’s event stream.

Capability authors define dataclass subclasses with a namespace shared by their event family. The emitting capability’s run id is stamped by RunContext.emit.

Events dispatch at their stream position by default. Decision events can instead pass dispatch='immediate' as a class argument so listeners run before RunContext.emit returns:

from dataclasses import dataclass

from pydantic_ai import CapabilityEvent


@dataclass(kw_only=True)
class CheckpointStartEvent(CapabilityEvent, namespace='checkpoint', dispatch='immediate'):
    cancelled: bool = False
    cancel_reason: str | None = None

    def cancel(self, reason: str | None = None) -> None:
        self.cancelled = True
        self.cancel_reason = reason

The dispatch mode is inherited by subclasses of a concrete event class.

Attributes

event_dispatch

When capability and application listeners receive the event.

Type: Literal[‘stream’, ‘immediate’] Default: 'stream'

kind

The namespaced event kind, injected as the default on registered subclasses.

Type: str Default: ''

capability_id

The run id of the capability that emitted this event.

Stamped at emission when unset; a pre-set value is preserved, so a capability re-emitting an event on behalf of another instance can keep the original attribution.

Type: str | None Default: None

tool_call_id

The associated tool call id, when emitted by a capability-contributed tool.

Type: str | None Default: None

tool_name

The associated tool name, when emitted by a capability-contributed tool.

Type: str | None Default: None

event_kind

Event type identifier, used as a discriminator.

Type: Literal[‘capability’] Default: 'capability'

Methods

__get_pydantic_core_schema__

@classmethod

def __get_pydantic_core_schema__(
    cls,
    source: Any,
    handler: pydantic.GetCoreSchemaHandler,
) -> pydantic_core.core_schema.CoreSchema

Build this family’s tagged union, instead of the plain dataclass schema pydantic would infer.

The set of event classes isn’t known when this module is imported — applications and capabilities register their own by defining them — so the union can’t be written down as a static Annotated[... , Field(discriminator=...)] the way the closed event types are. This override builds it from the registry each time a schema is generated, and routes a tag no class has registered to UnknownCapabilityEvent, so an event from a process that imported a module this one didn’t still round-trips instead of failing validation.

Only the family base builds the union; a subclass gets its own dataclass schema, so annotating a concrete event type validates just that event.

Returns

pydantic_core.core_schema.CoreSchema

UnknownCapabilityEvent

Bases: CapabilityEvent

A typed capability event whose kind isn’t registered in this process.

Produced when deserializing an event emitted by a process that had the defining module imported. The payload fields ride in data, and serialization re-flattens them, so a downstream consumer that does have the defining module imported recovers the typed event.

Attributes

data

The original event’s payload fields, or None if it had none.

Type: dict[str, Any] | None Default: None

is_multi_modal_content

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

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

Returns

parse_tool_kind

def parse_tool_kind(value: str) -> ToolPartKind | None

Return value if it’s the id of a defined ToolKind, 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. A run uses it to refuse a tool with an undefined kind when it collects its tools; a stored ToolDefinition with one still loads.

Returns

ToolPartKind | None

post_compaction_window

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.

Returns

narrow_message_parts

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 that keeps its tool_kind, except that one of core’s kinds is stripped when the data doesn’t fit it (see ToolCallPart.narrow_type).

A ModelResponse or ModelRequest already promotes its parts when it’s built, so this only changes parts that were given a tool_kind, or whose kind was registered, after their message was built.

Returns

repair_messages

def repair_messages(
    messages: Sequence[ModelMessage],
    *,
    repair_last_response: bool = True,
) -> list[ModelMessage]

Make a message history provider-valid.

Drops orphaned tool results, synthesizes a ToolReturnPart for each dangling tool call, and merges adjacent compatible messages. The same repair runs before every model request, so you don’t normally need to call this for history passed to Agent.run. See Making histories provider-valid for the full rules.

Use this before adding a new user prompt to history whose final response has unanswered tool calls, which Agent.run refuses, or when a store, UI, or capability outside a run needs to record or pass on a history it knows is runnable. The repair is deterministic and idempotent: repairing twice is a no-op and never churns a provider’s prompt-cache prefix. Synthesized returns carry {'pydantic_ai_synthesized_tool_return': True} in metadata so you can distinguish them from real results.

Returns

Parameters

messages : Sequence[ModelMessage]

The message history to repair.

repair_last_response : bool Default: True

Whether to close out tool calls in the final response. Defaults to True. Pass False to leave that live frontier alone: those calls can still be answered by resuming the run with this history and no new prompt, or by passing deferred_tool_results; repairing them would abandon that work.

sanitize_messages

def sanitize_messages(
    messages: Sequence[ModelMessage],
    *,
    strip_system_prompts: bool = True,
    strip_instructions: 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,
    strip_workspace_refs: bool = True,
    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 and instruction records (disable with strip_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 a ModelRequest with no parts, the request is dropped from history entirely. RetryFeedbackParts are kept, so the model still sees why it corrected itself: feedback that reaches the model in the user voice is kept as sent, since a client can write user text anyway, and 'no_output' feedback, the one cause rendered in the system voice, becomes the same fenced, attributed user text: a client can forge the part, so it can’t earn the system voice, whatever it says. A tool-less legacy RetryPromptPart is translated into the feedback part it always meant and takes the same rule.
ModelRequest.instructions, resetting it to None (disable with strip_instructions=False). An agent run sends the agent’s own instructions instead, but a direct Model.request call without instruction_parts falls back to the instructions recorded in history. Every request an agent run records carries them, so this doesn’t warn.
FileUrl parts whose URL scheme is not in allowed_file_url_schemes (default http/https). Non-HTTP schemes like s3:// or gs:// 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_download values other than False that aren’t in allowed_file_url_force_download, resetting them to False. Both True and 'allow-local' are reset by default. Applies to file URLs in user content and those nested in tool return parts.
TextContent.metadata on the text items of a UserPromptPart, resetting it to None and keeping the text. Metadata is never sent to the model, but application code and capabilities read it to recognize content they added themselves, such as a background task’s report, so a client that can set it could make its own text pass as theirs.
UploadedFile items unless allow_uploaded_files=True. Like a non-HTTP FileUrl, an UploadedFile references 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.
ModelResponse.workspace_ref, resetting it to None (disable with strip_workspace_refs=False). The most recent reference in history is otherwise offered to a capability’s get_workspace, so a client that can set it could point a reconnecting capability at an environment it attaches to using server-side provider credentials. Reconnect explicitly by passing an authorized workspace= instead.
The framework-reserved __pydantic_ai__ key from ModelRequest.metadata and ModelResponse.metadata, keeping your own keys (and resetting metadata to None if nothing else is left). Pydantic AI and its capabilities keep state there that they act on in later runs, so it is only honored on trusted server-side message_history. On client-held history that state is computed again where it’s needed: a file FileUnderstanding described is described again, for example.
ToolCallParts at the end of the history that aren’t in resolved_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 a NativeToolReturnPart in 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 leading SystemPromptParts: they are re-sent to the model even where the provider’s own compaction state would normally let them be skipped.
CompactionParts, when strip_compaction_parts=True (off by default). Everything before a compaction part is hidden from the model, so pass True whenever you combine the sanitized history with trusted server-side message_history — a client-supplied compaction part would hide that server-side history. The UI adapters apply this rule automatically when a run combines server-side message_history with client-submitted messages.

Returns

Parameters

messages : Sequence[ModelMessage]

Messages to sanitize.

strip_system_prompts : bool Default: True

Whether to strip SystemPromptParts, InstructionDeltaParts and InstructionBaselineParts, and demote 'no_output' RetryFeedbackParts to fenced user text. Other retry feedback is kept either way.

strip_instructions : bool Default: True

Whether to reset ModelRequest.instructions to None.

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.

strip_workspace_refs : bool Default: True

Whether to reset ModelResponse.workspace_ref to None. On by default; pass False only when the history comes from storage the application trusts, so that a run continues in the environment those responses were produced in.

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.

FinishReason

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

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 while iteration is in flight.
'suspended': the model paused mid-turn and expects a continuation request. Used by Anthropic pause_turn and OpenAI background mode. Pydantic AI issues these continuations transparently for both agent.run and agent.run_stream, merging every segment into a single completed ModelResponse, 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 via StreamedResponse.cancel(), and when a realtime turn is cut off by a barge-in or RealtimeSession.interrupt() — in which case the cut-off point is recorded on the last SpeechPart.interrupted_at_ms.

Type: TypeAlias Default: Literal['complete', 'incomplete', 'suspended', 'interrupted']

ModelRequestState

Lifecycle state of a model request.

Type: TypeAlias Default: Literal['complete', '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 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 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')]

UploadedFileProviderName

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

MultiModalContent

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

UserContent

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

RETURN_VALUE_KEY

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

Default: 'return_value'

tool_return_content_ta

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

ToolPartKind

What a tool is, independent of its name: the id of a ToolKind.

Set on BaseToolCallPart.tool_kind, BaseToolReturnPart.tool_kind, and ToolDefinition.tool_kind. A user-defined kind is '{namespace}.{name}', as in 'inventory.lookup'; core’s 'tool-search' and 'capability-load' are the only kinds without a namespace. See Typed tool parts.

A part may carry a kind that isn’t defined in the current process, for example when it was recorded by a process that imported the defining module. It then stays a base part that keeps its tool_kind, so it round-trips and is promoted wherever the kind is defined.

Distinct from ToolDefinitionKind (invocation semantics — 'function', 'output', 'external', 'unapproved').

Type: TypeAlias Default: str

ToolRetryCause

Why a tool call has to be made again, recorded as the cause of a retried ToolReturnPart.retry.

'validation_error': the call’s arguments, or an output tool’s result, failed validation.
'model_retry': the tool, its args_validator, a tool hook, or a HandleDeferredToolCalls handler raised ModelRetry, or the call timed out.
'unknown_tool': the model called a tool name that doesn’t exist.
'unavailable_tool': the tool exists but can’t be called at this step, e.g. it hasn’t been revealed by tool search or its capability hasn’t been loaded.

Type: TypeAlias Default: Literal['validation_error', 'model_retry', 'unknown_tool', 'unavailable_tool']

RetryFeedbackCause

What made a response unusable, recorded as the cause of RetryFeedbackPart.retry.

'validation_error': the output failed validation against the expected schema. The feedback quotes what the model itself wrote, which may in turn quote untrusted user input, so it goes in the user voice inside a <validation_errors> fence rather than in the harness’s own.
'no_output': the response carried nothing usable as output (e.g. thinking only). The agent loop’s fixed text goes in the system voice; a 'no_output' part with any other content, such as one your own code builds, is fenced in the user voice like a 'model_retry'.
'model_retry': an output validator, output function, or model hook raised ModelRetry. Its message commonly interpolates the output it rejects, so it goes in the user voice too, inside a <retry_feedback> fence.

Only 'no_output' carries fixed framework text, so only it reaches the model in the system voice.

Type: TypeAlias Default: Literal['validation_error', 'no_output', 'model_retry']

RetryCauseT_co

The cause a RetryInfo records: a ToolRetryCause or a RetryFeedbackCause.

Default: TypeVar('RetryCauseT_co', bound=str, covariant=True, default=(Literal[ToolRetryCause, RetryFeedbackCause]))

ToolKindLike

How a tool declares its kind: a ToolKind, or its id.

Accepted by tool_kind on ToolDefinition, Tool and the tool decorators. See Typed tool parts.

Type: TypeAlias Default: 'ToolKind | ToolPartKind'

ArgsT_co

The arguments shape of a ToolKind and of the typed call parts registered for it.

Default: TypeVar('ArgsT_co', covariant=True, default=Any)

ContentT_co

The result shape of a ToolKind and of the typed return parts registered for it.

Default: TypeVar('ContentT_co', covariant=True, default=Any)

INTERRUPTED_TOOL_RETURN_CONTENT

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

ERROR_OUTCOMES

The BaseToolReturnPart.outcome values that reach the model as an error.

Both went wrong from the model’s point of view — the tool raised, or its call was rejected before it could run — so both take the provider’s native error channel (Anthropic is_error, Bedrock status='error', Google’s error key) and the {"error": ...} wrapper where there is none. The other outcomes ('denied', 'interrupted') are ordinary results whose content says what happened.

Type: tuple[Literal[‘failed’, ‘retried’], …] Default: ('failed', 'retried')

InstructionSource

The source that authored an instruction part.

Type: TypeAlias Default: AgentInstructionSource | ToolsetInstructionSource | CapabilityInstructionSource | RunInstructionSource

SerializedInstructionId

An InstructionId that persists as the string it renders to.

Type: TypeAlias Default: Annotated[InstructionId | None, pydantic.BeforeValidator(_deserialize_instruction_id), pydantic.PlainSerializer(_serialize_instruction_id, return_type=(str | None), when_used='json')]

InstructionChangePolicy

How changes to an instruction block are delivered; see InstructionPart.on_change.

Type: TypeAlias Default: Literal['rewrite', 'append']

CitationSource

Where a citation’s information came from.

Type: TypeAlias Default: Annotated[WebCitationSource | DocumentCitationSource, pydantic.Discriminator('kind')]

CitationAnchor

Which part of TextPart.content a citation is about.

Type: TypeAlias Default: Annotated[ContentCitationAnchor | MarkerCitationAnchor, pydantic.Discriminator('kind')]

STANDING_PROMPT_PLANTED_KEY

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'

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[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[RetryFeedbackPart, pydantic.Tag('retry-feedback')] | Annotated[ToolAvailabilityDeltaPart, pydantic.Tag('tool-availability-delta')] | Annotated[InstructionDeltaPart, pydantic.Tag('instruction-delta')] | Annotated[InstructionBaselinePart, pydantic.Tag('instruction-baseline')] | Annotated[pydantic.SerializeAsAny[ToolReturnPart], pydantic.BeforeValidator(_translate_legacy_retry_part), pydantic.Tag('legacy-retry-tool-return')] | Annotated[pydantic.SerializeAsAny[RetryFeedbackPart], pydantic.BeforeValidator(_translate_legacy_retry_part), pydantic.Tag('legacy-retry-feedback')], 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')] | Annotated[SpeechPart, pydantic.Tag('speech')], 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 for (de)serializing messages.

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

SYNTHESIZED_TOOL_RETURN_METADATA_KEY

Metadata key set to True on ToolReturnParts synthesized for tool calls that never received a result.

Default: 'pydantic_ai_synthesized_tool_return'

ModelResponsePartDelta

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

Default: Annotated[TextPartDelta | ThinkingPartDelta | ToolCallPartDelta | SpeechPartDelta, 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.

CUSTOM_EVENT_TYPES

Registry of CustomEvent subclasses, keyed by their name.

Subclasses register automatically when their class is defined, so an event type is only deserializable in processes that have imported the module defining it; see UnknownCustomEvent for what happens otherwise.

Type: dict[str, type[CustomEvent]] Default: _EventRegistry[type['CustomEvent']]()

CAPABILITY_EVENT_TYPES

Registry of CapabilityEvent subclasses, keyed by kind.

Type: dict[str, type[CapabilityEvent]] Default: _EventRegistry[type['CapabilityEvent']]()

RealtimeSessionEvent

An event that occurs only in realtime session streams.

AgentStreamEvent

An event in an agent run or realtime session stream.

ToolSearchArgs

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.

Attributes

queries

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_tools fallback: single-item list with the keywords string.

Type: list[str]

ToolSearchReturnContent

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.

Attributes

discovered_tools

Matches ordered by relevance. An empty list means “search ran, nothing matched”.

Type: list[ToolSearchMatch]

message

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]

ToolSearchCallPart

Bases: ToolCallPart[ToolSearchArgs]

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.

part.tool_kind == 'tool-search' answers which tool a part belongs to, whatever its outcome and whether search ran server-side or locally. To read a search result, check isinstance(part, ToolSearchReturnPart | NativeToolSearchReturnPart) instead: a failed or denied return keeps its tool_kind, but its content is an error, not the typed result.

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.

Attributes

tool_name

Default tool name for the typed subclass. Discrimination drives off tool_kind.

Type: Literal[‘search_tools’] Default: 'search_tools'

args

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

tool_kind

Discriminator for the typed subclass (framework-emitted search_tools call).

Type: Literal[‘tool-search’] Default: 'tool-search'

queries

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

Type: list[str]

ToolSearchReturnPart

Bases: ToolReturnPart[ToolSearchReturnContent]

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.

Shadows content with a narrower ToolSearchReturnContent TypedDict.

Attributes

content

Discovered-tools payload.

Narrows the parent’s ToolReturnContent to a typed ToolSearchReturnContent.

Type: ToolSearchReturnContent Default: field(kw_only=True)

tool_name

Default tool name for the typed subclass. Discrimination drives off tool_kind.

Type: Literal[‘search_tools’] Default: 'search_tools'

tool_kind

Discriminator for the typed subclass (framework-emitted search_tools return).

Type: Literal[‘tool-search’] Default: 'tool-search'

discovered_tools

Subfield accessor for content['discovered_tools'].

Type: list[ToolSearchMatch]

message

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

Type: str | None

RetryFeedbackPart

Pydantic AI’s own feedback about a model response it couldn’t use.

Attributes

content

Details of why the response couldn’t be used.

If the retry was triggered by a ValidationError, this will be a list of error details, serialized into the fenced block the model is shown.

Type: list[pydantic_core.ErrorDetails] | str

retry

What made the response unusable, which decides the voice the feedback reaches the model in, and which output retry this is.

See RetryFeedbackCause for the causes and the voice each one takes. The agent loop fills in attempt and max_retries from the run’s output-retry budget.

Type: RetryInfo[RetryFeedbackCause]

timestamp

The timestamp, when the retry was triggered.

Type: datetime Default: field(default_factory=_now_utc)

part_kind

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

Type: Literal[‘retry-feedback’] Default: 'retry-feedback'

Methods

model_response

def model_response() -> str

Return the text the model is shown, in the voice retry.cause calls for.

What prepare_messages adds around this is the voice, not the wording: the part type it goes into, and the <system> tagging a provider without a mid-conversation system message needs.

Returns