Pydantic AI V2: Build Python Agents With Capabilities

Pydantic AI V2 went stable on June 23, 2026, introducing a new 'capability' primitive that bundles tools, lifecycle hooks, instructions, and model settings into composable objects for building Python agents. The release also includes a separate Harness package with experimental features like CodeMode, which reduces model round-trips by having the model write Python code to orchestrate tools. The upgrade requires fixing five breaking changes from V1.

Pydantic AI V2 went stable on June 23, 2026, and it changes how Python agents are built. After seven betas, the release’s central contribution is a new primitive called a capability — a composable unit that bundles tools, lifecycle hooks, instructions, and model settings into one object. If you’ve been putting off the upgrade, the architecture is genuinely better and the migration is shorter than you expect. What Is a Capability? In V1, you wired an agent by passing a growing list of keyword arguments to the Agent constructor: tools= , mcp servers= , instrument= , prepare tools= , history processors= . In V2, all of that lives inside capabilities passed as a list. Each capability bundles everything a feature needs: its tools, the instructions that tell the model when to use them, any lifecycle hooks, and model settings — one composable object. The practical payoff is reusability. Build a memory capability once, drop it into any agent that needs it. Set defer loading=True and the capability collapses to a single catalog entry — the model loads the full bundle only when it decides to use it, reducing token overhead on agents with large tool sets. python from pydantic ai import Agent from pydantic ai.capabilities import Capability, Thinking, WebSearch from pydantic ai.mcp import MCPToolset agent = Agent 'anthropic:claude-sonnet-5', instructions='Research thoroughly and cite sources.', capabilities= Thinking effort='high' , WebSearch , Capability id='github', description='Look up GitHub issues, PRs, and code.', instructions='Use GitHub tools when questions involve repositories.', toolset=MCPToolset 'https://mcp.example.com/github' , defer loading=True, , , The Pydantic AI Harness The Harness https://github.com/pydantic/pydantic-ai-harness is a separate package — pydantic-ai-harness — that ships capabilities not yet ready for core. The split is deliberate: core stays small and stable; the Harness iterates quickly. When a capability matures and proves broadly useful, it graduates into core. The Harness currently ships memory systems, guardrails, context management, file system access, and the feature most worth your attention: CodeMode. CodeMode: Fewer Round-Trips, Same Tools CodeMode wraps your existing tools into a single run code tool. Instead of one model round-trip per tool call, the model writes Python code that orchestrates your tools — with asyncio.gather for parallel calls, loops, and conditionals — inside a single execution. An agent that previously needed 11 model calls to fetch and process 10 items now does it in roughly 2. The runtime is Monty https://github.com/pydantic/monty , a minimal Python interpreter written in Rust. It runs a safe subset: standard library modules including asyncio , json , re , math , and pathlib are available. No third-party imports, no timing primitives — sandboxed by design. python from pydantic ai import Agent from pydantic ai harness import CodeMode uv add "pydantic-ai-harness code-mode " agent = Agent 'anthropic:claude-sonnet-5', capabilities= CodeMode @agent.tool plain def get weather city: str - dict: return {'city': city, 'temp f': 72, 'condition': 'sunny'} @agent.tool plain def convert temp fahrenheit: float - float: return round fahrenheit - 32 5 / 9, 1 result = agent.run sync "Weather in Paris and Tokyo, in Celsius?" The model receives one run code tool instead of two separate ones. It calls both tools for both cities inside a single code block using asyncio.gather . Pydantic’s docs note CodeMode is “an early candidate to graduate into core” — meaning this won’t always require the Harness package. Five Breaking Changes to Fix Before You Upgrade The V1-to-V2 migration path is: upgrade to the latest V1 first, fix every deprecation warning, then jump to V2. That handles roughly 80% of the work. The remaining 20% is a short list of behavior changes that warnings couldn’t catch: The It now routes to the Responses API instead of Chat Completions. If your code uses openai: prefix changed silently. openai: and expects Chat Completions behavior, switch to openai-chat: . This is the most dangerous change — it produces no error, just different behavior. Provider extras are now opt-in. Bedrock, Groq, Mistral, Cohere, and others are no longer installed with a bare pip install pydantic-ai . Add them explicitly: pip install 'pydantic-ai bedrock,groq ' . The MCP server classes are gone. MCPServerStdio , MCPServerSSE , and MCPServerStreamableHTTP are removed. Use MCPToolset from pydantic ai.mcp instead, and replace agent.run mcp servers with async with agent: . WebSearch and WebFetch default to native-only. If your model doesn’t support native search, requests will raise instead of falling back silently. Restore fallback behavior: WebSearch local='duckduckgo' or WebFetch local=True . Agent constructor kwargs migrated to capabilities. The kwargs instrument= , mcp servers= , prepare tools= , and history processors= are removed from Agent . Pass Instrumentation ... , PrepareTools ... , and ProcessHistory ... as capabilities instead. One thing that does not break: message history. V1-serialized messages continue to deserialize in V2, so persistent conversations survive the upgrade intact. Upgrade Now V1 is not deprecated, but the capability pattern is cleaner architecture for anything beyond a single-tool agent. If you run multi-tool agents — especially with MCP servers — the migration pays off immediately: less constructor configuration, reusable capabilities, and CodeMode to cut tool round-trips. The version policy also changed: breaking change windows shrink from six months to three months between majors, so the sooner you’re on V2, the more runway you have before the next transition. Start with the upgrade guide https://pydantic.dev/docs/ai/project/changelog/ , review the V2 announcement https://pydantic.dev/articles/pydantic-ai-v2 for the architectural overview, and explore the CodeMode docs https://pydantic.dev/docs/ai/harness/code-mode/ for any agent doing repeated tool calls.