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

v2.43.0 · September 2026 · Python 3.10+ Each page carries its own “verified against” stamp: the newest deep dives are on 2.43.0, the class reference on 2.33.0, and some older topic pages still sit on the 1.10x line.

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

19 · Class & API reference Consolidated, source-verified reference — Agents, Models, Tools, Streaming, Capabilities, Durable Execution, Testing, Security & more · 60 min

Jump to a topic

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.

Class & API reference Consolidated, source-verified reference to every pydantic_ai/pydantic_graph/pydantic_evals class and function, in 16 topic sections. Verified against pydantic-ai 2.33.0.

10 class deep dives (Aug 2026) Runnable, source-verified examples for Agent, RunContext, UsageLimits, ToolReturn, DeferredToolRequests/Results, CachePoint, PrefixedToolset/FilteredToolset/RenamedToolset, WebSearchTool, and the error taxonomy. Verified against pydantic-ai 2.33.0.

10 more class deep dives (Aug 2026 · v2.36.0) AgentRun, AgentRunResult, StreamedRunResult, ModelSettings, Tool, ToolDefinition, RunUsage/RequestUsage, ConcurrencyLimiter, MCPToolset, ApprovalRequiredToolset/DynamicToolset — verified against pydantic-ai 2.36.0.

10 class deep dives (Sep 2026 · v2.40.0) RealtimeSession, RealtimeModelSettings/TurnDetection, AgentRealtime, Capability, Hooks, TemplateStr, ExternalToolset, RetryConfig/HTTPX2TenacityTransport, DuckDuckGoSearchTool, ImageGenerationSubagentTool — verified against pydantic-ai 2.40.0.

10 class deep dives (Sep 2026 · v2.43.0) ToolFailed, RunCancelled, ToolSelector, ToolOrOutput, ServiceTier/ThinkingLevel, AgentStream/StreamedRunResult, SkipModelRequest/SkipToolValidation/SkipToolExecution, ToolDefinition.sequential, OutputContext, ApprovalRequired/DeferredToolRequests — verified against pydantic-ai 2.43.0.

Advanced patterns

Error handling & testing

Hooks Lifecycle callbacks: Hooks capability.

Concurrency ConcurrencyLimiter, backpressure, distributed limiting.

Embeddings Embedder, EmbeddingModel, similarity search.

Durable execution (2025)

Graph support (2025)

Integrations 2025

Evals (2025)

Recipes

Diagrams

Production guide

Streaming server (FastAPI)

What’s new

Condensed version history (superseded the previous per-volume changelog — full historical detail lives in git history and the Revision history table below).

