Pydantic AI v2 Capabilities: The Complete Guide to Composable Agent Architecture (2026)

On June 23, 2026, the Pydantic team shipped Pydantic AI v2 — and with it, one architectural primitive that rewrites how production AI agents are built. Not a new model wrapper. Not another chatbot framework. A capability: a single composable unit that bundles an agent’s tools, lifecycle hooks, instructions, and model settings into something you snap together like building blocks.

If you’ve spent any time wiring up agentic systems with LangGraph, CrewAI, or AG2, you know the pain: tools configured here, system prompts threaded there, retry logic bolted on somewhere else, guardrails in yet another layer. Pydantic AI v2 collapses all of that into one concept. And because it’s built by the team behind Pydantic — the validation library that underpins FastAPI and virtually every serious Python ML pipeline — the type safety isn’t aspirational. It’s enforced.

This guide walks you through everything an Agentic AI Architect needs to know: what capabilities actually are, how the architecture works, how they compare to extension mechanisms in competing frameworks, and how to build production agents with them. We’ll use real code throughout, sourced directly from the official documentation.

Table of Contents

• What Are Capabilities and Why Do They Matter?
• The Architecture: How Capabilities Compose
• Built-in Capabilities Reference
• Provider-Adaptive Tools: One API, Every Model
• The Pydantic AI Harness: Batteries Sold Separately
• Agent Specs: Declarative Agents in YAML/JSON
• Code Mode: The Capability That Changes Everything
• On-Demand Loading: Keep Your Prompt Lean
• Building Custom Capabilities
• How Pydantic AI v2 Compares to LangGraph, CrewAI, and AG2
• Migrating from v1 to v2
• Production Patterns and Best Practices
• FAQs
• Key Takeaways
• References

What Are Capabilities and Why Do They Matter?

Before v2, building a Pydantic AI agent meant threading configuration through multiple constructor arguments: instructions here, model_settings there, a toolset somewhere else, a history_processor on yet another parameter. Each concern lived in its own argument, and composing multiple extensions — say, a memory system and a guardrail and instrumentation — meant carefully interleaving parameters that didn’t know about each other.

A capability solves this by bundling related behavior into a single, self-contained unit. According to the official documentation, a capability can provide any combination of:

• Tools — via toolsets or native tools
• Lifecycle hooks — intercept and modify model requests, tool calls, and the overall run
• Instructions — static or dynamic instruction additions
• Model settings — static or per-step model configuration
• Models — static or adaptive model selection

This makes the capability the primary extension point for the entire framework. Whether you’re building a memory system, a cost tracker, a guardrail, an approval workflow, or an MCP integration, it goes through this single abstraction.

Here’s what a minimal agent with capabilities looks like in practice:

from pydantic_ai import Agent
from pydantic_ai.capabilities import Thinking, WebSearch

agent = Agent(
    'anthropic:claude-opus-4-6',
    instructions='You are a research assistant. Be thorough and cite sources.',
    capabilities=[
        Thinking(effort='high'),
        WebSearch(local='duckduckgo'),
    ],
)

Two lines in the capabilities list give this agent extended thinking and web search — behavior that in other frameworks would require separate configuration files, middleware chains, or monkey-patched tool registries.

The Architecture: How Capabilities Compose

The design philosophy behind capabilities mirrors what made Pydantic itself successful: explicit over implicit, composable over monolithic, type-safe over stringly-typed.

Capabilities compose through a flat list on the Agent constructor. There’s no inheritance hierarchy to navigate, no middleware pipeline ordering to debug. Each capability operates independently, and the framework merges their contributions:

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'),
        CodeMode(),
        WebSearch(),
        ToolSearch(),
        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,
        ),
    ],
)

That last entry — the inline Capability — shows a richer shape. It bundles an ID, a description, instructions, and a toolset (here an MCP server) into a single declaration. Marked defer_loading=True, it stays collapsed to a one-line catalog entry until the model decides to load it. The model sees only the description in a compact list, then pulls the full bundle — instructions and tools together — in a single step when needed.

The Hooks System

The real power of capabilities comes from lifecycle hooks — the mechanism that lets a capability read and rewrite what the model sees on every step. This includes the model’s tools, its instructions, and its message history. As the v2 announcement puts it: “Code mode and tool search are built on exactly the same public hooks your own capabilities would use, so the batteries we ship double as worked examples.”

