Pydantic AI V2 went stable on June 23, 2026. After seven betas and a full architectural rethink, the framework that brought FastAPI-style ergonomics to LLM development now ships with one concept that replaces most of what made early agent code messy: capabilities. This is not a point release. It is a deliberate redesign of how Python developers build production agents — and it solves a problem that LangChain never seriously addressed.
What Capabilities Actually Are #
The core idea is straightforward: a capability is a composable unit that bundles an agent’s tools, lifecycle hooks, instructions, and model settings into one named object. Instead of passing an ever-growing flat list of tools and a 2,000-token system prompt to the Agent
constructor, you compose capabilities.
from pydantic_ai import Agent, Thinking
agent = Agent(
'anthropic:claude-opus-4-6',
instructions="You are helpful.",
capabilities=[Thinking(effort='high')]
)
That is five lines. The Thinking
capability bundles extended reasoning, unified across Anthropic, OpenAI, and Google — one import, zero provider-specific boilerplate. Pydantic AI V2 ships eight built-in capabilities with core: Thinking
, WebSearch
, WebFetch
, ImageGeneration
, MCP
, ToolSearch
, PrepareTools
, and Hooks
. Each is a named, testable unit you can reuse across agents without copy-pasting hundreds of lines of tool definitions.
This is the FastAPI moment for agent frameworks. FastAPI did not invent HTTP routing — it gave Python developers a clean, typed way to express it. Capabilities do the same for agent behavior.
Deferred Capabilities: The Fix for Tool Explosion #
Agents with 50+ tools have measurably worse tool selection. The model burns tokens scanning irrelevant options, picks wrong tools at higher rates, and hallucinates tool arguments. This is a context-window problem disguised as an agent intelligence problem.
V2’s answer is deferred (on-demand) capabilities. Mark any capability defer_=True
and it stays invisible — a single catalog entry — until the model explicitly loads it. When loaded, everything activates together: instructions, tools, hooks, model settings. Nothing loads partially.
refunds = Capability(
id='refunds',
description='Use for refund eligibility and status.',
instructions='Always confirm order ID before refunds.',
defer_=True,
)
The model sees only the ID and a one-line description until it calls load_capability
. After that, the full runbook and associated tools activate. State persists via message history, so the capability survives conversation resumption across processes and model providers without re-discovery.
One gotcha: deferred capabilities require a stable, explicit id
. Omit it and agent construction raises an error. The framework uses the ID to replay history correctly — a class-derived ID would break silently on rename.
The Harness: Where the Real Power Lives #
The core/harness split is V2’s most consequential architectural decision. Core stays lean and stable — it ships the agent loop, provider integrations (OpenAI, Anthropic, Google by default), the capability API, and only capabilities fundamental to every agent. Everything else lives in pydantic-ai-harness, where it can move fast without strict backward-compatibility constraints.
uv add pydantic-ai-harness
uv add "pydantic-ai-harness[codemode]" # sandboxed Python execution
uv add "pydantic-ai-harness[dynamic-workflow]" # model-written fan-out scripts
The harness currently tracks 40+ capabilities. The standout is CodeMode. It wraps your existing tools into a single run_code
tool powered by a Monty sandbox. The model writes Python that calls multiple tools with loops, conditionals, and asyncio.gather
— all inside one tool call. What used to take 10 sequential roundtrips takes 1–2. If your agent is making more than five tool calls per task, CodeMode is worth evaluating immediately.
Other harness highlights: persistent key-value memory across sessions, sliding window context trimming with LLM-powered summarization, approval workflows for destructive tool calls, secret detection and redaction, and sub-agent delegation with specialized toolsets. Multi-agent team support is in active development. The full harness capability overview tracks each item’s implementation status.
Core Got Leaner — Pydantic AI V2 Providers Are Now Opt-In #
Previously, pip install pydantic-ai
pulled in providers you may never use. V2 fixes this: OpenAI, Anthropic, and Google ship by default. Bedrock, Groq, Mistral, and the rest are now opt-in.
uv add pydantic-ai # OpenAI, Anthropic, Google
uv add "pydantic-ai[groq]" # add Groq
uv add "pydantic-ai[mistral]" # add Mistral
This matters in Docker environments. Smaller installs mean fewer dependency conflicts, faster CI builds, and less risk of the kind of pydantic v1/v2 namespace collision that has historically caused production failures in frameworks that bundle too much. The full capabilities reference documents what ships with each install variant.
Breaking Changes and How to Migrate #
V2 breaks four things worth knowing before upgrading:
OpenAI model names now target the Responses API. Use theopenai-chat:
prefix for Chat Completions models.WebSearch and WebFetch are native by default. MCP servers now run locally by default.Instrumentation defaults changed to version 5 with aggregated token-usage attributes.Tool execution order: function tools requested alongside a successful output tool now execute (end_strategy='graceful'
).
The recommended migration path: upgrade to the latest V1 release first, resolve every deprecation warning, then move to V2. The Pydantic team’s own experience is that this approach captures most of the migration work with minimal additional breakage.
V2 also tightens the major-version policy: the no-breaking-changes window drops from six months to three. That is a reasonable trade at the pace AI development moves. Pin your versions and write upgrade tests.
Should You Migrate Now? #
Building new agents: Start on V2. The capabilities model is cleaner than anything that came before, and the harness gives you production-grade memory, guardrails, and sandboxed execution without writing it yourself.
Maintaining V1 agents in production: Upgrade to the latest V1 first, clear deprecations, then plan the V2 migration. The breaking changes are manageable but not trivial — give it a sprint, not an afternoon.
On LangChain for its ecosystem: V2 does not change that calculus yet. The harness is growing fast, but LangSmith and LangChain’s integration catalog still have no equivalent. Watch the harness roadmap.
Pydantic AI V2 did what Pydantic itself did: took a working but sprawling concept and gave it the right abstraction. Capabilities are that abstraction. The question is not whether to switch — it is when.