itechmeat/llm-code/pydantic-ai

Pydantic AI

Python agent framework for building production-grade GenAI applications with the "FastAPI feeling".

Quick Navigation

When to Use

• Building AI agents with structured output
• Need type-safe, IDE-friendly agent development
• Require dependency injection for tools
• Multi-model support (OpenAI, Anthropic, Gemini, etc.)
• Production observability with Logfire
• Complex workflows with graphs

Installation

See references/installation.md for full/slim install options and optional dependency groups. Requires Python 3.10+.

Release Highlights (2.49.0 -> 2.59.0)

• Security (upgrade): three advisories landed in this window - the local web_fetch HTML conversion stall (High, GHSA-4whf-38hw-pxxh, fixed in 2.59.0/v1.107.9), MCP server URLs/tokens/custom headers leaking into OpenTelemetry traces and URL-derived credential exposure (Medium, GHSA-xv4x-g8mx-ch56, fixed in 2.58.0/v1.107.8), and client-triggered tool execution through the Vercel AI/AG-UI adapters with server-side message_history (Medium, GHSA-5pfm-2g3g-gh85, fixed in 2.58.0). Rotate MCP credentials when upgrading from below 2.58.0. Details in references/security.md.
• Workspaces and sandboxes (2.52.0+): ctx.workspace gives Coder, Shell and FileSystem one API for files and commands, running locally or in a sandbox with durable execution. New providers: SpritesSandbox (Fly.io Sprite), E2BSandbox, SSHWorkspace, BubblewrapSandbox, and DaytonaSandbox (2.59.0); ModalSandboxBackend replaces ModalSandboxSession. Coder file tools get a retry budget of 5 and keep scratch files out of the project. See references/workspaces-and-sandboxes.md.
• Realtime (2.49.0 - 2.59.0): OpenAI GPT-Live via OpenAILiveModel (2.51.0) with browser WebRTC (2.52.0), ElevenLabsRealtimeModel (2.58.0), azure_voice_live_voice (2.52.0), gemini-3.8-live (2.50.0), RealtimeSession.wait_for_reply() (2.49.0), context_window_used (2.51.0), the async_tool_call_mode profile setting (2.52.0), and the AnswersRevised / OutputItemCut lifecycle events (2.59.0). See references/realtime.md.
• Provider-neutral errors (2.59.0): ModelRateLimitError, ModelUnavailableError, ModelServerError, ModelContextWindowExceededError, plus ModelHTTPError.for_category to map a raw provider error onto them.
• MCP Apps (2.57.0): tool results can carry resources and app surfaces, forwarded to the AG-UI and Vercel AI frontends. MCPToolset.read_resource_contents and MCPToolset.call_tool_for_app read a resource or call an app-producing tool; ToolKind typed tool parts (2.58.0) let any module emit a typed tool part. See references/mcp-apps.md.
• Decision models (2.49.0 - 2.50.0): DecisionModel (the base TypeSafeModel builds on) answers several questions in one call and routes from the answers, with route fields, decision_route_threshold, ModelSelectionContext.prompt and RunContext.in_durable_context. TypeSafeModel gained "none of these" semantics and whole-number Choice options; BoolCriteria types boolean answers. See references/decision-models.md.
• Providers and models (2.49.0 - 2.59.0): Claude Sonnet 5.5 (claude-sonnet-5-5) with AnthropicModel default max_tokens raised from 4096 to 16384 on Sonnet 4.5+ (and defaulting to the model's maximum output); MetaProvider for Meta Muse (2.57.0); OpenAI gpt-6-sol/gpt-6-luna/gpt-6-astra on Bedrock Converse with temperature/top_p dropped for GPT-5.6/GPT-6 there; GitHubCopilotProvider can send a configurable copilot-integration-id; shut-down Groq models (playai-tts, playai-tts-arabic, meta-llama/llama-guard-4-12b, meta-llama/llama-4-maverick-17b-128e-instruct) were removed.
• Agent control (2.57.0 - 2.59.0): DelegationTasks.steer steers a running delegated task; ModelSettings['max_retries'], whole-agent timeout= and RunContext.deadline; ApprovalReviewer lets a model approve low-risk tool calls before a person sees them; on_change='append' for dynamic instruction prefixes (also opt-in on FunctionToolset.instructions); tool_calls_limit is checked before each CodeMode nested call; BackgroundTools results are framed as <tool_result> tool output; read_file can return images and PDFs; SqliteStepStore stores each message once.
• Breaking change (2.52.0): SubAgents no longer load agent files by default, and inherit_tools is deprecated.

Release Highlights (2.40.0 -> 2.48.0)

• Security (upgrade) (2.44.0, backported to 1.107.6): four fixes reached through web_fetch_tool or OTel instrumentation — IPv6 zone-identifier bypass of the private-IP blocklist when local URLs are opted in, superlinear web_fetch HTML/charset processing that could stall the event loop, domain blocklists compared without resolver normalization, and span content leaks with include_content=False (GHSA-vmxc-h2x2-jmf3, GHSA-fpf4-vwcp-v4hp, GHSA-22h6-qm39-v87j, GHSA-4x9p-g9wm-8q7f).
• Realtime session control (2.40.0/2.46.0): handle_barge_in=True with interrupt(played_bytes=...), RealtimeSession.enqueue() for out-of-band prompts, respond= on send(), wait_for_playback(), and @agent.on_event listeners.
• Image generation (2.41.0): direct ImageGenerator API alongside the built-in tool; fallback_model on ImageGeneration/XSearch deprecated in favor of fallback_subagent_model.
• Providers and models (2.41.0/2.42.0/2.48.0): openai-codex provider for ChatGPT/Codex subscription auth, GitHubCopilotProvider; OpenAI gpt-6-sol/gpt-6-luna and Claude Opus 5.5 (claude-opus-5-5).
• Pricing (2.40.0): pydantic_ai.prices.update_in_background() refreshes genai-prices data in the background.
• Temporal (2.46.0): event_stream_topic on TemporalDurability streams agent events via Workflow Streams.

Release Highlights (2.23.0 -> 2.39.0)

• Realtime speech-to-speech (2.28.0): Agent.realtime() with browser WebRTC plus server sideband support; Azure AI Voice Live via the azure_voice_live setting (2.29.0); RealtimeSession.send_audio() accepts async iterables (2.36.0).
• Run cancellation (2.26.0): AgentRun.cancel(), RunContext.cancel(), and RunCancelled; stream_run_events() returns a public AgentRunEvents handle with cancel() and run-state access.
• Deferred tool reveal (2.23.0/2.26.0/2.30.0): ToolAvailabilityDeltaPart with native tool_addition/additional_tools; tools can stay hidden until revealed via tool search, load_capability, or ToolReturn.tools, on each provider's native deferral/addition channel; a deferred tool must be revealed before it can be called.
• Cost tracking (2.23.0): cost on RunUsage and cost_limit on UsageLimits. Context window (2.38.0): context_window on ModelProfile and context_window_used on RunContext.
• Typed events (2.38.0): application code and capabilities can emit typed CustomEvent/CapabilityEvent into the run event stream and subscribe with @on_event. Durable execution (2.36.0): @durable_operation for capabilities plus a public backend API for third-party durable execution engines.
• Providers and models: Crusoe (2.28.0), Snowflake Cortex (2.27.0), and vLLM (2.38.0) providers; gemini-3.7-flash (2.30.0), gemini-3.8-flash (2.38.0), Claude Fable 5.1 / Mythos 5.1 (2.38.0), OpenAI gpt-6-astra (2.39.0), GLM-5.3 on ZaiModel (2.34.0), DeepSeek V4 Flash (2.26.0).
• MCP and HTTP clients: MCPToolset supports FastMCP 4 and MCP SDK v2 alongside FastMCP 3 (2.29.0). Builds moved to httpx2 clients; pydantic-ai[anthropic] requires anthropic>=1.0.0 and a custom AnthropicProvider http_client must be an httpx2.AsyncClient (2.32.0/2.33.0).
• `clai` CLI (2.36.0): --mcp-config support and tool-call streaming. OpenRouter (2.30.0/2.32.0): openrouter:web_search for web search and web-search sources in provider_details["annotations"].
• Security (upgrade): 2.24.0 fixes unbounded memory in the local web_fetch tool / FileUrl media downloads (GHSA-v2xh-2vp8-57h8); 2.27.1 fixes a low-severity retry-prompt redaction leak when include_content=False (GHSA-3gh4-cghq-f8v4); 2.28.0 fixes a high-severity missing content-type check on the dev web chat UI so arbitrary cross-origin requests no longer run the agent (GHSA-h4xc-3qfq-jf93); 2.30.0 fixes DNS-rebinding via Host-header validation on the dev web chat UI, with an opt-in allowed_hosts for non-loopback deployments (GHSA-q2xc-rrxj-58x9).

Release Highlights (2.13.0 -> 2.22.0)

• Durability capabilities replace wrapper agents: TemporalDurability, DBOSDurability, and PrefectDurability (2.14.0) attach to a regular Agent via capabilities=[...], replacing the deprecated TemporalAgent / DBOSAgent / PrefectAgent wrapper classes (removed in v3). Existing wrapper-based workflows keep replaying correctly after switching. See integrations.md for the updated Temporal/DBOS/Prefect examples.
• New models/providers: Claude Opus 5 (2.20.0), gemini-3.6-flash/gemini-3.5-flash-lite (2.16.0), Mistral reasoning_effort (2.14.0) and mistral_prompt_cache_key (2.16.0), OpenAI explicit prompt caching for gpt-5.6 (2.15.0), BedrockMantleProvider (2.18.0), and the AdvisorTool builtin tool for Anthropic/OpenRouter (2.18.0).
• Usage & limits: cache_hit_ratio on RequestUsage/RunUsage (2.13.0), ToolFailed for model-visible failures that don't consume a retry (2.16.0), optional run_id= on runs (2.16.0), tool-retry budget overrides at run/iter/override time (2.15.0), and per_request_input_tokens_limit on UsageLimits (2.21.0).
• Error handling & instrumentation: ModelHTTPError now carries headers and a parsed retry_after from every provider SDK (2.19.0); RaiseContentFilterError capability and include_model_request_parameters instrumentation setting (2.13.0); per-message OTel serialization is cached to avoid O(n^2) cost (2.17.0).
• Dependencies: the fastmcp optional group now constrains fastmcp<4 (2.19.0).

Release Highlights (2.0.0 -> 2.12.0)