Pydantic AI V2: Capabilities & Harness

TL;DR + what’s new

Pydantic AI is a Python agent framework from the Pydantic team that applies FastAPI-style type safety and validation to LLM agent code. Version 2, released June 23, 2026, reorganizes every extension point — tools, system prompt text, model settings, lifecycle hooks — around one primitive called a capability: a reusable, composable unit of agent behavior you attach to an Agent via a single capabilities=[...] list.

• Capability replaces four separate constructor arguments (tools, instructions, hooks, model settings) with one object that can provide any combination of them.
• Pydantic AI Harness is a new, separate package — “the batteries for your agent” — shipping pre-built capabilities: memory, guardrails, sandboxed code execution, file system and shell access, and more.
• MCP support runs both directions: agents can call out to MCP servers, and Pydantic AI agents can themselves be exposed inside an MCP server — confirmed directly against Pydantic’s docs below.

The announcement came from the framework’s own account, and it is worth reading in full because the phrasing is precise about what changed and what didn’t:

What Pydantic AI actually is

Per Pydantic’s own docs, Pydantic AI is designed “to help you quickly, confidently, and painlessly build production grade applications and workflows with Generative AI,” bringing “that FastAPI feeling to GenAI app and agent development.” The pitch: nearly every Python LLM library already leans on Pydantic Validation for structured output, but before this framework, none of them wrapped that validation in FastAPI’s ergonomics — decorators, type hints, validation as the default path, not an afterthought. You write typed Python functions; the framework turns them into tool schemas; swapping model providers (OpenAI, Anthropic, Gemini, and others) leaves your business logic untouched.

Before v2, extending an agent meant threading more arguments through the Agent constructor: a tools list here, a system-prompt string there, model settings somewhere else, an event hook bolted on last. Nothing forced those four things to travel together, so a reusable extension — a memory system, a guardrail — meant wiring up several disconnected pieces by hand, every time you wanted to reuse it. That is the gap the capability closes.

Takeaway: if you have used Pydantic (the validation library) or FastAPI before, the pitch will land in one sentence — this is the same ergonomics bet, applied one layer up, to the agent itself rather than the API route.

Core, capability, Harness — the three pieces

Three named pieces do all the work in v2, and the boundary between them is deliberate:

• Core (pydantic-ai-slim) — the agent loop, the model-provider adapters, and the Capability API itself. Small and stable by design.
• Capability — the composable unit. Anything that bundles tools, instructions, hooks, or model settings, attached via capabilities=[...].
• Harness (pydantic-ai-harness) — a separate, official package of pre-built capabilities that don’t (yet) belong in core.

Takeaway: the split is not arbitrary. Core keeps only what needs deep provider integration or is load-bearing for nearly every agent (Thinking, WebSearch, MCP); everything else moves at Harness speed and can “graduate” into core once it proves broadly essential — Pydantic’s own docs name Code Mode as an early candidate for exactly that move.

Smallest end-to-end example

Install core plus the Harness (the extras in brackets pull in the model provider, MCP support, a local search fallback, Logfire tracing, and Code Mode):

uv add "pydantic-ai-slim[anthropic,mcp,duckduckgo,logfire]" "pydantic-ai-harness[code-mode]"

Then stack three capabilities on one agent — this example is reproduced from the Harness’ own README:

from pydantic_ai import Agent
from pydantic_ai_harness import CodeMode, WebSearch
from pydantic_ai.capabilities import MCP

agent = Agent(
    'anthropic:claude-opus-4-7',
    capabilities=[
        CodeMode(),
        WebSearch(native=False),
        MCP('https://hn.caseyjhand.com/mcp', native=False),
    ],
)

Three extensions, one line each: sandboxed code execution, web search with a local fallback, and a live MCP connection to a Hacker News server. No separate tool registration step, no separate hook wiring for the sandbox — each capability owns its own tools, instructions, and lifecycle behavior internally.

Takeaway: however many extensions you stack, the constructor signature never grows past capabilities=[...]. That uniformity is the actual product, not a syntax nicety.

Capabilities: the primitive, deep dive

