Skip to content
PaPy

PydanticAI: Comprehensive Guide

Single-page tutorial to PydanticAI V2 — installation, agents, RunContext, tools, structured output, dependency injection and upgrading from V1 — followed by a map of the public API and where each part is documented.

Checked against pydantic-ai 2.68.0 (2026-11-19). Requires Python 3.11+. The examples were run against that release with TestModel in place of the real model.

This page takes you from installation to a typed, tool-using agent, then maps the rest of the public API to the pages that cover it. Topic pages carry the depth: output types, toolsets, streaming, testing and the others listed in the API map.

  1. Core concepts
  2. Installation and setup
  3. Core fundamentals
  4. Simple agents
  5. Type safety and validation
  6. Structured output
  7. Tools and function calling
  8. Dependency injection
  9. Upgrading from V1
  10. Agent reference
  11. API map

PydanticAI is the Pydantic team’s agent framework. It aims for the feel of FastAPI: plain Python functions, type hints that drive validation and schemas, and dependency injection instead of globals.

  • Typed throughout. Agent[DepsT, OutputT] is generic; tools, instructions and validators receive a typed RunContext[DepsT], and outputs are validated by Pydantic.
  • Model-agnostic. One interface over OpenAI, Anthropic, Google, Bedrock, Groq, Mistral, xAI, OpenRouter and many OpenAI-compatible providers, selected by a provider:model string.
  • Agents are reusable. Create an agent once and run it many times; per-run data goes in deps, conversation state in message_history.
  • Composable. Tools, toolsets and capabilities (hooks, instrumentation, native tools, durability) attach to an agent without subclassing it.
  • Testable and observable. TestModel and FunctionModel replace the LLM in tests; OpenTelemetry instrumentation and Logfire integration are built in.
ProblemWhat PydanticAI provides
Unpredictable LLM outputoutput_type= with Pydantic validation and automatic retries
Model lock-inOne Agent API across providers; FallbackModel across several
Tool plumbing@agent.tool with schemas from type hints and docstrings
Passing state to toolsdeps_type= and RunContext
Production visibilityOpenTelemetry spans and metrics, Logfire
Testing without API callsTestModel, FunctionModel, agent.override()
Terminal window
pip install pydantic-ai # or: uv add pydantic-ai
pip install "pydantic-ai==2.68.0" # pinned

Since 2.0 the standard package installs pydantic-ai-slim[openai,anthropic,google,cli,mcp,evals,web,logfire]: the OpenAI, Anthropic and Google providers plus the CLI, MCP, evals, web UI and Logfire integrations. Everything else is an extra, for example pip install "pydantic-ai[bedrock,groq,mistral,xai,temporal,ag-ui,retries]". There is no [all] extra.

For a smaller install, use pydantic-ai-slim with only the extras you need:

Terminal window
pip install "pydantic-ai-slim[anthropic]"
pip install "pydantic-ai-slim[openai,logfire]"
pip install "pydantic-ai-slim[openai,temporal]" # or dbos, prefect

Providers read their key from the environment: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY and so on. A .env file is convenient in development:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
LOGFIRE_TOKEN=... # optional, for observability

PydanticAI does not load .env files itself; use python-dotenv (pip install python-dotenv) or your process manager:

import os
from dotenv import load_dotenv
load_dotenv()
assert os.getenv('OPENAI_API_KEY'), 'OPENAI_API_KEY not set'
from pydantic_ai import Agent
agent = Agent('openai:gpt-6.1-sol')
result = agent.run_sync('What is 2 + 2?')
print(result.output)
#> 2 + 2 equals 4.
print(result.usage) # a property since 2.0; it was a method in V1
#> RunUsage(input_tokens=14, output_tokens=5, requests=1)

Agent('test') runs the same code against the built-in test model without an API key.

The primary class. Create it once and reuse it.

from dataclasses import dataclass
from pydantic_ai import Agent
agent = Agent('openai:gpt-6.1-sol')
agent_with_instructions = Agent(
'openai:gpt-6.1-sol',
instructions='Be concise and professional. Reply with one or two sentences.',
)
@dataclass
class UserContext:
user_id: int
username: str
agent_complete = Agent(
'openai:gpt-6.1-sol',
deps_type=UserContext,
output_type=str | None,
instructions='Provide clear, working code examples.',
retries=2, # retry budget for tools and output validation
name='PythonHelper',
)

instructions= is the recommended way to give the model its brief. Each request carries the instructions of the agent making it: they are recorded on ModelRequest.instructions for inspection, but they are not replayed from message_history, so a later run with a different agent sends its own instructions rather than inheriting the old ones. system_prompt= text, by contrast, is stored as a SystemPromptPart in the history and travels with it.

Tools, instruction functions and validators can take a RunContext[DepsT] as their first argument. It carries the run’s dependencies, the model, usage so far, the message history and retry state.

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext
@dataclass
class AppDependencies:
database_url: str
api_key: str
agent = Agent('openai:gpt-6.1-sol', deps_type=AppDependencies)
@agent.tool
async def fetch_user_data(ctx: RunContext[AppDependencies], user_id: int) -> str:
"""Fetch a user's record.
Args:
user_id: The user identifier.
"""
db_url = ctx.deps.database_url # typed dependencies
model_name = ctx.model.model_name # the model handling this run
history = ctx.messages # messages so far in this run
attempt = ctx.retry # 0 on the first attempt
return f'User {user_id} from {db_url} ({len(history)} messages, attempt {attempt}, {model_name})'