This is architecturally significant. It means the framework’s own advanced features don’t use privileged internal APIs — they use the same extension surface available to every developer. If Pydantic’s CodeMode capability can rewrite tool calls into Python code blocks using hooks, your custom capability can use those same hooks to implement guardrails, token budgets, or adaptive context management.

Built-in Capabilities Reference

Pydantic AI v2 ships with over 20 built-in capabilities. Here are the ones most relevant to production agent builders:

The “Spec” column indicates whether the capability can be serialized into an Agent Spec file (YAML/JSON). Capabilities that take non-serializable arguments — callables, toolset objects — can only be used in Python code.

Provider-Adaptive Tools: One API, Every Model

One of the most elegant design decisions in Pydantic AI v2 is the provider-adaptive tool pattern. Five built-in capabilities — WebSearch, WebFetch, ImageGeneration, XSearch, and MCP — each cover a single concern with two implementations:

• Native — the model provider handles it server-side (e.g., Anthropic’s built-in web search runs on their infrastructure)
• Local — your Python process does the work (e.g., calling DuckDuckGo directly)

This means you write WebSearch() once, and your agent automatically uses the native implementation when available and falls back to a local implementation when it’s not. Switch from Claude to GPT and the search still works — just via a different path.

from pydantic_ai import Agent
from pydantic_ai.capabilities import MCP, ImageGeneration, WebFetch, WebSearch, XSearch

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[
        WebSearch(local='duckduckgo'),        # Native when supported; DuckDuckGo fallback
        WebFetch(local=True),                 # Native when supported; markdownify fallback
        ImageGeneration(fallback_model='openai-responses:gpt-5.4'),  # Subagent fallback
        XSearch(fallback_model='xai:grok-4.3'),                     # xAI native; explicit fallback
        MCP('https://mcp.example.com/api'),    # Runs locally by default
    ],
)

Notice the asymmetry: MCP defaults to local (because MCP connections carry credentials), while the others default to native. This is a security-conscious default that most framework designers would miss.

For RPA and automation architects already working with the Model Context Protocol (MCP), this native integration is significant. You can connect any MCP server as a capability — with automatic transport detection from a URL — and the agent handles the lifecycle.

The Pydantic AI Harness: Batteries Sold Separately

Pydantic AI v2 made a deliberate architectural split: the core framework stays small and stable, while the Pydantic AI Harness ships as a separate pydantic-ai-harness package with higher-level capabilities that iterate faster.

The Harness currently includes capabilities for:

• Code Mode — wraps tools into a single run_code call (more on this below)
• Memory — persistent agent memory across conversations
• Guardrails — content filtering and safety checks
• File System — sandboxed file access for agents
• Shell — sandboxed command execution
• Repo Context — code repository understanding
• Browser Use — web browser automation
• Compaction — context window management via server-side compaction (with dedicated OpenAI and Anthropic capabilities)
• Subagents — multi-agent coordination patterns
• Planning — structured planning capabilities
• Dynamic Workflow — runtime workflow construction
• Spend — cost tracking and budget management

The split is deliberate. As the official announcement explains: “Core stays small and stable, shipping the loop, the providers, the capability and hooks API, and only the capabilities that need deep provider support or are fundamental to every agent. Everything else lives in the Harness, where it can move fast, and a capability can graduate into core once it proves broadly essential.”

Third-party capabilities are already emerging. VStorm and other community contributors ship capabilities that Pydantic endorses and links to from the Harness, with plans to upstream the most mature ones.

Agent Specs: Declarative Agents in YAML/JSON

Because capabilities are serializable, Pydantic AI v2 introduces Agent Specs — the ability to define an entire agent in YAML or JSON, without writing Python code. This is a significant shift for enterprise teams where non-developers (business analysts, solution architects) need to configure agent behavior.

An Agent Spec file can define:

• The model to use
• System instructions
• Capabilities (any that are spec-compatible)
• Model settings
• Output schema

The generated JSON Schema file enables autocompletion and validation in editors that support the YAML Language Server protocol. For teams using RPA-to-agentic-AI transition strategies, this declarative approach maps well to the configuration-driven mindset that RPA platforms like UiPath and Automation Anywhere already use.