Version	Date	Highlight
1.14.x	Nov 2025	Initial guide: durable execution, graphs, integrations
1.84.0–1.85.x	Apr 2026	Evals framework, graph support; embeddings API; AG UI adapter; `ApprovalRequiredToolset` HITL; `DeferredLoadingToolset`; `UrlContextTool` deprecated
1.86.0–1.87.0	Apr 2026	Capabilities system introduced (`Hooks`, `AbstractCapability`, `ModelProfile`) and expanded with 9 more capability classes
1.88.0–1.96.0	Apr–May 2026	`DeferredToolCalls` deprecated → `DeferredToolRequests`; `TestModel` moved out of top-level; `AgentRun`/`AgentRunResultEvent`; `ConcurrencyLimiter`
1.98.0–1.99.0	May 2026	`pydantic_ai.ag_ui` deprecated → `pydantic_ai.ui.ag_ui`; `common_tools` module added
1.100.0–1.105.0	May–Jun 2026	`Hooks`, embeddings, `AgentSpec`, `MCPToolset`, UI adapters, native tool suite (WebSearch/WebFetch/CodeExecution/Memory), `AgentStream`, full `FunctionToolset` — first source-verified “class deep dive” reference material begins here
1.106.0–1.107.0	Jun 2026	Agent graph nodes promoted to public API; `tool_timeout`/`max_concurrency`; full Capabilities subsystem; Bedrock + expanded provider ecosystem; `pydantic_graph` `GraphBuilder`; SSRF-hardened `safe_download`
2.0.0	Jun 2026	Major version: `Agent.to_web`/`to_cli`/`run_stream_events`; `ToolManager` parallel execution modes; Temporal/DBOS/Prefect durable execution; `NativeOrLocalTool` capability family
2.2.0–2.5.1	Jul 2026	`FallbackModel` response handlers, `Embedder`, server-side compaction (`AnthropicCompaction`/`OpenAICompaction`), `OnlineEvaluation`, Z.AI/Vercel providers, `pydantic_graph` `Path`/`PathBuilder`, agentic evaluators
2.6.0–2.10.0	Jul 2026	`Hooks`+`HookTimeoutError`, `MCP` capability, built-in search capabilities (`WebSearch`/`WebFetch`/`XSearch`/`ImageGeneration`/`Thinking`), streaming event protocol, `AgentSpec` YAML/JSON
2.13.0–2.22.0	Jul–Aug 2026	Fine-grained `AgentRun` control, `SelectModel`/`ResolveModelId` routing, `RaiseContentFilterError`, MCP `prefer_tasks` durable calls, `RunContext.is_tool_available`
2.27.0	Aug 2026	`RunUsage.cost` + `CancellationToken`/`RunCancelled`; `ReinjectSystemPrompt`/`ProcessHistory` hardened for untrusted history
2.31.0	Aug 2026	`AgentSpec` YAML/JSON specs stabilised, `SelectModel`, native tool suite (Advisor/XSearch/ImageGeneration/WebFetch) complete
2.33.0	Aug 2026	Consolidated Class & API Reference added to the comprehensive guide — 44 sprawling deep-dive volumes folded into 16 organised sections; guide version currency refreshed end-to-end
2.36.0	Aug 2026	New 10-class deep-dive page (v2.36.0) — `AgentRun`, `AgentRunResult`, `StreamedRunResult`, `ModelSettings`, `Tool`, `ToolDefinition`, `RunUsage`/`RequestUsage`, `ConcurrencyLimiter`/`ConcurrencyLimit`, `MCPToolset`, `ApprovalRequiredToolset`/`DynamicToolset`.
2.40.0	Sep 2026	New 10-class deep-dive page (v2.40.0) — `RealtimeSession`, `RealtimeModelSettings`/`TurnDetection`, `AgentRealtime`, `Capability`, `Hooks`, `TemplateStr`, `ExternalToolset`, `RetryConfig`/`HTTPX2TenacityTransport`, `DuckDuckGoSearchTool`, `ImageGenerationSubagentTool` — all source-verified with runnable examples.
2.43.0	Sep 2026	Current. New 10-class deep-dive page (v2.43.0) — `ToolFailed`, `RunCancelled`, `ToolSelector`, `ToolOrOutput`, `ServiceTier`/`ThinkingLevel`, `AgentStream`/`StreamedRunResult`, `SkipModelRequest`/`SkipToolValidation`/`SkipToolExecution`, `ToolDefinition.sequential`, `OutputContext`, `ApprovalRequired`/`DeferredToolRequests` — all source-verified with runnable examples.

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

Condensed — one row per meaningfully distinct change to this index/guide pairing. Full historical detail for every prior volume lives in git history.

