Skip to content

PydanticAI

Type-safe agents with validated outputs, dependency injection, durable execution, and graph support.

GroupLightweight
Current versionv2.68.0
Bonds withPy

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

Terminal window
pip install pydantic-ai

Version

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.

VersionDateHighlights
1.0.0Sep 2025API stability commitment for the 1.x line. FallbackModel, ApprovalRequiredToolset and DeferredToolRequests already present.
1.1–1.40Sep 2025 – Jan 2026AG-UI adapter (AGUIAdapter), WebFetchTool, embeddings API (Embedder).
1.41–1.75Jan–Apr 2026ConcurrencyLimiter; capabilities system (AbstractCapability, Hooks) and AgentSpec.
1.76–1.94Apr–May 2026DeferredLoadingToolset and ToolSearch; ToolOrOutput.
1.95–1.107May–Jun 2026V2 removals announced as PydanticAIDeprecationWarnings; NativeOrLocalTool capabilities; MCPToolset (1.97).
2.0.0Jun 2026Major 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.13Jul 2026SelectModel and ResolveModelId capabilities.
2.14Jul 2026Durability capabilities (TemporalDurability, DBOSDurability, PrefectDurability); the wrapper agents are deprecated.
2.15–2.40Jul–Sep 2026ToolFailed, AdvisorTool, CancellationToken / RunCancelled, realtime voice sessions (agent.realtime()).
2.51–2.59Sep–Oct 2026Caching and LocalWorkspace capabilities.
2.60Oct 2026RetryPromptPart deprecated for ToolReturnPart(outcome='retried') and RetryFeedbackPart; 'max' thinking level; FileUnderstanding capability; ModelSelectionContext gains usage_limits, deadline, run_id, conversation_id.
2.61Oct 2026Citations 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.63Oct 2026BatchModelRequests capability and model_request_batch for provider batch APIs; PendingModelResponse; OpenAICompatibleProvider; ModelAuthenticationError, ModelNotFoundError and ModelRequestRejectedError.
2.64Nov 2026ModelFallback capability (with sticky=); RetryModelRequest for retrying a request from model-request hooks; first_event_timeout model setting; SpeechTimestamp types.
2.65–2.66Nov 2026ModelFallback 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 BaseModel
from 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 →


DateSummary
2026-10-25Version 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-25Every 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-21Comprehensive 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-21Class & API Reference consolidated into the comprehensive guide.
2026-04Index redesigned with Zero → Hero and Jump-to-topic grids.
2025-11Initial guide (1.x).