Pydantic AI v2: Capabilities and the Harness (2026)

In one line: Pydantic AI v2, released June 23, 2026, folds everything wrapped around an agent's core loop — instructions, tools, lifecycle hooks and model settings — into one composable primitive called a capability, ships a slimmer core beside a fast-moving Harness package, and halves its breaking-change window to three months.

TL;DR: Pydantic AI v2 landed on June 23, 2026, the framework's first major version since v1 last September.¹² The headline is a single new primitive — the capability — that bundles an agent's instructions, tools, lifecycle hooks and model settings into one composable unit.¹³ Around it, the team split the project into a small, stable core and a fast-moving first-party package called the Harness, and quietly cut the window it promises between breaking changes from six months to three.¹⁴ If you clear your v1 deprecation warnings first, almost nothing else should break.⁵

What you'll learn

• What shipped in Pydantic AI v2, and the exact date it went stable
• What a "capability" is, and why it anchors the entire release
• How the Harness and the leaner core divide responsibilities
• What actually breaks when you upgrade from v1 — and how the team softened it
• Why the no-breaking-changes window dropped from six months to three
• Where v2 sits in the wider 2026 agent-framework shipping wave

What shipped on June 23

Pydantic AI v2 went stable on June 23, 2026.¹ It is the first major release since v1 arrived last September, and the team is keen to point out that the gap covered more than a hundred releases "without once breaking your code."¹² Pydantic AI is the agent framework from the team behind Pydantic — the type-validation library used throughout much of the Python AI ecosystem — so a major version here is a signal worth reading rather than routine version churn.

The framing in the announcement, written by Pydantic's Douwe Maan, is that the interesting problems in agent building have moved.¹ "The inner loop of an agent is settled by now: call the model, run a tool, feed the result back," it argues. The leverage now lives in the layer around that loop — the instructions and tools you hand an agent, but also the hooks that rewrite what the model sees mid-run, context management, steering a run in flight, and loading the right tools just in time. v2's whole thesis is to turn that surrounding layer into one thing you compose.¹

Installation is a single command for existing uv users:

uv add pydantic-ai

That is the entire "getting v2" story if you are starting fresh.¹ The more interesting question is what that one primitive actually is.

One primitive: the capability

A capability in Pydantic AI is a single composable unit that bundles an agent's instructions, tools, lifecycle hooks and model settings, so that an entire extension — a memory system, a guardrail, a coding toolkit — can reach every layer of the agent through one concept.¹³ It is, in the team's words, "the unit of agent behavior that lives in the loop." You attach a capability the same way you attach anything else to an agent:

from pydantic_ai import Agent
from pydantic_ai.capabilities import Capability, Thinking, ToolSearch, WebSearch
from pydantic_ai.mcp import MCPToolset
from pydantic_ai_harness import CodeMode

agent = Agent(
    'anthropic:claude-opus-4-7',
    instructions='Research thoroughly and cite your sources.',
    capabilities=[
        Thinking(effort='high'),  # extended thinking, unified across providers
        CodeMode(),               # one run_code call replaces N tool calls, sandboxed by Monty
        WebSearch(),              # native where the provider supports it, local fallback otherwise
        ToolSearch(),             # discover tools on demand instead of listing hundreds upfront
        Capability(
            id='github',
            description='Look up GitHub issues, pull requests, and code.',
            instructions='Use the GitHub tools when a question is about a repository.',
            toolset=MCPToolset('https://mcp.example.com/github'),
            defer_loading=True,  # stays out of the prompt until the model loads it on demand
        ),
    ],
)

Some capabilities are thin. Thinking(effort='high') is really just a model setting — extended thinking, exposed in a way that is consistent across providers.¹ WebSearch() wraps a native web-search tool, used natively where the provider supports it. The powerful ones use hooks to read and rewrite what the model sees on every step: its tools, its instructions, and its message history.¹

Two of the batteries in that example are worth pausing on because they map directly to problems this site has covered. ToolSearch() lets the model "discover tools on demand instead of listing hundreds upfront" — the same overload problem that shows up when you try to answer how many tools an AI agent can actually handle before accuracy degrades.¹ The GitHub Capability in the example takes that further with defer_loading=True: the model sees only a one-line description in a compact catalog, then loads the whole bundle — instructions and tools together — in a single step when it decides it needs to.¹ CodeMode() collapses what would be many separate tool calls into a single run_code call, sandboxed by Monty, Pydantic's safe Python subset.¹⁶

Because a capability is serializable, an agent can be loaded from a spec file, and the surface is small enough that a coding agent pointed at the capabilities docs can write most of one for you.¹³ That serialization point is also why the primitive has become a magnet for the rest of the framework: in recent releases the team has turned instrumentation, deferred tool calls resolved in the loop, server-side compaction for OpenAI and Anthropic, dynamically built per-run capabilities, on-demand loading, and a pending message queue for steering a run mid-flight all into capabilities.¹ Even durable execution — the ability to preserve an agent's progress across transient failures and restarts — is being moved onto the same capability layer, a migration the team describes as still in progress at the time of the v2 release, with a runtime extension point tracked for after v2.¹

The Harness and a leaner core

