Class for defining "agents" - a way to have a specific type of "conversation" with an LLM. Agents are generic in the dependency type they take [`

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

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

A model controlled by a local function. Apart from `__init__`, all methods are private or match those of the base class.

A user prompt, generally written by the end user. Content comes from the `user_prompt` parameter of [`Agent.run`][pydantic_ai.agent.AbstractAgent

A plain text response from a model.

LLM usage associated with a single request. This is an implementation of `genai_prices.types.AbstractUsage` so it can be used to calculate the pr

Configuration for an agent's request to a model, specifically related to tools and output handling.

A tool call from a model.

Provider for OpenAI API. Changing `base_url` does not change the OpenAI model profile selection. For another service, use its dedicated provi

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

A model that uses the Anthropic API. Internally, this uses the [Anthropic Python client](https://github.com/anthropics/anthropic-sdk-python) to i

Provider for Anthropic API.

A model that uses the OpenAI Responses API. The [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) is the new A

Error caused by a usage mistake by the application developer — You!

Definition of a tool passed to a model. This is used for both function tools and output tools.

A toolset that lets Python functions be used as tools. See [toolset docs](../toolsets.md#function-toolset) for more information.

A connection that replays a fixed list of events and records what is sent.

The provider reported that its current response is done. This codec event is consumed by the session to finalize a [`ModelResponse`][pydantic

LLM usage associated with an agent run. Responsibility for calculating request usage is on the model; Pydantic AI simply sums the usage informati

A model that uses the OpenAI API. Internally, this uses the [OpenAI Python client](https://github.com/openai/openai-python) to interact with the

A model that uses the Bedrock Converse API.

A thinking response from a model.

A model that uses Gemini via `generativelanguage.googleapis.com` API. This is implemented from scratch rather than using a dedicated SDK, good AP

A capability that registers a native tool with the agent. Wraps a single [`AgentNativeTool`][pydantic_ai.tools.AgentNativeTool] — either a static

Provider for xAI API (native xAI SDK).

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

A tool return message from a native tool. For native tools with a stable cross-provider shape (currently `tool_search`), a `NativeToolReturnP

A toolset for connecting to an MCP server. `MCPToolset` is the recommended way to use [Model Context Protocol](https://modelcontextprotocol.io)

A model that uses the xAI SDK to interact with xAI models.

The model is requesting a tool call.

A message back to a model asking it to try again. This can be sent for a number of reasons: * Pydantic validation of tool arguments failed,

Settings to configure an LLM. Includes only settings which apply to multiple models / model providers, though not all of these settings are s

A builder for constructing executable graph definitions. GraphBuilder provides a fluent interface for defining nodes, edges, and routing in a

Settings used for an Anthropic model request.

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

Describes how requests to and responses from specific models or families of models need to be constructed and processed to get the best results, indep

Options for instrumenting models and agents with OpenTelemetry. Used in: - [`Instrumentation`][pydantic_ai.capabilities.Instrumentation] cap

The model's textual output (partial or final): an audio transcript, or plain text output.

Temporal worker plugin for a specific Pydantic AI agent. Accepts either a regular `Agent` carrying a [`TemporalDurability`][pydantic_ai.durab

A system prompt, generally written by the application developer. This gives the model context and guidance on how to respond.

Exception to raise to request a model retry. Can be raised from tool functions, output validators, and capability hooks (such as `after_model

A message as displayed in the UI by Vercel AI Elements.

A native tool that allows your agent to search the web for information. The parameters that PydanticAI passes depend on the model, as some parame

Settings used for an OpenAI Responses model request. ALL FIELDS MUST BE `openai_` PREFIXED SO YOU CAN MERGE THEM WITH OTHER MODELS.

A URL to an image.

Settings for Bedrock models. See [the Bedrock Converse API docs](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.htm

A model that yields a pre-built connection and records connect arguments.

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 lit

Capability that instruments agent runs with OpenTelemetry/Logfire tracing. When added to an agent via `capabilities=[Instrumentation(...)]`, this

A text part of a message.

OpenAI Realtime API model. Authentication and the base URL come from a [`Provider`][pydantic_ai.providers.Provider], mirroring [`OpenAIChatMo

A model that uses one or more fallback models upon failure. Apart from `__init__`, all methods are private or match those of the base class.

Limits on model usage. The request count is tracked by pydantic_ai, and the request limit is checked before each request to the model. Token

A sequence of path items defining data flow through the graph. Paths represent the route that data takes through the graph, including transfo

An event indicating that a new part has started. If multiple `PartStartEvent`s are received with the same index, the new one should fully rep

Binary content that's guaranteed to be an image.

Holds cross-evaluator defaults for online evaluation. Create instances for different evaluation configurations, or use the global `DEFAULT_CO

Spoken audio exchanged during a realtime session, paired with its transcript. This part is a member of both [`ModelRequestPart`][pydantic_ai.mess

Submit message request.

A cache point marker for prompt caching. Can be inserted into UserPromptPart.content to mark cache boundaries. Models that don't support cach

A minimal stand-in for a `websockets` client connection. Running out of scripted frames stands in for the server closing the connection normally,

Provider for the Gemini API (formerly Google AI Studio / Google GLA).

Profile for models used with `OpenAIChatModel`. ALL FIELDS MUST BE `openai_` PREFIXED SO YOU CAN MERGE THEM WITH OTHER MODELS.

Provider for OpenRouter API.

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 p

Marker class to use a tool for output and optionally customize the tool. Example: ```python {title="tool_output.py"} from pydantic import

Marker class to use the model's native structured outputs functionality for outputs and optionally customize the name and description. Example:

Register hook functions via decorators or constructor kwargs. For extension developers building reusable capabilities, subclass [`AbstractCap

Provider for Mistral API.

A reference to a file uploaded to a provider's file storage by ID. This allows referencing files that have been uploaded via provider-specific fi

Marker class to use a prompt to tell the model what to output and optionally customize the prompt. Example: ```python {title="prompted_output

A model that uses Mistral. Internally, this uses the [Mistral Python client](https://github.com/mistralai/client-python) to interact with the API

Information about the current call.

Capability that makes an agent durable by routing I/O through DBOS steps. The capability routes model requests, MCP I/O, and optionally event-str

A tool function for an agent.

A transcription of the user's audio input (partial or final). Providers with per-item IDs use `item_id` to associate interleaved transcripts with

An event indicating a delta update for an existing part.

Extends OpenAIChatModel to capture extra metadata for Openrouter.

An event indicating that a part is complete.

A chunk of audio output from the model.

Capability that makes an agent durable by routing I/O through Prefect tasks. Built on the declarative base: the base owns toolset/model/event ass

A capability that combines multiple capabilities. When any child returns a fresh instance from [`for_agent`][pydantic_ai.capabilities.Abstrac

High-level interface for generating text embeddings. The `Embedder` class provides a convenient way to generate vector embeddings from text u

Image generation capability. Uses the model's native image generation when available. When the model doesn't support it, the [direct image ge

Results for deferred tool calls from a previous run that required approval or external execution. The tool call IDs need to match those from the

The URL of the document.

A live WebSocket connection to the OpenAI Realtime API.

A file response from a model.

A native tool that allows your agent to execute code. Supported by: * Anthropic * OpenAI Responses * Google * Bedrock (Nova2.0)

Collects sink submissions for test assertions.

A toolset that dynamically builds a toolset using a function that takes the run context.

Capability that makes an agent durable by routing I/O through Temporal activities. When added to an agent, this capability intercepts model reque

A deterministic image generation model for testing. This model returns a single 1x1 PNG without making any API calls, and records the reference i

UI adapter for the Vercel AI protocol.

Provider for Azure OpenAI API. See <https://azure.microsoft.com/en-us/products/ai-foundry> for more information.

A compaction part that summarizes previous conversation history. Compaction parts contain an opaque or readable summary of prior messages, pr

The result of an embedding operation. This class contains the generated embeddings along with metadata about the operation, including the ori