Code Mode: The Capability That Changes Everything

Of all the Harness capabilities, Code Mode deserves special attention because it fundamentally changes the agent execution model.

In a standard agentic loop, each tool call requires a full round-trip to the model: the agent decides to call tool A, sends the request, waits for the response, processes the result, then decides to call tool B. For a workflow that requires ten tool calls, that’s ten round-trips — each adding latency and token cost.

Code Mode changes this by wrapping 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 for iteration, and conditionals for branching — inside a single sandboxed execution. The code runs via Monty, Pydantic’s safe Python subset.

This means an agent that previously needed ten sequential round-trips to process ten invoices can now write a parallel processing script in one round-trip. For RPA architects designing high-throughput agentic workflows, this is a direct answer to the “agent latency tax” problem.

On-Demand Loading: Keep Your Prompt Lean

Production agents often have access to dozens or hundreds of tools — but cramming all of them into the system prompt on every run wastes context window space and confuses the model. Pydantic AI v2 solves this with on-demand capabilities.

When you set defer_loading=True on a capability, it stays collapsed to a one-line description in a compact catalog. The model sees a list of available capabilities and loads the full bundle — instructions, tools, and configuration — only when it decides it needs them.

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

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

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

This is conceptually similar to how Claude Code’s own tool search works — and that’s not a coincidence. ToolSearch is itself a built-in capability that uses the same on-demand pattern to let agents discover tools from large registries without loading everything upfront.

Building Custom Capabilities

There are two paths to creating custom capabilities, depending on complexity:

The Declarative Path: Capability

For capabilities that bundle instructions, tools, and toolsets without needing lifecycle hooks:

from pydantic_ai.capabilities import Capability

invoice_processing = Capability(
    id='invoice-processing',
    description='Extract and validate invoice data from documents.',
    instructions='Always validate amounts against PO before approving.',
)

@invoice_processing.tool_plain
def extract_invoice(document_url: str) -> dict:
    """Extract structured data from an invoice document."""
    # Your extraction logic here
    return {"vendor": "...", "amount": 0.0, "po_number": "..."}

@invoice_processing.tool_plain
def validate_against_po(invoice_data: dict) -> str:
    """Cross-reference invoice against purchase order."""
    return "Validated: amounts match within tolerance."

The Subclass Path: AbstractCapability

For capabilities that need lifecycle hooks, model settings, or native tools, subclass AbstractCapability. This is the path for building guardrails, cost trackers, approval workflows, or any behavior that needs to intercept the agent loop:

from pydantic_ai.capabilities import AbstractCapability

class CostGuard(AbstractCapability):
    """Tracks token usage and stops the agent if budget is exceeded."""
    
    max_tokens: int = 100_000
    current_tokens: int = 0
    
    def on_model_response(self, response):
        self.current_tokens += response.usage.total_tokens
        if self.current_tokens > self.max_tokens:
            raise BudgetExceededError(
                f"Token budget {self.max_tokens} exceeded"
            )

The key insight: both paths produce objects that go into the same capabilities=[] list. The agent doesn’t care whether a capability was built declaratively or via subclass — it composes the same way.

How Pydantic AI v2 Compares to LangGraph, CrewAI, and AG2

Understanding where Pydantic AI v2 fits requires comparing its design decisions to the other major Python agent frameworks. Here’s a decision table for architects evaluating their options:

When to choose Pydantic AI v2: You’re building production Python agents, you value type safety, you want provider-agnostic code that works across OpenAI/Anthropic/Google/local models without rewiring, and your team already uses Pydantic or FastAPI. The capability model is particularly strong when you need to compose multiple concerns (memory + guardrails + instrumentation + custom tools) without them stepping on each other.

When to choose LangGraph: Your workflow is inherently graph-shaped with complex branching and state machines, or you’re deeply invested in the LangChain ecosystem (LangSmith, LangServe). For complex multi-agent orchestration patterns, LangGraph’s explicit graph model can be more readable than imperative agent code.

When to choose CrewAI: You want the fastest path from idea to working multi-agent prototype, your team prefers high-level abstractions over low-level control, and you’re comfortable with less type safety in exchange for simpler code.