A capability is “a reusable, composable unit of agent behavior,” per Pydantic’s core-concepts docs — the primary extension point for the whole framework. Custom capabilities subclass AbstractCapability, which exposes configuration methods (get_toolset, get_native_tools, get_instructions, get_model_settings) called once at construction, and lifecycle hooks (like before_tool_execute) that fire on every run:

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext
from pydantic_ai.capabilities import AbstractCapability

@dataclass
class ApprovalGate(AbstractCapability[None]):
    id: str = 'approval'
    description: str = 'Confirms destructive actions.'

    def get_instructions(self) -> str:
        return 'Seek approval before deleting data.'

    async def before_tool_execute(self, ctx, *, call, tool_def, args):
        if 'delete' in tool_def.name:
            # Custom approval logic
            pass
        return args

agent = Agent('openai:gpt-5.2', capabilities=[ApprovalGate()])

For simpler cases, the Capability() helper skips the subclass entirely. Its most consequential field is defer_loading: set it True and the capability collapses to a one-line catalog entry until the model explicitly calls a framework-managed load_capability tool, at which point its instructions activate, its tools register, and it stays active — including across history replay on a resumed conversation:

from pydantic_ai import Agent
from pydantic_ai.capabilities import Capability

refunds = Capability(
    id='refunds',
    description='Use for refund eligibility and status.',
    instructions='Always confirm order ID before processing.',
    defer_loading=True,
)

@refunds.tool_plain
def refund_status(order_id: str) -> str:
    """Look up refund status."""
    return f'Order {order_id}: refund issued 2026-05-01.'

agent = Agent('openai-responses:gpt-5.4', capabilities=[refunds])

Takeaway: capabilities are more than syntactic sugar over tool registration — the lifecycle hooks and defer_loading give you levers (approval gates, progressive tool disclosure) that a flat list of functions passed to tools=[...] cannot express on its own.

The Harness: batteries, not bloat

pydantic-ai-harness first shipped on PyPI in April 2026, roughly two months before v2 core went stable — the Harness was already proving itself as a fast-moving package before the core it plugs into froze around the capability primitive. Install it with uv add pydantic-ai-harness, or with extras for Code Mode, Logfire, or ACP support.

The repo’s own capability matrix lists more than 40 features across nine categories. The shape of that list says as much as any individual entry:

Two entries are worth calling out. First, ACP (Agent Client Protocol) support puts the Harness in the same conversation as editor integrations — if you have not run into ACP before, our ACP vs MCP explainer covers how it differs from MCP (one wires an agent into an editor’s UI, the other wires an agent into external tools and data). Second, “Skills” appears as its own orchestration capability, the same name Anthropic uses for Claude’s packaged instruction-and-tool bundles — convergent naming, not a shared implementation.

Takeaway: the Harness is not a grab-bag of examples. It is a versioned, installable package with its own release cadence, and the matrix reads like a checklist for “what does a production coding or research agent actually need” — because that is exactly what Pydantic built it to answer.

The headless coding agent Pydantic dogfoods on itself

The v2 announcement is specific about one more thing shipping alongside the Harness: “a headless coding agent built on Pydantic AI that we are dogfooding across Pydantic’s own repositories.” That is the whole public description — as of this writing, Pydantic has not given it a standalone product name or a public release, in the article, the Harness README, or anywhere else we could verify. Treat it as an internal proof point, not a tool you can install today.

What it is built from is verifiable, though: the exact Harness capabilities that make a coding agent possible — Code Mode for sandboxed execution, file system and shell access, repo-context auto-loading, sub-agents, and tool-error recovery. Code Mode is the load-bearing piece, and Douwe Maan, Pydantic AI’s lead engineer (the same byline on the v2 article), explained the reasoning on Hacker News when the feature first shipped: it lets “the LLM chain tool calls, pull out specific fields, and run entire algorithms using tools with only the necessary parts of the result (or errors) going back to the LLM,” instead of round-tripping every intermediate value through a new model turn. It runs by default on Monty, a sandboxed Python runtime.

If you have used Claude Code or a similar terminal coding agent, the shape will feel familiar: a loop that reads files, edits them, runs commands, and checks its own work. The difference here is that every piece of that loop is an off-the-shelf Harness capability rather than bespoke glue code, which is the whole argument for capabilities existing in the first place.

