PydanticAI

The Pydantic way for Generative AI. Type-safe agents with validated inputs/outputs, FastAPI-inspired dependency injection, and — new in 2025 — durable execution, graph-based workflows, and a first-class evals framework.

Install

pip install pydantic-ai

Version

v1.90.0 · May 2026 · Python 3.10+

Best for

Typed APIs, structured output, validated data pipelines, evals-driven agents.

Zero → Hero

1 · Philosophy & core concepts Why type safety, design principles · 10 min

2 · Installation & setup Install, first agent, LLM config · 15 min

3 · Core fundamentals Agent, Model, RunContext, tools · 20 min

4 · Your first agent Query/response, streaming, async · 20 min

5 · Type safety & validation Pydantic models for everything · 15 min

6 · Output types & validators ToolOutput/NativeOutput/PromptedOutput/TextOutput/StructuredDict · 15 min

7 · Tools & function calling @agent.tool decorator, validation · 20 min

8 · Toolsets FunctionToolset, Prefixed, Filtered, Approval, Deferred · 15 min

9 · Built-in tools WebSearch, WebFetch, CodeExec, Image, FileSearch · 10 min

10 · Dependency injection FastAPI-style deps, testing, mocking · 15 min

11 · Model providers & fallback Every provider prefix, FallbackModel, gateway · 20 min

12 · Message history & multi-turn ModelMessagesTypeAdapter, HistoryProcessor · 15 min

13 · Streaming run_stream, AgentStream, iter, events · 20 min

14 · Testing TestModel, FunctionModel, override, capture · 20 min

15 · Graph support Typed state graphs · 25 min

16 · Durable execution Checkpointing, resume, Temporal-style · 25 min

17 · Evals LLM-as-judge, regression testing · 20 min

18 · Production Deployment, observability, cost · 30 min

Jump to a topic

Agent primitive

Output types

Tools (typed)

Toolsets

Built-in tools

Dependency injection

Model providers & fallback

Message history

Streaming

Testing

Graph support

Durable execution

Evals

Integrations 2025

Advanced patterns

Error testing

Streaming server

Reference

Comprehensive guide Single-page technical reference.

Output types & validators ToolOutput / NativeOutput / PromptedOutput / TextOutput / StructuredDict.

Message history & multi-turn ModelMessagesTypeAdapter, HistoryProcessor, capture_run_messages.

Streaming run_stream, run_stream_events, iter, AgentStream.

Testing TestModel, FunctionModel, agent.override().

Model providers & fallback Every provider prefix, FallbackModel, gateway routing.

Toolsets FunctionToolset, Prefixed, Filtered, Approval, Deferred, External.

Built-in tools WebSearch, WebFetch, CodeExecution, ImageGeneration, FileSearch, MCPServer, XSearch.

Advanced patterns

Advanced error testing

Durable execution (2025)

Graph support (2025)

Integrations 2025

Evals (2025)

Recipes

Diagrams

Production guide

Streaming server (FastAPI)

What’s new in v1.90.0 (May 2026)

v1.90.0 (May 5) — Patch release; maintenance and dependency updates. DeferredToolCalls class in pydantic_ai.output marked @deprecated — use DeferredToolRequests (already the recommended API since v1.87.x).
v1.89.1 (May 2) — Patch release; maintenance and dependency updates.
v1.89.0 (May 1) — Patch release; maintenance and dependency updates.
v1.88.0 (April 29) — Patch release; maintenance and dependency updates.
v1.87.0 — Expanded Capabilities API — 9 new capability classes added to pydantic_ai.capabilities: WrapperCapability (base for decorating capabilities), ReinjectSystemPrompt (guards against system prompt being truncated away), ProcessHistory (composable history transformation), ProcessEventStream (custom event handling), HandleDeferredToolCalls (inline deferred tool resolution), IncludeToolReturnSchemas (per-tool return schema injection), PrefixTools (capability-level tool prefixing), PrepareTools (capability-level tool preparation), SetToolMetadata (capability-level metadata tagging). New type aliases: RawToolArgs, ValidatedToolArgs, CapabilityRef, CapabilityPosition, CapabilityOrdering. CAPABILITY_TYPES registry for dynamic capability construction.
Prior (v1.86.x): capabilities parameter on Agent; Hooks with decorator registration; ModelProfile/DEFAULT_PROFILE; pydantic_ai.ui module (UIAdapter, UIEventStream, MessagesBuilder).
Prior (v1.85.x): 8 built-in tools, embeddings API, AG UI adapter, ApprovalRequiredToolset HITL, DeferredLoadingToolset. UrlContextTool deprecated — use WebFetchTool.
Prior (v1.84.x): durable execution, graph support, evals framework, Logfire/OpenTelemetry.