When to choose AG2: You need event-driven, streaming-first architecture with concurrent agent support, especially for real-time applications. AG2’s beta redesign with MemoryStream addresses multi-user scenarios that other frameworks handle awkwardly.

Migrating from v1 to v2

The Pydantic team designed the v1-to-v2 migration to be as smooth as possible. The recommended path:

1. Upgrade to the latest v1 first and clear every deprecation warning. This catches most breaking changes before you ever touch v2.
2. Run uv add pydantic-ai to get v2.
3. Check these behavior changes that a deprecation warning couldn’t catch:
   • openai: model names now use the Responses API; use openai-chat: to stay on Chat Completions
   • WebSearch and WebFetch are native by default
   • MCP(url=...) runs locally by default
   • Instrumentation defaults to version 5 with aggregated token-usage attributes
   • Function tools requested alongside a successful output tool now run (end_strategy='graceful')

One policy change worth noting: the no-breaking-changes window between major versions has moved from six months to three. The Pydantic team’s reasoning is straightforward — the agentic AI field moves fast enough that committing further out means committing to decisions that don’t fit the world three months from now. Deprecations still always land before removals.

Production Patterns and Best Practices

Pattern 1: Layered Capabilities for Enterprise Agents

In production, capabilities naturally layer into three tiers:

1. Infrastructure capabilities (always-on): Instrumentation, Thinking, cost tracking
2. Domain capabilities (loaded on demand): CRM tools, ERP connectors, document processing
3. Guardrail capabilities (always-on): PII detection, content filtering, budget enforcement

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[
        # Infrastructure (always-on)
        Instrumentation(),
        Thinking(effort='medium'),
        CostGuard(max_tokens=200_000),
        
        # Domain (on-demand)
        Capability(id='crm', description='Salesforce queries', 
                   toolset=crm_tools, defer_loading=True),
        Capability(id='erp', description='SAP data lookups', 
                   toolset=erp_tools, defer_loading=True),
        
        # Guardrails (always-on)
        PIIFilter(),
        OutputValidator(),
    ],
)

Pattern 2: Durable Execution for Long-Running Workflows

For agentic workflows that run for minutes or hours (common in RPA scenarios), Pydantic AI v2 is integrating durable execution as capabilities. TemporalDurability, DBOSDurability, and PrefectDurability ship in the pydantic_ai.durable_exec subpackages, with support for Restate, Kitaru, and Apache Airflow as well.

This is particularly relevant for organizations transitioning from traditional RPA to agentic automation. Traditional RPA workflows in UiPath or Automation Anywhere run deterministically and persistently — if the machine reboots, the workflow picks up where it left off. Agentic workflows need the same guarantees, and durable execution capabilities provide exactly that.

Pattern 3: Multi-Agent Coordination via Subagents

The Harness includes a Subagents capability for structured multi-agent coordination. Combined with the Planning capability, this enables patterns like:

• A supervisor agent that decomposes tasks and delegates to specialist agents
• Each specialist agent with its own capabilities (domain tools, guardrails)
• The supervisor aggregating results and making final decisions

This maps directly to the multi-agent orchestration patterns that platforms like Salesforce Agentforce and Microsoft Copilot Studio are implementing — but with the flexibility and transparency of open-source code.

Frequently Asked Questions

Can Pydantic AI v2 replace LangChain for production AI agents?

For new projects, yes — Pydantic AI v2 covers the agent loop, tool management, provider abstraction, and observability that most production agents need, with stronger type safety than LangChain. For existing LangChain projects, the migration cost depends on how deeply you’ve invested in LangChain-specific abstractions (chains, memory classes, output parsers). Pydantic AI’s MCP capability means you can incrementally adopt it by exposing existing tools as MCP servers.

How does Pydantic AI handle multi-model agents (e.g., Claude for reasoning, GPT for code)?

The SelectModel capability lets you pick a model per step using a callable — so your agent can route reasoning tasks to Claude and code generation to GPT within the same run. The provider-adaptive tool pattern means capabilities like WebSearch automatically adapt to whichever model is active.

Is Pydantic AI v2 production-ready for enterprise use?

Yes. The framework is built by Pydantic Services Inc. (the company behind the validation library used by most Python ML/AI infrastructure), ships with commercial-grade observability via Logfire, supports durable execution for crash-safe long-running workflows, and follows a formal version policy with no breaking changes within major versions.