Takeaway: the interesting story is not “Pydantic shipped a coding agent” — it’s that the Harness is complete enough to build one from off-the-shelf capabilities and have Pydantic trust it on their own codebase before productizing it.

MCP support: client and server, both real

The Model Context Protocol is the open standard for connecting AI applications to external tools and data sources. We checked Pydantic AI’s MCP docs directly rather than take the “MCP” mention in the README at face value, and the support is genuinely bidirectional:

• As a client — “agents can connect to MCP servers and use their tools,” via the MCP capability or the lower-level MCPToolset for direct lifecycle management.
• As a server — “agents can be used within MCP servers,” documented separately in Pydantic’s MCP server guide. Most Python agent frameworks only do the first half.

from pydantic_ai import Agent
from pydantic_ai.capabilities import MCP

agent = Agent(
    'openai:gpt-5.2',
    capabilities=[
        MCP(url='https://mcp.example.com/api'),
        MCP(url='https://mcp.example.com/other', native=True),
    ],
)

One v2-specific change matters here: MCP connections now run locally by default, which Pydantic’s docs frame as “keeping credentials, hooks, and tracing under your control.” Set native=True to hand the connection to the model provider’s own infrastructure instead, with automatic fallback to local execution if the provider doesn’t support it for that call. MCPToolset goes further and accepts a URL, a FastMCP transport, a prebuilt fastmcp.Client, an in-process FastMCP server, or a local script path — useful if you are already building your MCP server in Python with FastMCP, FastAPI-MCP, or the official SDK and want to wire it straight into a Pydantic AI agent without leaving the process.

Takeaway: for a directory built around MCP, this is the detail worth underlining — Pydantic AI is one of the few mainstream Python agent frameworks that treats “be an MCP server” as a first-class, documented capability rather than something you bolt on with a separate library.

Pydantic AI vs LangGraph and CrewAI

We already cover LangGraph, CrewAI, Letta, and AutoGen in depth in our Python agent framework comparison, and Pydantic AI deliberately sits outside that lineup — it is the type-safe entrant, built around validation rather than orchestration graphs or role play. The distinction is not cosmetic; it changes what “composing an agent” means in each framework:

If you have already read our LangGraph vs CrewAI vs Letta vs AutoGen guide and picked LangGraph for its durable, resumable state machine, nothing here should change that — Pydantic AI’s capability model is linear, not graph-based, and does not compete on that axis. If you picked CrewAI for the fastest path to a working demo, same story: Pydantic AI asks for more upfront type discipline in exchange for catching bad tool-call shapes before they hit an LLM turn. The real evidence this decision is genuinely unsettled: a 34-comment r/LangChain thread titled “LangGraph, ADK, Strands, PydanticAI: how do you actually choose in 2026?” is sitting at 26 upvotes with no consensus answer.

Takeaway: pick Pydantic AI when the agent’s output feeding into other systems matters more than the orchestration logic’s visual shape — validated output is the load-bearing feature, not a side benefit.

What we got wrong

Researching this from the outside, in the order the documentation corrected us:

• We assumed the Harness was a cookbook, not a package. The name suggested a docs section or a set of recipe snippets. It is a versioned pip/uv-installable package with its own PyPI release history, its own extras, and its own changelog, separate from pydantic-ai-slim.
• We assumed defer_loading was the default for every capability. Given how central the token-bloat problem is to the framework’s pitch, it would be reasonable to guess deferred loading is automatic. It is opt-in per capability — you set defer_loading=True explicitly, or every capability’s instructions and tools ship on every turn by default.
• We assumed “MCP support” meant client-only, like most frameworks. Every other Python agent framework we cover in our LangGraph/CrewAI/Letta/AutoGen comparison connects to MCP servers but is not one. Pydantic AI does both, and it is documented as a first-class path, not an experimental flag.

Common mistakes

