Install
pip install pydantic-aiType-safe agents with validated outputs, dependency injection, durable execution, and graph support.
The Pydantic way for Generative AI. Type-safe agents with validated inputs/outputs, FastAPI-inspired dependency injection, composable capabilities, durable execution, graph-based workflows and a first-class evals framework.
Install
pip install pydantic-aiVersion
pydantic-ai 2.68.0 · Python 3.11+ Pages are checked against this release (2026-11-19).
Best for
Typed APIs, structured output, validated data pipelines, evals-driven agents.
Condensed version history. The upstream changelog has the full detail.
| Version | Date | Highlights |
|---|---|---|
| 1.0.0 | Sep 2025 | API stability commitment for the 1.x line. FallbackModel, ApprovalRequiredToolset and DeferredToolRequests already present. |
| 1.1–1.40 | Sep 2025 – Jan 2026 | AG-UI adapter (AGUIAdapter), WebFetchTool, embeddings API (Embedder). |
| 1.41–1.75 | Jan–Apr 2026 | ConcurrencyLimiter; capabilities system (AbstractCapability, Hooks) and AgentSpec. |
| 1.76–1.94 | Apr–May 2026 | DeferredLoadingToolset and ToolSearch; ToolOrOutput. |
| 1.95–1.107 | May–Jun 2026 | V2 removals announced as PydanticAIDeprecationWarnings; NativeOrLocalTool capabilities; MCPToolset (1.97). |
| 2.0.0 | Jun 2026 | Major version. openai: means the Responses API; builtin_tools= → capabilities=[NativeTool(...)]; MCPServer* → MCPToolset; result.usage is a property; run_stream_events() is a context manager; default end_strategy='graceful'; ModelProfile is a TypedDict; slimmer default extras; graph persistence removed. See Upgrading from V1. |
| 2.10–2.13 | Jul 2026 | SelectModel and ResolveModelId capabilities. |
| 2.14 | Jul 2026 | Durability capabilities (TemporalDurability, DBOSDurability, PrefectDurability); the wrapper agents are deprecated. |
| 2.15–2.40 | Jul–Sep 2026 | ToolFailed, AdvisorTool, CancellationToken / RunCancelled, realtime voice sessions (agent.realtime()). |
| 2.51–2.59 | Sep–Oct 2026 | Caching and LocalWorkspace capabilities. |
| 2.60 | Oct 2026 | RetryPromptPart deprecated for ToolReturnPart(outcome='retried') and RetryFeedbackPart; 'max' thinking level; FileUnderstanding capability; ModelSelectionContext gains usage_limits, deadline, run_id, conversation_id. |
| 2.61 | Oct 2026 | Citations capability and TextPart.citations; thinking=False sends the lowest accepted level on models that cannot disable thinking; async auth functions for hosted MCP capabilities. |
| 2.62–2.63 | Oct 2026 | BatchModelRequests capability and model_request_batch for provider batch APIs; PendingModelResponse; OpenAICompatibleProvider; ModelAuthenticationError, ModelNotFoundError and ModelRequestRejectedError. |
| 2.64 | Nov 2026 | ModelFallback capability (with sticky=); RetryModelRequest for retrying a request from model-request hooks; first_event_timeout model setting; SpeechTimestamp types. |
| 2.65–2.66 | Nov 2026 | ModelFallback also falls back on refusals (ContentFilterError is in its default fallback_on); FunctionToolset(requires_approval=True) covers Tool instances passed to it; Z.ai quota 429s raise ModelQuotaExceededError; include_instructions on the MCP capability; retries on SummarizingCompaction; OpenSandbox and RenderSandbox workspaces. |
Version ranges are where a feature first appears in the published wheels; the changelog has exact versions.
from pydantic import BaseModelfrom pydantic_ai import Agent
class Answer(BaseModel): value: int reasoning: str
agent = Agent('openai:gpt-6.1-sol', output_type=Answer)
result = agent.run_sync("What is 15 + 27?")print(result.output) # Answer(value=42, reasoning='...')Ready? Start Zero → Hero step 1 →
| Date | Summary |
|---|---|
| 2026-10-25 | Version bump to pydantic-ai 2.68.0: retry-part deprecation, 'max' thinking level, Citations and FileUnderstanding, 2.60 and 2.61 rows in the version table. |
| 2026-10-25 | Every page re-audited and its examples re-run offline against pydantic-ai 2.68.0. Corrected: what-is-new version ranges (from the published wheels), ProcessHistory persistence, settings merge order, async for hook behaviour, graph type checking (type checker, not build()), partial structured streaming, MCP server install and stdio environment, pai CLI name, EmbeddingResult.model_name, the wrap_tool_execute handler signature, two broken placeholder code blocks. Added: Conversation, ReinjectSystemPrompt, output functions, Choices, BoolCriteria, None output, MCP resources and prompts, in-process MCP testing, ALLOW_MODEL_REQUESTS, cancellation example, graph stream steps, report evaluators and evaluation metrics, online-eval sampling and sinks, Tavily, real reflection and delegation patterns. |
| 2026-10-21 | Comprehensive guide rewritten (class reference replaced by an Agent reference and API map); production page rewritten around PydanticAI’s own production features; toolsets page de-duplicated; evals and integrations pages moved to undated URLs. Whole guide re-verified against pydantic-ai 2.68.0; V1-era examples migrated to the V2 API; the durable execution, graph, evals and integrations pages rewritten around the real durable_exec, pydantic_graph, pydantic_evals, MCP and A2A APIs; the standalone per-class pages folded into the topic pages and the comprehensive guide’s class reference. |
| 2026-08-21 | Class & API Reference consolidated into the comprehensive guide. |
| 2026-04 | Index redesigned with Zero → Hero and Jump-to-topic grids. |
| 2025-11 | Initial guide (1.x). |