Date	Framework version	Summary
2026-09-14	pydantic-ai 2.43.0	Added `pydantic_ai_class_deep_dives_v2_43.md` — 10 source-verified deep dives for 2.43.0 (`ToolFailed`, `RunCancelled`, `ToolSelector`, `ToolOrOutput`, `ServiceTier`/`ThinkingLevel`, `AgentStream`/`StreamedRunResult`, `SkipModelRequest`/`SkipToolValidation`/`SkipToolExecution`, `ToolDefinition.sequential`, `OutputContext`, `ApprovalRequired`/`DeferredToolRequests`). Sources read: `pydantic_ai/exceptions.py`, `pydantic_ai/tools.py`, `pydantic_ai/settings.py`, `pydantic_ai/result.py`, `pydantic_ai/output.py`, `pydantic_ai/tool_manager.py`. Version bumped from 2.40.0 → 2.43.0. Comprehensive guide addendum and v2.40.0 cross-link added.
2026-09-07	pydantic-ai 2.40.0	Added `pydantic_ai_class_deep_dives_v2_40.md` — 10 source-verified deep dives for 2.40.0 (`RealtimeSession`, `RealtimeModelSettings`/`TurnDetection`, `AgentRealtime`, `Capability`, `Hooks`, `TemplateStr`, `ExternalToolset`, `RetryConfig`/`HTTPX2TenacityTransport`, `DuckDuckGoSearchTool`, `ImageGenerationSubagentTool`). Sources read: `pydantic_ai/realtime/_session.py`, `pydantic_ai/realtime/settings.py`, `pydantic_ai/agent/abstract.py`, `pydantic_ai/capabilities/capability.py`, `pydantic_ai/capabilities/hooks.py`, `pydantic_ai/template.py`, `pydantic_ai/toolsets/external.py`, `pydantic_ai/retries.py`, `pydantic_ai/common_tools/duckduckgo.py`, `pydantic_ai/common_tools/image_generation.py`. Version bumped from 2.36.0 → 2.40.0.
2026-08-31	pydantic-ai 2.36.0	Added `pydantic_ai_class_deep_dives_v2_36.md` — 10 more source-verified deep dives with runnable code examples (`AgentRun`, `AgentRunResult`, `StreamedRunResult`, `ModelSettings`, `Tool`, `ToolDefinition`, `RunUsage`/`RequestUsage`, `ConcurrencyLimiter`/`ConcurrencyLimit`, `MCPToolset`, `ApprovalRequiredToolset`/`DynamicToolset`). Linked from the Reference grid. Sources read: `pydantic_ai/run.py`, `pydantic_ai/result.py`, `pydantic_ai/settings.py`, `pydantic_ai/tools.py`, `pydantic_ai/usage.py`, `pydantic_ai/concurrency.py`, `pydantic_ai/mcp.py`, `pydantic_ai/toolsets/{approval_required,_dynamic}.py`. Version bumped from 2.33.0 → 2.36.0.
2026-08-24	pydantic-ai 2.33.0	Added `pydantic_ai_class_examples_2026_08.md` — 10 source-verified deep dives with runnable code examples (`Agent`, `RunContext`, `UsageLimits`, `ToolReturn`, `DeferredToolRequests`/`Results`, `CachePoint`, `PrefixedToolset`/`FilteredToolset`/`RenamedToolset`, `WebSearchTool`, `FunctionToolset`, `ModelRetry`/`UnexpectedModelBehavior`/`ModelHTTPError`). Linked from the Reference grid. Sources read: `pydantic_ai/agent/__init__.py`, `_run_context.py`, `usage.py`, `messages.py`, `_deferred.py`, `toolsets/{function,filtered,renamed,prefixed}.py`, `native_tools/__init__.py`, `exceptions.py`.
2026-08-21	pydantic-ai 2.33.0	Consolidated the 44 `pydantic_ai_class_deep_dives.md` / `pydantic_ai_advanced_classes_part2.md` / `pydantic_ai_source_code_deep_dive.md` volumes into one Class & API Reference* section (16 subsections) inside the comprehensive guide; deleted the 44 source files; replaced the 44 individual `LinkCard`s and the per-volume “What’s new” narrative with the single reference link and condensed changelog above; version badge and guide banners bumped to 2.33.0.
2026-07-20	pydantic-ai 2.13.0	`AgentRun`/`AgentRunResult`/`AgentRunResultEvent` fine-grained control; `FunctionModel`/`AgentInfo`; `FallbackModel`/`ResponseRejected`; tenacity HTTP retry; `FilteredToolset`/`DeferredLoadingToolset`/`ToolSearchToolset`; `WrapperModel`/`CompletedStreamedResponse`; `WrapperCapability`; `MessagesBuilder`/`BuilderCheckpoint`.
2026-07-15	pydantic-ai 2.10.0	`UsageLimits`/`RunUsage`/`RequestUsage` fixes; `AgentSpec` YAML/JSON; cross-provider `ModelSettings` reference; `ConcurrencyLimiter`; output-mode toolkit; two-round HITL `ApprovalRequiredToolset` flow.
2026-07-08 to 2026-07-14	pydantic-ai 2.6.0–2.9.1	`Hooks`+`HookTimeoutError`; `ProcessHistory`/`ReinjectSystemPrompt`; `ApprovalRequiredToolset`/`ExternalToolset`; Vercel AI SDK v5/v6 + AG-UI HITL adapters; new provider profiles (`harmony`/`moonshotai`/`amazon`); built-in search capabilities (`WebSearch`/`WebFetch`/`XSearch`/`ImageGeneration`/`Thinking`); streaming event protocol; `DynamicToolset`.
2026-06-25 to 2026-07-09	pydantic-ai 2.0.0–2.5.1	Major v2.0.0: `Agent.to_web`/`to_cli`/`run_stream_events`; `ToolManager` parallel execution modes; Temporal/DBOS/Prefect durable execution; `NativeOrLocalTool` capability family. Then: toolset composition (`FallbackModel`, `Embedder`), server-side compaction, `OnlineEvaluation`, Z.AI/Vercel providers, `pydantic_graph` `Path`/`PathBuilder`, agentic evaluators.
2026-06-12 to 2026-06-21	pydantic-ai 1.106.0–1.107.0	Agent graph nodes (`UserPromptNode`/`ModelRequestNode`/`CallToolsNode`) promoted to public API; `tool_timeout`/`max_concurrency`; full Capabilities subsystem (`Hooks`, `Instrumentation`, `MCP`, `ToolSearch`); AWS Bedrock + expanded provider ecosystem (Alibaba/OVHcloud/Heroku/gateway); `pydantic_graph` `GraphBuilder`; SSRF-hardened `safe_download`.
2026-05-22 to 2026-06-05	pydantic-ai 1.101.0–1.105.0	`Tool`/`ModelSettings`/`Hooks`/`Thinking`/`WebSearch` deep dives begin (source-verified against installed package); `MCPToolset`, UI adapters, native tool suite, `AgentStream`, full `FunctionToolset`; `builtin_tools=` migrated to `capabilities=[NativeTool(...)]`.
2026-05-01 to 2026-05-20	pydantic-ai 1.89.0–1.99.0	`DeferredToolCalls` deprecated → `DeferredToolRequests`; `TestModel` moved out of top-level; new exports `AgentRun`/`AgentRunResultEvent`/`AgentEventStream`; `ConcurrencyLimiter` + `limit_model_concurrency`; `pydantic_ai.ag_ui` deprecated in favour of `pydantic_ai.ui.ag_ui`; `common_tools` module added.
2026-04-17 to 2026-04-29	pydantic-ai 1.83.0–1.88.0	Hard removal of `result_` → `output_` renames; `EvaluationReport` API; pydantic-graph branching/looping; `defer_loading`; `ThreadExecutor`; `OllamaModel`; Capabilities API introduced and expanded (9 new capability classes).
2026-04-21 to 2026-04-22	pydantic-ai 1.84.1–1.85.1	Embeddings API; AG UI adapter; `ApprovalRequiredToolset` HITL; `DeferredLoadingToolset`; `UrlContextTool` deprecated; index redesigned with Zero → Hero + Jump-to-topic grid.
2025-11	pydantic-ai 1.14.x	Initial 2025 guide with durable execution, graphs, integrations.