• Letting an AI coding assistant write v1-shaped v2 code. Root cause: most coding models’ training data predates the June 23, 2026 release, so they confidently generate the old multi-argument Agent() pattern instead of capabilities=[...]. One developer’s workaround, shared on r/PydanticAI, was blunt about the problem:

  “Pydantic AI is great and it's even better with the newly released version 2! But unfortunately LLMs don't know anything about this new 2.0 version. Luckily, there is a way to work around that...”

• Expecting Code Mode’s sandbox to have full PyPI access. Root cause: Monty intentionally restricts the runtime — that is the security/capability tradeoff the sandbox exists to make. It surfaced as a real technical debate on Hacker News when Code Mode first shipped:

  “Why do you think python without access to the library ecosystem is a good approach? I think you will end up with small tool call subgraphs (i.e. more round trips) or having to generate substantially more utility code.”

  It is a fair tradeoff to weigh, not a bug — decide whether your use case needs arbitrary third-party packages inside the sandbox before you build around Code Mode.
• Treating every capability’s tools as always visible. Root cause: without defer_loading=True, stacking many capabilities on one agent means every tool schema and every instruction block rides along on every turn, which is exactly the token-bloat problem the flag exists to solve.
• Assuming MCP(url=...) always calls out to the model provider. Root cause: it runs locally by default in v2. native=True is opt-in, with local fallback when the provider does not support native MCP for that call — the opposite assumption of what the flag name implies at a glance.

Who it’s for, who it isn’t

Good fit if you already think in typed Python and want that discipline to extend into agent code; if you need fine control over what enters the model’s context on a given turn (defer_loading); if you are building a coding or research agent and want the Harness’s pre-built capabilities instead of reimplementing memory and guardrails; or if you need an agent that is also reachable as an MCP server, not only a client.

Look elsewhere if you want an out-of-the-box visual, resumable state machine — LangGraph’s explicit graph model fits that better, per our framework comparison. If you want the fastest possible path to a working demo with minimal type discipline, CrewAI’s role-and-task model gets there in fewer lines. And if your project leans on a large existing ecosystem of prebuilt integrations today, LangChain/LangGraph’s is larger, if only because it has been around longer.

Building the MCP servers these agents talk to is a separate decision — browse the MCP server catalog for what is already built, or see our Python MCP server framework comparison if you are building your own.

Community signal

Reaction to the underlying Code Mode capability (now folded into the Harness) has been more substantive than the usual launch-day noise, because it touches a real architectural question: how much should an LLM round-trip through the model versus execute locally. Praise leaned toward the specific problem it solves:

The skepticism in the same thread (quoted in Common Mistakes above) was not about whether Code Mode works — it was about the tradeoff of a restricted sandbox versus full library access, which is the correct question to ask before adopting it. On the MCP side, one commenter summed up why Pydantic AI treats MCP as load-bearing rather than optional: “MCP makes tools uniform” — a one-line case for why a typed framework would want a typed, uniform tool interface as its default integration surface.

The verdict

The Harness shipping two months ahead of a stable v2 core, and graduating capabilities like Code Mode back into core once they prove out, is the detail we would watch. It is a credible answer to the tension every agent framework faces — move fast on features without breaking the API surface production code depends on — and it is testable: watch which Harness capabilities move into core over the next few releases.

Frequently Asked Questions

Glossary

Sources

• Primary — launch article: Pydantic AI v2: capabilities, a leaner core, and the Harness (pydantic.dev, June 23, 2026, by Douwe Maan)
• Primary — docs: Capabilities · Harness overview · MCP overview · Pydantic AI overview
• Primary — repos: github.com/pydantic/pydantic-ai · github.com/pydantic/pydantic-ai-harness (MIT) · Code Mode implementation PR #4153 · pydantic-ai-harness on PyPI
• Community — official launch tweet: @pydantic, June 23, 2026
• Community — Hacker News, Code Mode announcement and discussion: news.ycombinator.com/item?id=46920388
• Community — Reddit: r/PydanticAI — “Migrating to Pydantic AI v2” · r/LangChain — “LangGraph, ADK, Strands, PydanticAI: how do you actually choose in 2026?”
• Internal — related guides: LangGraph vs CrewAI vs Letta vs AutoGen · FastMCP vs FastAPI-MCP vs Python SDK · Agent Client Protocol vs MCP · What is MCP?