The most used fields are deps, model, usage, messages, retry, max_retries, tool_name, tool_call_approved, run_id and metadata.

Raise ModelRetry from a tool or output validator to send an error message back to the model and let it try again.

import re
from pydantic import BaseModel, Field
from pydantic_ai import Agent, ModelRetry, RunContext
class EmailAddress(BaseModel):
email: str = Field(description='Valid email address')
name: str = Field(description='Person name')
agent = Agent('openai:gpt-6.1-sol', output_type=EmailAddress)
@agent.output_validator
async def validate_email(ctx: RunContext, output: EmailAddress) -> EmailAddress:
if not re.match(r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$', output.email):
raise ModelRetry(f'Invalid email format: {output.email}. Provide a valid address.')
if len(output.name) < 2:
raise ModelRetry(f'Name too short: {output.name}. Provide a full name.')
return output
result = agent.run_sync('Extract the contact from: Contact John Doe at john@example.com')
print(result.output)
#> email='john@example.com' name='John Doe'

When the retry budget is spent the run raises UnexpectedModelBehavior. For a failure that retrying cannot fix, raise ToolFailed instead: the model is told the call failed and no retry is spent.

Functions decorated with @agent.tool (which receive RunContext) or @agent.tool_plain (which do not) become tools. The JSON schema comes from the type hints; parameter descriptions come from the docstring.

import asyncio
from datetime import datetime
from typing import Literal
from pydantic_ai import Agent, RunContext
agent = Agent('openai:gpt-6.1-sol')
@agent.tool
async def search_database(ctx: RunContext, query: str, limit: int = 10) -> str:
"""Search the document database.
Args:
query: Search query.
limit: Maximum results.
"""
await asyncio.sleep(0.1) # simulate I/O
return f'Found {limit} results for {query!r}'
@agent.tool_plain
def get_current_time() -> str:
"""Get the current server time in ISO format."""
return datetime.now().isoformat()
@agent.tool(strict=True) # ask OpenAI for strict schema adherence
async def calculate(
ctx: RunContext, a: int, b: int, operation: Literal['add', 'subtract', 'multiply', 'divide']
) -> int:
"""Apply an arithmetic operation.
Args:
a: First number.
b: Second number.
operation: The operation to apply.
"""
operations = {'add': a + b, 'subtract': a - b, 'multiply': a * b, 'divide': a // b if b else 0}
return operations[operation]
result = agent.run_sync('What time is it?')
print(result.output)

A model is named provider:model. Common prefixes:

PrefixProviderExample
openai:OpenAI Responses API'openai:gpt-6.1-sol'
openai-chat:OpenAI Chat Completions'openai-chat:gpt-6.1-sol'
anthropic:Anthropic'anthropic:claude-sonnet-5-5'
google: / google-cloud:Gemini API / Vertex AI'google:gemini-3.8-flash'
bedrock:Amazon Bedrock (extra)'bedrock:us.anthropic.claude-sonnet-5-5'
groq:, mistral:, xai:, deepseek:, openrouter:, …other providers (most need an extra)'mistral:mistral-medium-latest'
gateway/<provider>:Pydantic AI Gateway'gateway/anthropic:claude-sonnet-5-5'

Since 2.0 a model name without a prefix raises UserError. OpenAI-compatible services (Ollama, vLLM, Perplexity, Together, …) use an OpenAI model class with a provider that sets the base URL. The model providers page lists every prefix, explicit provider construction, local models and FallbackModel.

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider
local = OpenAIChatModel('qwen3', provider=OpenAIProvider(base_url='http://localhost:11434/v1'))
agent = Agent(local)
from pydantic import BaseModel
from pydantic_ai import Agent, ModelSettings, UsageLimits
from pydantic_ai.exceptions import UsageLimitExceeded
agent = Agent('openai:gpt-6.1-sol', instructions='Be concise.', retries=3, name='MyAgent')
settings = ModelSettings(temperature=0.7, max_tokens=500, top_p=0.95)
result = agent.run_sync('What is Python?', model_settings=settings) # also accepted by Agent(...)
class Article(BaseModel):
title: str
content: str
keywords: list[str]
article_agent = Agent('openai:gpt-6.1-sol', output_type=Article)
limits = UsageLimits(
request_limit=5, # model requests per run (default 50)
tool_calls_limit=10, # successful tool executions per run
total_tokens_limit=10_000,
)
result = article_agent.run_sync('Write about type safety in Python', usage_limits=limits)
usage = result.usage
print(usage.requests, usage.tool_calls, usage.input_tokens, usage.output_tokens, usage.total_tokens)
try:
agent.run_sync('Count every prime below 10000.', usage_limits=UsageLimits(request_limit=1, output_tokens_limit=50))
except UsageLimitExceeded as exc:
print(f'Run aborted: {exc}')

Most ModelSettings keys a model does not support (temperature, seed, …) are ignored silently, so one settings dict works across providers. The settings whose absence changes what a request guarantees — timeout, max_retries, stop_sequences, parallel_tool_calls=False, extra_headers and extra_body — emit an UnsupportedSettingWarning instead; turn it into an error with warnings.filterwarnings('error', category=UnsupportedSettingWarning). Cost limits, timeouts and the other production guards are on the production page.

import asyncio
from pydantic_ai import Agent
agent = Agent('openai:gpt-6.1-sol', instructions='Respond with exactly one sentence.')
result = agent.run_sync('What is the capital of France?') # scripts and notebooks
print(result.output)
#> The capital of France is Paris.
async def main() -> str:
result = await agent.run('Explain type safety in Python.') # inside async code
return result.output
print(asyncio.run(main()))

run_sync() cannot be called from inside a running event loop; use await agent.run(...) there. agent.run_stream() streams the output and agent.iter() walks the run node by node (see streaming).

from datetime import datetime, timezone
from pydantic_ai import Agent, RunContext
agent = Agent('openai:gpt-6.1-sol', instructions='You are a helpful assistant.')
@agent.instructions
def current_time(ctx: RunContext) -> str:
"""Re-evaluated for every run."""
return f'The current UTC time is {datetime.now(timezone.utc):%Y-%m-%d %H:%M}.'
result = agent.run_sync('What day is it?')
# Extra instructions for a single run are appended to the agent's own
result = agent.run_sync('Explain closures in Python.', instructions='Explain at a beginner level.')
print(len(result.all_messages()), result.usage.input_tokens)

@agent.system_prompt and system_prompt= still exist. Use them when the prompt must stay in the message history (for example when another agent will continue the conversation); otherwise prefer instructions.

import asyncio
from pydantic import BaseModel
from pydantic_ai import Agent
agent = Agent('openai:gpt-6.1-sol')
class Article(BaseModel):
title: str
content: str
structured_agent = Agent('openai:gpt-6.1-sol', output_type=Article)
async def stream_text() -> None:
async with agent.run_stream('Write a haiku about Python') as response:
async for text in response.stream_text(delta=True):
print(text, end='', flush=True)
print()
async def stream_structured() -> None:
async with structured_agent.run_stream('Write an article about type safety') as response:
async for partial in response.stream_output(): # partially validated Article objects
print(partial.title or '…')
article = await response.get_output()
print(f'Title: {article.title}; {len(article.content)} characters')
asyncio.run(stream_text())
asyncio.run(stream_structured())

stream_text() only works when the output type is text; for structured output use stream_output(). The streaming page covers run_stream_events(), debouncing and cancellation.

Validation and retries on structured output

Section titled “Validation and retries on structured output”
from pydantic import BaseModel, Field
from pydantic_ai import Agent, ModelRetry, RunContext
from pydantic_ai.exceptions import UnexpectedModelBehavior
class CodeReview(BaseModel):
issues: list[str] = Field(min_length=1, description='Code issues found')
severity: str = Field(pattern='^(low|medium|high)$')
suggestions: list[str]
agent = Agent('openai:gpt-6.1-sol', output_type=CodeReview, retries=2)
@agent.output_validator
async def one_suggestion_per_issue(ctx: RunContext, output: CodeReview) -> CodeReview:
if len(output.issues) > 10:
raise ModelRetry('Limit the review to at most 10 issues.')
if len(output.suggestions) != len(output.issues):
raise ModelRetry(
f'Give one suggestion per issue: {len(output.issues)} issues, {len(output.suggestions)} suggestions.'
)
return output
try:
result = agent.run_sync('Review this Python code: x = 1; y = 2; z = x+y')
print(result.output.severity, len(result.output.issues))
except UnexpectedModelBehavior as exc: # retries exhausted
print(f'Validation kept failing: {exc}')

Pydantic field constraints (min_length, pattern, …) are enforced first; a failure there is sent back to the model as a retry in the same way as ModelRetry.

Anything Pydantic can validate can be an output type: models, dataclasses, TypedDicts, scalars, lists and unions.

from datetime import datetime
from pydantic import BaseModel, ConfigDict, Field, field_validator
from pydantic_ai import Agent
class UserProfile(BaseModel):
model_config = ConfigDict(json_schema_extra={'example': {'id': 1, 'name': 'John', 'email': 'john@example.com'}})
id: int = Field(gt=0, description='Unique user identifier')
name: str = Field(min_length=1, max_length=100)
email: str
age: int | None = Field(default=None, ge=0, le=150)
premium: bool = False
class ValidatedArticle(BaseModel):
title: str = Field(min_length=5, max_length=200)
content: str = Field(min_length=100)
tags: list[str] = Field(default_factory=list, max_length=10)
published_date: datetime | None = None
@field_validator('tags')
@classmethod
def normalise_tags(cls, v: list[str]) -> list[str]:
return sorted({tag.lower() for tag in v})
article_agent = Agent('openai:gpt-6.1-sol', output_type=ValidatedArticle)
result = article_agent.run_sync('Write an article about Python type hints')
print(result.output.title, result.output.tags)

Field descriptions and constraints go into the JSON schema the model sees, so they steer the model as well as validating its answer.

from dataclasses import dataclass
import httpx
from pydantic_ai import Agent, RunContext
@dataclass
class ServiceDependencies:
http_client: httpx.AsyncClient
api_base: str
api_key: str
user_id: int
agent = Agent('openai:gpt-6.1-sol', deps_type=ServiceDependencies)
@agent.tool
async def fetch_profile(ctx: RunContext[ServiceDependencies], include_preferences: bool = False) -> dict:
"""Fetch the current user's profile.
Args:
include_preferences: Whether to include preference data.
"""
headers = {'X-API-Key': ctx.deps.api_key}
base = f'{ctx.deps.api_base}/users/{ctx.deps.user_id}'
data = (await ctx.deps.http_client.get(base, headers=headers)).json()
if include_preferences:
data['preferences'] = (await ctx.deps.http_client.get(f'{base}/preferences', headers=headers)).json()
return data
@agent.instructions
def personalise(ctx: RunContext[ServiceDependencies]) -> str:
return f'You are helping user {ctx.deps.user_id}.'
async def main() -> None:
async with httpx.AsyncClient() as client:
deps = ServiceDependencies(client, 'https://api.example.com', 'secret-key', 123)
result = await agent.run('Tell me about my profile', deps=deps)
print(result.output)

A type checker now knows the shape of ctx.deps in every tool, and agent.run(deps=...) is checked against deps_type.

from pydantic import BaseModel, Field
from pydantic_ai import Agent
class Address(BaseModel):
street: str
city: str
country: str
postal_code: str
class Contact(BaseModel):
email: str = Field(pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$')
phone: str | None = None
class Company(BaseModel):
name: str
founded: int = Field(ge=1800, le=2100)
employees: int = Field(gt=0)
address: Address
contacts: list[Contact]
website: str | None = None
agent = Agent('openai:gpt-6.1-sol', output_type=Company)
result = agent.run_sync('Extract company information for Pydantic: founded 2017, about 50 employees, based in London.')
company = result.output
print(company.name, company.address.city, company.contacts[0].email if company.contacts else None)

Pass several output types as a list (each becomes its own output tool), or use a discriminated union inside a model:

from typing import Annotated, Literal
from pydantic import BaseModel, Field
from pydantic_ai import Agent
class TextResult(BaseModel):
kind: Literal['text']
content: str
class JsonResult(BaseModel):
kind: Literal['json']
data: dict
class ProcessingResult(BaseModel):
status: str
output: Annotated[TextResult | JsonResult, Field(discriminator='kind')]
agent = Agent('openai:gpt-6.1-sol', output_type=ProcessingResult)
result = agent.run_sync('Output JSON data about Python')
match result.output.output:
case JsonResult(data=data):
print('JSON keys:', list(data))
case TextResult(content=content):
print('Text:', content)
class Refusal(BaseModel):
reason: str
either_agent = Agent('openai:gpt-6.1-sol', output_type=[ProcessingResult, Refusal])

output_type=[A, B] gives the model a separate output tool per type, which models handle more reliably than one large union schema.

By default structured output uses a tool call. NativeOutput uses the provider’s JSON-schema response format, PromptedOutput puts the schema in the prompt, TextOutput passes plain text to your parser and StructuredDict validates against a JSON schema without a Pydantic model. The output types page compares them.

import random
import re
from typing import Any, Literal
from pydantic import Field
from pydantic_ai import Agent, RunContext
agent = Agent('openai:gpt-6.1-sol')
@agent.tool
async def calculate_factorial(ctx: RunContext, n: int) -> int:
"""Calculate n!."""
if n < 0:
raise ValueError('Factorial not defined for negative numbers')
result = 1
for i in range(2, n + 1):
result *= i
return result
@agent.tool
async def search_and_rank(
ctx: RunContext,
query: str,
filters: dict[str, Any],
sort_by: Literal['relevance', 'date', 'popularity'] = 'relevance',
limit: int = Field(10, ge=1, le=100),
) -> dict[str, Any]:
"""Search documents and rank the results.
Args:
query: Search query string.
filters: Filter conditions.
sort_by: Field to sort by.
limit: Maximum results to return.
"""
results = [{'id': i, 'score': 1 - i * 0.1, 'title': f'Result {i}'} for i in range(min(limit, 5))]
return {'results': results, 'total': 1000, 'query': query, 'sort_by': sort_by}
@agent.tool_plain
def get_random_number(min_value: int = 0, max_value: int = 100) -> int:
"""Generate a random integer between min_value and max_value."""
return random.randint(min_value, max_value)
@agent.tool_plain
def validate_email(email: str) -> dict[str, bool | str]:
"""Check whether an email address is well formed."""
return {'valid': bool(re.match(r'^[\w\.-]+@[\w\.-]+\.\w+$', email)), 'email': email}
result = agent.run_sync('Pick a random number and check the email bob@example.com.')

Literal, enums, Field(...) constraints and Pydantic models all appear in the schema. Arguments that fail validation are sent back to the model as a retry. The return value can be anything Pydantic can serialise.

Async tools run on the event loop; sync tools run in a worker thread so they do not block it. When the model requests several tools in one response, they run concurrently.

import asyncio
import httpx
from pydantic_ai import Agent, RunContext
agent = Agent('openai:gpt-6.1-sol')
@agent.tool
async def fetch_webpage(ctx: RunContext, url: str) -> str:
"""Fetch the first 1000 characters of a page."""
async with httpx.AsyncClient() as client:
response = await client.get(url, timeout=10)
return response.text[:1000]
@agent.tool
async def parallel_searches(ctx: RunContext, queries: list[str]) -> list[str]:
"""Run several searches concurrently."""
async def search_one(q: str) -> str:
await asyncio.sleep(0.1)
return f'Results for {q!r}'
return await asyncio.gather(*(search_one(q) for q in queries))

For a model-chosen URL, prefer web_fetch_tool() from pydantic_ai.common_tools, which blocks private and cloud-metadata addresses (built-in tools).

A prepare function receives the tool’s ToolDefinition before each model request and returns it (possibly modified) or None to hide the tool for that step.

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext
from pydantic_ai.tools import ToolDefinition
@dataclass
class Deps:
user_role: str
agent = Agent('openai:gpt-6.1-sol', deps_type=Deps)
async def only_if_admin(ctx: RunContext[Deps], tool_def: ToolDefinition) -> ToolDefinition | None:
return tool_def if ctx.deps.user_role == 'admin' else None
@agent.tool(prepare=only_if_admin)
async def delete_record(ctx: RunContext[Deps], record_id: int) -> bool:
"""Delete a record (admins only)."""
return True
result = agent.run_sync('Delete record 7', deps=Deps(user_role='viewer')) # the tool is not offered

To filter or rewrite many tools at once, use the toolset wrappers (FilteredToolset, PreparedToolset) or the PrepareTools capability; see toolsets.

import httpx
from pydantic_ai import Agent, ModelRetry, RunContext, ToolFailed
agent = Agent('openai:gpt-6.1-sol')
@agent.tool
async def fetch_resource(ctx: RunContext, resource_id: int) -> dict:
"""Fetch a resource by ID."""
if resource_id <= 0:
raise ModelRetry(f'Invalid resource_id {resource_id}: it must be positive.')
try:
async with httpx.AsyncClient() as client:
response = await client.get(f'https://api.example.com/resources/{resource_id}', timeout=5)
except httpx.TimeoutException:
raise ModelRetry('The request timed out; try again.')
if response.status_code == 404:
raise ToolFailed(f'Resource {resource_id} does not exist.') # not worth retrying
response.raise_for_status()
return response.json()
  • ModelRetry sends the message back and spends one retry.
  • ToolFailed tells the model the call failed, without asking it to retry.
  • Any other exception propagates and ends the run.

The error handling page lists every exception and how to test each path.

Provider-native tools (web search, code execution, image generation, web fetch, file search, …) run on the provider’s side. Since 2.0 they are attached as capabilities: capabilities=[WebSearch()] (with an optional local fallback) or capabilities=[NativeTool(WebSearchTool())] (the raw tool). Support varies by provider; the built-in tools page has the support table.

from pydantic_ai import Agent
from pydantic_ai.capabilities import WebSearch
agent = Agent('anthropic:claude-sonnet-5-5', capabilities=[WebSearch(max_uses=3)])
result = agent.run_sync('What is the latest Python release? Cite the source.')

deps is the only state an agent run sees that you did not put in the prompt. Use it for database pools, HTTP clients, configuration and per-request identity. Dependencies are passed per run, so one agent can serve many tenants.

import asyncio
from dataclasses import dataclass, field
from typing import Any
from pydantic_ai import Agent, RunContext
@dataclass
class ApplicationState:
user_id: int
session_id: str
cache: dict[str, Any] = field(default_factory=dict)
agent = Agent('openai:gpt-6.1-sol', deps_type=ApplicationState)
@agent.tool
async def store_value(ctx: RunContext[ApplicationState], key: str, value: str) -> str:
"""Remember a value for this session."""
ctx.deps.cache[key] = value
return f'Stored {key!r}'
@agent.tool
async def retrieve_value(ctx: RunContext[ApplicationState], key: str) -> str | None:
"""Recall a value stored earlier in this session."""
return ctx.deps.cache.get(key)
@agent.instructions
def session_context(ctx: RunContext[ApplicationState]) -> str:
return f'You are assisting user {ctx.deps.user_id} in session {ctx.deps.session_id}.'
async def main() -> None:
state = ApplicationState(user_id=123, session_id='sess_abc123')
first = await agent.run('Store my favourite language as Python', deps=state)
# The same deps object is passed again, so the cache persists; pass the history too
second = await agent.run('What is my favourite language?', deps=state, message_history=first.all_messages())
print(second.output)
asyncio.run(main())

In tests, pass fake dependencies the same way, or replace them for a block of code with agent.override(deps=...).

PydanticAI 2.0.0 (June 2026) collected the breaking changes V1’s stability promise held back. Most were announced by PydanticAIDeprecationWarnings from 1.95.0 onwards, so the smooth path is: upgrade to the last 1.x, clear every PydanticAIDeprecationWarning, then move to 2.x. The changes most likely to affect code written from older guides:

V1V2
openai: prefix = Chat Completionsopenai: = Responses API; use openai-chat: for Chat Completions
google-gla:, google-vertex:, grok: prefixes; GeminiModel, OpenAIModelgoogle:, google-cloud:, xai:; GoogleModel, OpenAIChatModel
Agent('gpt-5') without a prefixraises UserError
Agent(builtin_tools=[...]), pydantic_ai.builtin_tools, UrlContextToolcapabilities=[NativeTool(...)], pydantic_ai.native_tools, WebFetchTool
Agent(instrument=..., event_stream_handler=..., history_processors=..., prepare_tools=...)capabilities=[Instrumentation(...)], ProcessEventStream(...), ProcessHistory(...), PrepareTools(...)
Agent(mcp_servers=[...]), MCPServerStdio / MCPServerSSE / MCPServerStreamableHTTPtoolsets=[MCPToolset(...)]
result.usage(), result.timestamp(), stream.get()result.usage, result.timestamp, stream.response (properties)
async for e in agent.run_stream_events(...)async with agent.run_stream_events(...) as events:
stream_responses(), FunctionToolResultEvent.resultstream_response(), FunctionToolResultEvent.part
DeferredToolCalls, DeferredToolsetDeferredToolRequests, ExternalToolset
usage.request_tokens / response_tokensusage.input_tokens / output_tokens
Agent.to_a2a(), Agent.to_ag_ui()fasta2a.pydantic_ai.agent_to_a2a, pydantic_ai.ui.ag_ui.AGUIAdapter
pydantic_graph.beta, pydantic_graph.persistencetop-level pydantic_graph; persistence removed
Dataset(...) without a nameDataset(name=...) required
Default end_strategy='early'Default 'graceful': function tools requested before an output tool still run
ModelProfile dataclassesTypedDicts; use merge_profile()
Bare pip install pydantic-ai included Bedrock, Groq, Mistral, …Only OpenAI, Anthropic and Google providers by default; add extras
TemporalAgent, DBOSAgent, PrefectAgent wrappersdeprecated since 2.14 in favour of the TemporalDurability / DBOSDurability / PrefectDurability capabilities (durable execution)

The full list, with the PR for each change, is in the official upgrade guide. Message history serialised with V1 still loads in V2.

Agent(
model: Model | KnownModelName | str | None = None,
*,
output_type: OutputSpec = str,
instructions: AgentInstructions = None,
system_prompt: str | Sequence[str] = (),
deps_type: type = object,
name: str | None = None,
description: TemplateStr | str | None = None,
model_settings: AgentModelSettings | None = None,
retries: int | AgentRetries | None = None, # default 1 for tools and output
validation_context: Any | Callable[[RunContext], Any] = None,
tools: Sequence[Tool | ToolFunc] = (),
toolsets: Sequence[AgentToolset] | None = None,
defer_model_check: bool = False,
end_strategy: EndStrategy = 'graceful',
metadata: AgentMetadata | None = None,
tool_timeout: float | None = None,
max_concurrency: int | ConcurrencyLimit | AbstractConcurrencyLimiter | None = None,
capabilities: Sequence[AgentCapability] | None = None,
)
  • instructions accepts a string, a TemplateStr, a function of RunContext (sync or async), or a list mixing these; @agent.instructions registers more.
  • model_settings, toolsets and capabilities each also accept a function of RunContext, resolved per run, for per-tenant settings or feature flags.
  • retries is an int (both budgets) or an AgentRetries dict: retries={'tools': 3, 'output': 1}.
  • defer_model_check=True postpones resolving the model string (and the API-key check) until the first run, useful when tests override the model.
  • metadata is attached to the run and its spans but never sent to the model.
  • tool_timeout and max_concurrency are covered on the production page.

end_strategy decides what happens to function tools the model requests in the same response as its final output. It is set on the agent only; run() does not take it.

ValueBehaviour
'graceful' (default since 2.0)Tools run in the order the model emitted them, so function tools before the output tool complete. The first successful output tool wins; later output tools are skipped. A ModelRetry from a function tool suppresses the output and surfaces the retry.
'early'The run ends at the first successful output tool; function tools in that response are not executed (the V1 default).
'exhaustive'Every requested tool runs (in parallel by default); the first valid output by emission order becomes the result.
from pydantic_ai import Agent
agent = Agent('openai:gpt-6.1-sol', end_strategy='early', retries={'tools': 3, 'output': 1})
MethodUse
await agent.run(prompt, ...)Run to completion; returns AgentRunResult
agent.run_sync(prompt, ...)The same, from synchronous code
async with agent.run_stream(prompt) as stream:Stream text or partial output (streaming)
agent.run_stream_sync(prompt)Synchronous streaming
async with agent.run_stream_events(prompt) as events:Every event, ending with AgentRunResultEvent
async with agent.iter(prompt) as run:Step through the graph node by node
agent.override(model=..., deps=..., toolsets=...)Replace parts of the agent in a with block (tests)
agent.to_web(), agent.to_cli()Chat web app, terminal chat (integrations)
Agent.from_spec(...), Agent.from_file(path)Build an agent from a YAML/JSON AgentSpec

The run methods share these keyword arguments: message_history or conversation (a whole Conversation, see below), deps, instructions (appended for this run), model, model_settings, output_type, usage_limits, usage, timeout, cancellation_token, metadata, retries, toolsets, capabilities, deferred_tool_results, conversation_id and run_id; run, run_sync, run_stream and run_stream_sync also take a per-run event_stream_handler.

AgentRunResult exposes output, usage (a property), response (the final ModelResponse), run_id, conversation_id, metadata, conversation (messages, usage, conversation ID and pending deferred calls in one object, ready to pass back as conversation=), and all_messages() / new_messages() with _json() variants for storage (message history).

import asyncio
from pydantic_ai import Agent, CallToolsNode, ModelRequestNode
agent = Agent('openai:gpt-6.1-sol')
@agent.tool_plain
def lookup(city: str) -> str:
"""Look up a city's population."""
return f'{city}: 9 million'
async def main() -> None:
async with agent.iter('How many people live in London?') as run:
async for node in run:
if isinstance(node, ModelRequestNode):
print('request with', [type(p).__name__ for p in node.request.parts])
elif isinstance(node, CallToolsNode):
print('response:', node.model_response.finish_reason)
print(run.result.output)
asyncio.run(main())

async for yields each node before it runs and advances through run.next(), so capability hooks fire exactly as they do for agent.run(). Call node = await run.next(node) yourself when you want to inspect or replace a node before it executes, or stop early by breaking out of the loop.

An AgentSpec describes an agent’s model, instructions, settings, retries and capabilities as data, so it can live in YAML or JSON. Capabilities use short forms: a bare name ('Thinking') or {Name: {kwargs}}.

from pydantic_ai import Agent, AgentSpec
spec = AgentSpec.from_dict({
'model': 'anthropic:claude-sonnet-5-5',
'name': 'support-agent',
'instructions': 'You are a helpful support agent.',
'model_settings': {'temperature': 0.3},
'retries': 3,
'capabilities': ['Thinking'],
})
agent = Agent.from_spec(spec) # or Agent.from_file('agent.yaml')

AgentSpec.from_file(), .from_text() and .to_file() read and write YAML or JSON. There is no spec.to_agent(); build through Agent.from_spec() or Agent.from_file().

The public API grouped by area, with the page that covers each part. Everything listed is importable from the module shown; most names are also exported from pydantic_ai itself. The upstream documentation and the docstrings in the installed package document every class and argument.

NamesModuleCovered in
Agent, AgentRunResult, AgentRun, RunContextpydantic_aithis page
UserPromptNode, ModelRequestNode, CallToolsNode, AgentRunResultEventpydantic_aiStreaming
AgentSpec, TemplateStrpydantic_aiAgents from a spec
WrapperAgent, AbstractAgentpydantic_ai.agentAdvanced patterns
UsageLimits, RunUsage, RequestUsagepydantic_ai / pydantic_ai.usageProduction
CancellationToken, RunCancelled, RunTimedOutpydantic_ai, pydantic_ai.exceptionsError handling
capture_run_messagespydantic_aiMessage history
model_request, model_request_sync, model_request_stream, model_request_stream_syncpydantic_ai.directDirect API
model_request_batch, BatchModelRequests, PendingModelResponsepydantic_ai.direct, pydantic_ai.capabilities, pydantic_aiBatch processing
NamesModuleCovered in
OpenAIResponsesModel, OpenAIChatModel, AnthropicModel, GoogleModel, BedrockConverseModel, GroqModel, MistralModel, XaiModel, OpenRouterModel, …pydantic_ai.models.<provider>Model providers
OpenAIProvider, AnthropicProvider, GoogleProvider, GoogleCloudProvider, BedrockProvider, …pydantic_ai.providers.<provider>Model providers
ModelSettings and the per-provider *ModelSettingspydantic_ai.settings, pydantic_ai.models.<provider>Model providers
FallbackModel, FallbackExceptionGrouppydantic_ai.models.fallback, pydantic_ai.exceptionsModel providers, Production
WrapperModel, InstrumentedModel, InstrumentationSettingspydantic_ai.models.wrapper, pydantic_ai.models.instrumented, pydantic_aiModel providers
ModelProfile, merge_profilepydantic_ai.profilesModel providers
TestModel, FunctionModel, AgentInfopydantic_ai.models.test, pydantic_ai.models.functionTesting
ConcurrencyLimiter, ConcurrencyLimit, limit_model_concurrencypydantic_aiConcurrency
AsyncHTTPX2TenacityTransport, RetryConfig, wait_retry_afterpydantic_ai.retries (retries extra)Production
Embedder, EmbeddingModelpydantic_ai, pydantic_ai.embeddingsEmbeddings
NamesModuleCovered in
Tool, ToolDefinition, ToolReturnpydantic_ai, pydantic_ai.toolsTools, ToolReturn
ModelRetry, ToolFailedpydantic_aiError handling
FunctionToolset, CombinedToolset, PrefixedToolset, RenamedToolset, FilteredToolset, PreparedToolset, SetMetadataToolset, IncludeReturnSchemasToolset, DynamicToolset, WrapperToolset, AbstractToolsetpydantic_ai.toolsetsToolsets
ApprovalRequiredToolset, ExternalToolset, DeferredLoadingToolsetpydantic_ai.toolsetsToolsets
ApprovalRequired, CallDeferred, DeferredToolRequests, DeferredToolResults, ToolApproved, ToolDeniedpydantic_aiToolsets
MCPToolset, load_mcp_toolsetspydantic_ai.mcpIntegrations
WebSearchTool, WebFetchTool, CodeExecutionTool, ImageGenerationTool, FileSearchTool, MemoryTool, MCPServerTool, XSearchTool, AdvisorToolpydantic_ai / pydantic_ai.native_toolsBuilt-in tools
web_fetch_tool, duckduckgo_search_tool, tavily_search_tool, ExaToolsetpydantic_ai.common_tools.*Built-in tools
LangChainToolset, tool_from_langchainpydantic_ai.ext.langchainupstream tools docs

Capabilities bundle behaviour (hooks, instructions, tools, settings) and attach with Agent(capabilities=[...]) or per run.

NamesModuleCovered in
Hooks, AbstractCapability, WrapperCapability, CombinedCapability, Capabilitypydantic_ai.capabilitiesHooks, Bundling tools
Instrumentationpydantic_ai.capabilitiesProduction
ProcessHistory, ReinjectSystemPromptpydantic_ai.capabilitiesMessage history
ProcessEventStreampydantic_ai.capabilitiesStreaming
PrepareTools, PrepareOutputTools, SetToolMetadata, PrefixTools, Toolset, ToolSearch, IncludeToolReturnSchemaspydantic_ai.capabilitiesToolsets
HandleDeferredToolCallspydantic_ai.capabilitiesRecipes
WebSearch, WebFetch, ImageGeneration, XSearch, MCP, NativeTool, NativeOrLocalTool, Thinkingpydantic_ai.capabilitiesBuilt-in tools
SelectModel, ResolveModelIdpydantic_ai.capabilitiesChoosing the model per step
RaiseContentFilterError, UseThreadExecutor, Caching, LocalWorkspace, Citations, FileUnderstandingpydantic_ai.capabilitiesupstream capabilities docs
TemporalDurability, DBOSDurability, PrefectDurabilitypydantic_ai.durable_exec.<engine>Durable execution
OnlineEvaluationpydantic_evals.online_capabilityEvals
NamesModuleCovered in
ToolOutput, NativeOutput, PromptedOutput, TextOutput, StructuredDictpydantic_ai / pydantic_ai.outputOutput types
ModelMessage, ModelRequest, ModelResponse and their parts, ModelMessagesTypeAdapterpydantic_ai.messagesMessage history
BinaryContent, ImageUrl, AudioUrl, VideoUrl, DocumentUrl, UploadedFile, CachePointpydantic_aiMessage history, Recipes
PartStartEvent, PartDeltaEvent, PartEndEvent, FinalResultEvent, FunctionToolCallEvent, FunctionToolResultEventpydantic_ai.messagesStreaming
format_as_xmlpydantic_aiRecipes
NamesModuleCovered in
GraphBuilder, BaseNode, End, GraphRunContextpydantic_graphGraph support
Dataset, Case, Evaluator, LLMJudge and the built-in evaluatorspydantic_evals, pydantic_evals.evaluatorsEvals
AGUIAdapter, VercelAIAdapterpydantic_ai.ui.ag_ui, pydantic_ai.ui.vercel_aiIntegrations, Streaming server
agent_to_a2afasta2a.pydantic_ai (separate package)Integrations
AgentRunError (RuntimeError)
├── UsageLimitExceeded
├── ConcurrencyLimitExceeded
├── RunCancelled
│ └── RunTimedOut (also a TimeoutError)
├── HookTimeoutError (also a TimeoutError)
├── UnexpectedModelBehavior
│ ├── ContentFilterError
│ └── IncompleteToolCall
└── ModelAPIError
├── ModelHTTPError (status_code, model_name, body, headers, retry_after)
├── ModelConnectionError
│ └── ModelTimeoutError
├── ModelRequestTimeout
└── ModelRateLimitError, ModelQuotaExceededError, ModelServerError,
ModelRequestRejectedError (→ ModelAuthenticationError, ModelNotFoundError,
ModelContextWindowExceededError), ModelUnavailableError (└── ModelOverloadedError)
— when one comes from an HTTP response it is also a ModelHTTPError
UserError (RuntimeError) — a programming mistake, raised before or during a run
FallbackExceptionGroup — every model in a FallbackModel failed
ModelRetry, ToolFailed — raised by your code to steer the model
ApprovalRequired, CallDeferred — raised by your code to defer a tool call

The error handling page shows when each is raised and how to test for it. Deprecations use PydanticAIDeprecationWarning, a UserWarning subclass, so they show by default; turn it into an error in CI with -W error::pydantic_ai.PydanticAIDeprecationWarning or a filterwarnings entry.

ToolReturn separates what the model gets as the tool result from extra content (images, documents, long text) sent alongside it, and from metadata your application keeps:

from pydantic_ai import Agent, BinaryContent, ToolReturn
agent = Agent('anthropic:claude-sonnet-5-5')
@agent.tool_plain
def screenshot(url: str) -> ToolReturn:
"""Take a screenshot of a web page."""
png = b'\x89PNG...' # real code: capture the page
return ToolReturn(
return_value=f'Captured {url}',
content=['Here is the screenshot:', BinaryContent(png, media_type='image/png')],
metadata={'bytes': len(png)}, # stays on the ToolReturnPart, never sent to the model
)

SelectModel picks the model before each model request, from the step number, the messages so far or the usage. It returns a Model or a model string:

from pydantic_ai import Agent, ModelSelectionContext
from pydantic_ai.capabilities import SelectModel
def escalate(ctx: ModelSelectionContext[None]) -> str:
# a cheap model for the first request, a stronger one once tools are in play
return 'anthropic:claude-haiku-5-5' if ctx.run_step == 1 else 'anthropic:claude-opus-5-5'
agent = Agent(capabilities=[SelectModel(escalate)])

TemplateStr renders a Handlebars template against deps for each run, which keeps per-user text out of code and works inside an AgentSpec:

from dataclasses import dataclass
from pydantic_ai import Agent, TemplateStr
@dataclass
class UserProfile:
name: str
language: str
agent = Agent(
'openai:gpt-6-luna',
deps_type=UserProfile,
instructions=TemplateStr('The user is {{name}}. Always respond in {{language}}.'),
)
result = agent.run_sync('What is a decorator?', deps=UserProfile(name='Alice', language='French'))

Capability groups instructions and tools under one id without subclassing. With defer_loading=True the model sees only its description until it asks to load it, which keeps large tool collections out of the context window:

from pydantic_ai import Agent, RunContext
from pydantic_ai.capabilities import Capability
finance = Capability(
id='finance-tools',
description='Stock prices and portfolio returns.',
instructions='Quote prices in USD with two decimal places.',
defer_loading=True,
)
@finance.tool
def get_stock_price(ctx: RunContext[object], ticker: str) -> float:
"""Return the latest closing price."""
return 150.0
agent = Agent('openai:gpt-6.1-sol', capabilities=[finance])

The framework’s own history is in the upstream changelog; this guide’s history is in git.

DateChange
2026-10-25Version bump to pydantic-ai 2.68.0: added Citations and FileUnderstanding to the API map.
2026-10-25Re-audited against pydantic-ai 2.68.0: corrected the instructions-versus-history note, UnsupportedSettingWarning scope, the start of V2 deprecation warnings (1.95.0), agent.iter() hook behaviour and the OnlineEvaluation module; added Conversation to the run reference and fuller exception tree.
2026-10-21Rewritten. The 4,700-line class reference (much of it private internals and repeats of topic pages) replaced by an Agent reference and an API map that links to the topic pages. Corrected the end_strategy default ('graceful'), the AgentRetries keys, the removed MCPServer* classes and the native-tool support table; fixed the tutorial examples (instructions= per run, stream_output() for structured streaming, min_length=, imports).
2026-08-21Class & API Reference section added, consolidating the earlier per-class pages.
2025-11First edition (1.x).