What’s the relationship between Pydantic AI capabilities and MCP?

MCP (Model Context Protocol) is supported as a first-class built-in capability. Any MCP server can be connected as a capability via MCP('url') or MCPToolset. The on-demand loading feature means MCP tool registries can be discovered at runtime without upfront prompt loading. This makes Pydantic AI one of the most MCP-native agent frameworks available.

How do capabilities compare to LangGraph’s “tools” or CrewAI’s “tasks”?

Capabilities are broader. A LangGraph tool is a callable; a CrewAI task is a unit of work. A Pydantic AI capability can include tools plus instructions plus hooks plus model settings. The closest analogy in other ecosystems would be a LangChain “toolkit” combined with middleware — but as a single, type-safe, composable unit.

Key Takeaways

• One primitive to rule the loop: Pydantic AI v2’s capability bundles tools, hooks, instructions, and model settings into a single composable unit — eliminating the scattered configuration that plagues other frameworks.
• Provider-adaptive by default: Write WebSearch() once and it works across Claude, GPT, Gemini, and local models — switching between native and local implementations automatically.
• On-demand loading keeps agents lean: With defer_loading=True, capabilities stay out of the prompt until the model needs them — critical for agents with dozens or hundreds of available tools.
• Code Mode collapses round-trips: Instead of ten sequential tool calls, the model writes a single Python script that orchestrates all ten in parallel — a direct answer to agent latency.
• The Harness/core split is deliberate: Core stays stable (three-month major version cadence), while the Harness iterates fast with memory, guardrails, and execution capabilities.
• Agent Specs enable no-code agent configuration: Spec-compatible capabilities can be defined entirely in YAML/JSON, bridging the gap between developers and business users.
• Durable execution built in: Temporal, DBOS, Prefect, Restate, and Airflow integrations ship as capabilities, giving agentic workflows the same crash-safe guarantees as traditional RPA.
• MCP is a first-class citizen: Any MCP server connects as a capability with automatic transport detection — making Pydantic AI one of the most MCP-native frameworks in the ecosystem.
• ~19k GitHub stars and growing: Backed by Pydantic Services Inc. with commercial support via Logfire, this is not a weekend project — it’s production infrastructure.

References

1. Douwe Maan, “Pydantic AI v2: capable agentic loops,” Pydantic Blog, June 23, 2026. https://pydantic.dev/articles/pydantic-ai-v2
2. “Capabilities Overview,” Pydantic AI Documentation, 2026. https://pydantic.dev/docs/ai/capabilities/overview/
3. “Pydantic AI Harness,” Pydantic Documentation, 2026. https://pydantic.dev/docs/ai/harness/
4. pydantic/pydantic-ai GitHub Repository. https://github.com/pydantic/pydantic-ai
5. pydantic/pydantic-ai-harness GitHub Repository. https://github.com/pydantic/pydantic-ai-harness
6. “Pydantic AI v2 Ships a Single Primitive That Rebuilds How Agents Work,” AlphaSignal, 2026. https://alphasignal.ai/news/pydantic-ai-v2-ships-a-single-primitive-that-rebuilds-how-agents-work
7. “What Is Pydantic AI 2.0? The Capability Primitive That Changes How You Build Agents,” MindStudio, 2026. https://www.mindstudio.ai/blog/what-is-pydantic-ai-2-0-capability-primitive
8. Kacper Wlodarczyk, “Pydantic AI Capabilities, Hooks & Agent Specs — What Changed and How Our Libraries Migrated,” Medium, 2026. https://medium.com/@kacperwlodarczyk/pydantic-ai-capabilities-hooks-agent-specs-migration-guide-with-real-code-d0d986eb2b91
9. “Agent Specs,” Pydantic AI Documentation, 2026. https://pydantic.dev/docs/ai/core-concepts/agent-spec/
10. “Durable Execution Overview,” Pydantic AI Documentation, 2026. https://pydantic.dev/docs/ai/capabilities/durable_execution/overview/

Published on rpabotsworld.com — practical guides for Agentic AI Architects, Generative AI Architects, and RPA professionals building the next generation of intelligent automation.