The Pydantic AI Harness is a separate first-party package, pydantic-ai-harness, that ships the "batteries" for an agent: memory, guardrails, context management, file system access, code mode, and more.¹⁴ It is where the team spent June, alongside a headless coding agent built on Pydantic AI that they say they are dogfooding across Pydantic's own repositories.¹ Community authors already ship capabilities too — the announcement calls out VStorm among others — with a capability matrix in the Harness repo linking the ones the team endorses.¹

The split between core and Harness is deliberate, and it is the structural half of the v2 story. Core stays small and stable: it ships the loop, the providers, the capability and hooks API, and only the capabilities that either need deep provider support or are fundamental to every agent.¹ Everything else lives in the Harness, where it can move fast, and any capability can graduate into core once it proves broadly essential. The same instinct shows up in packaging: uv add pydantic-ai still includes OpenAI, Anthropic and Google by default, but the long tail of providers — bedrock, groq, mistral and friends — is now opt-in, so you install only what you use.¹

The pattern here — a stable kernel plus a fast-moving batteries package — is one that memory-and-context tooling has been converging on across the ecosystem, and it rhymes with the split between a model's raw context window and the machinery that manages it, a theme explored in this walkthrough of Claude's memory tool and context editing. Pydantic's version puts a name and a package boundary on it.

What breaks when you upgrade from v1

Upgrading from Pydantic AI v1 to v2 is designed to be nearly a no-op — if you first move to the latest v1 and clear every deprecation warning.¹⁵ The announcement's blunt advice is to point a coding agent at those warnings; doing so covers most of the migration. What a deprecation warning could not catch is a short list, and it is worth knowing before you bump the pin:

• openai: model names now use the Responses API by default. Use the openai-chat: prefix to stay on Chat Completions.¹
• WebSearch and WebFetch are native by default, and MCP(url=...) runs locally by default.¹
• Instrumentation now defaults to version 5, with aggregated token-usage attributes.¹
• Function tools requested alongside a successful output tool now run instead of being skipped — the end_strategy='graceful' behavior.¹

The full list lives in the Upgrade Guide.⁵ The design goal is clear: the latest v1 already warns about most of what v2 changes, so the release itself should feel anticlimactic if you have kept current. That is a deliberately unglamorous migration story, and for teams running agents in production it is the most reassuring part of the release.

Six months to three: reading the version policy

The one change in v2 that has nothing to do with code is a promise. The window Pydantic AI guarantees between breaking changes within its support policy moves from six months to three.¹ The team is explicit that this is not a reduced commitment to stability: no breaking changes within a major version, and deprecations always landing before removals, both stay exactly as they were. What shrinks is only how far out the project is willing to commit to today's design decisions.

The stated reason is the tell: "The field moves fast enough that committing further out means committing to decisions that fit today and not the world three months from now."¹ Read as industry signal rather than release note, that is a framework maintainer saying the ground under agent design is still moving fast enough that a six-month architectural promise has become a liability. The evidence sits in the release itself — the capability primitive did not exist in this form a year ago, and durable execution is being re-homed onto it even now.¹ A three-month horizon is the team betting that the next reshaping is closer than the last one was.

Where v2 fits in the 2026 framework race

Pydantic AI v2 arrives in the middle of one of the busiest stretches the agent-framework ecosystem has seen. Across 2026, the graph-based and crew-based frameworks — LangGraph, CrewAI and the OpenAI Agents SDK among them — have all shipped heavily, and Pydantic AI itself has kept up a rapid release cadence since v2.⁷ The interesting thing is not who is winning but what everyone is building toward: context compaction, durable execution, tool search and deferred loading, memory, and guardrails. Those are production concerns, not demo concerns, and their appearance across otherwise-different frameworks is the clearest sign that agent tooling has crossed from novelty into infrastructure.

Pydantic AI's distinctive bet inside that convergence is consolidation. Where other frameworks expose separate surfaces for tools, memory, middleware and settings, v2 argues that all of it is the same shape — a capability — and that collapsing it into one composable, serializable unit is what makes agents easier to build, inspect and hand to another program to assemble.¹³ The MCP toolset in the example is a hint at how this plugs into the broader agent-tooling world: capabilities can wrap an MCP server the way the emerging stateless MCP spec intends, so the same governance and authorization story applies whether a tool is local or remote. And because instrumentation is now a capability, the traces an agent already emits close a loop the team is openly excited about: an agent that can read its own runs could, in principle, spot a pair of contradictory instructions or a tool whose description does not match what it does, and suggest the fix.¹

None of that makes Pydantic AI the only framework thinking this way, and the post does not need it to be. What v2 offers is a coherent answer to a question the whole field is now asking out loud: once the agent loop is boring, what is the right unit to build everything else out of?

The bottom line

Pydantic AI v2 is a consolidation bet: one primitive to compose everything that wraps an agent's loop, a small core that stays stable, and a Harness that can move as fast as the field does.¹ The most quietly revealing line in the release is not about capabilities at all — it is the decision to promise stability only three months out instead of six.¹ That is a maintainer telling you, in the language of a version policy, that the shape of agent frameworks is still being decided. v2 is one strong answer. It will not be the last one this year.