Install, minimal example

from pydantic import BaseModel
from pydantic_ai import Agent

class Answer(BaseModel):
    value: int
    reasoning: str

agent = Agent('openai:gpt-4o', output_type=Answer)

result = agent.run_sync("What is 15 + 27?")
print(result.data)  # Answer(value=42, reasoning='...')

Ready? Start Zero → Hero Step 1 →

Revision history

Date	Framework version (installed)	Summary of changes	Reviewer
2026-05-05	pydantic-ai 1.90.0	Version bumped 1.89.1 → 1.90.0; “What’s new” updated (DeferredToolCalls deprecated in favour of DeferredToolRequests); comprehensive guide header updated; revision history entry added. `Agent`, `TestModel`, `FunctionToolset`, `DeferredToolRequests`, `HandleDeferredToolCalls`, `ImageGenerationTool`, `MemoryTool`, `XSearchTool`, `RenamedToolset`, `WrapperToolset`, `IncludeReturnSchemasToolset`, `SetMetadataToolset`, `PreparedToolset` imports verified against installed 1.90.0 (`.routine-envs/check-0505`).	Claude routine
2026-05-02	pydantic-ai 1.89.1	Version bumped 1.89.0 → 1.89.1; “What’s new” heading updated; comprehensive guide header updated; revision history entry added. `Agent`, `OpenAIModel` imports verified against installed 1.89.1 (`.routine-envs/check-pydantic-0502`).	Claude routine
2026-05-01	pydantic-ai 1.89.0	Version bumped 1.88.0 → 1.89.0; “What’s new” heading updated; comprehensive guide header updated; revision history entry added. `Agent`, `OpenAIModel` imports verified against installed 1.89.0 (`.routine-envs/check-pydantic-0501`).	Claude routine
2026-04-29	pydantic-ai 1.88.0	Version bumped 1.87.0 → 1.88.0; “What’s new” heading updated; comprehensive guide header updated; revision history entry added. `Agent`, `OpenAIModel` imports verified against installed 1.88.0 (`.routine-envs/main-py-0429`).	Claude routine
2026-04-25	pydantic-ai 1.87.0	Version bumped 1.86.1 → 1.87.0; “What’s new” updated for v1.87.0 (9 new capability classes); new Capabilities API (v1.87.x) section added to comprehensive guide documenting `WrapperCapability`, `ReinjectSystemPrompt`, `ProcessHistory`, `ProcessEventStream`, `HandleDeferredToolCalls`, `IncludeToolReturnSchemas`, `PrefixTools`, `PrepareTools`, `SetToolMetadata`. All symbols verified against installed 1.87.0.	Claude routine
2026-04-24	pydantic-ai 1.86.1	Version bumped 1.85.1 → 1.86.1; “What’s new” updated for v1.86.x (Capabilities API, Hooks, ModelProfile, UI module); Capabilities API section added to comprehensive guide with verified snippets.	Claude routine
2026-04-22	pydantic-ai 1.85.1	Added 7 new deep-dive pages, all verified against installed 1.85.1 source: Output types & validators (ToolOutput / NativeOutput / PromptedOutput / TextOutput / StructuredDict + output_validator), Message history (ModelMessagesTypeAdapter, HistoryProcessor, capture_run_messages), Testing (TestModel, FunctionModel, Agent.override), Model providers & fallback (every prefix in `providers/__init__.py`, FallbackModel with custom handlers, gateway), Streaming (run_stream, run_stream_events, iter, AgentStream), Toolsets (FunctionToolset, Combined/Prefixed/Filtered/Prepared/Approval/Deferred/External), Built-in tools (WebSearch, WebFetch, CodeExecution, ImageGeneration, FileSearch, Memory, MCPServer, XSearch). Index re-ordered into an 18-step Zero → Hero reading order; Jump-to-topic and Reference grids re-indexed.	Claude routine
2026-04-22	pydantic-ai 1.85.1	Version bumped 1.85.0 → 1.85.1; “What’s new” section updated for v1.85.x (8 built-in tools, embeddings API, AG UI adapter, ApprovalRequiredToolset HITL, DeferredLoadingToolset); fabricated `pydantic_ai.common_tools` imports replaced with correct `pydantic_ai.builtin_tools` API; `UrlContextTool` deprecation noted. Snippets verified against installed 1.85.1.	Claude routine
2026-04-21	pydantic-ai 1.84.1	Index redesigned with Zero → Hero + Jump-to-topic grid.	—
2026-04-18	pydantic-ai 1.84.1	Patch; bug fixes.	—
2026-04-17	pydantic-ai 1.84.0	Evals framework; graph support improvements.	—
November 2025	pydantic-ai 1.14.x	Initial 2025 guide with durable execution, graphs, integrations.	—