{"slug": "pydantic-ai-v2-capabilities-the-harness-and-what-changed", "title": "Pydantic AI V2: Capabilities, the Harness, and What Changed", "summary": "Pydantic AI V2 went stable on June 23, 2026, introducing a capability-based architecture that bundles tools, lifecycle hooks, instructions, and model settings into composable units, replacing the flat tool lists of earlier agent frameworks. The update also splits the framework into a lean core and a fast-moving harness, with deferred capabilities to reduce tool explosion and a CodeMode feature for sandboxed Python execution. This redesign aims to bring FastAPI-style ergonomics to LLM development, solving tool selection and context-window problems that LangChain never addressed.", "body_md": "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.\n\n## What Capabilities Actually Are\n\nThe 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`\n\nconstructor, you compose capabilities.\n\n``` python\nfrom pydantic_ai import Agent, Thinking\n\nagent = Agent(\n    'anthropic:claude-opus-4-6',\n    instructions=\"You are helpful.\",\n    capabilities=[Thinking(effort='high')]\n)\n```\n\nThat is five lines. The `Thinking`\n\ncapability bundles extended reasoning, unified across Anthropic, OpenAI, and Google — one import, zero provider-specific boilerplate. [Pydantic AI V2](https://pydantic.dev/articles/pydantic-ai-v2) ships eight built-in capabilities with core: `Thinking`\n\n, `WebSearch`\n\n, `WebFetch`\n\n, `ImageGeneration`\n\n, `MCP`\n\n, `ToolSearch`\n\n, `PrepareTools`\n\n, and `Hooks`\n\n. Each is a named, testable unit you can reuse across agents without copy-pasting hundreds of lines of tool definitions.\n\nThis 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.\n\n## Deferred Capabilities: The Fix for Tool Explosion\n\nAgents 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.\n\nV2’s answer is deferred (on-demand) capabilities. Mark any capability `defer_loading=True`\n\nand 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.\n\n```\nrefunds = Capability(\n    id='refunds',\n    description='Use for refund eligibility and status.',\n    instructions='Always confirm order ID before refunds.',\n    defer_loading=True,\n)\n```\n\nThe model sees only the ID and a one-line description until it calls `load_capability`\n\n. 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.\n\nOne gotcha: deferred capabilities require a stable, explicit `id`\n\n. 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.\n\n## The Harness: Where the Real Power Lives\n\nThe 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](https://github.com/pydantic/pydantic-ai-harness), where it can move fast without strict backward-compatibility constraints.\n\n```\nuv add pydantic-ai-harness\nuv add \"pydantic-ai-harness[codemode]\"          # sandboxed Python execution\nuv add \"pydantic-ai-harness[dynamic-workflow]\"  # model-written fan-out scripts\n```\n\nThe harness currently tracks 40+ capabilities. The standout is **CodeMode**. It wraps your existing tools into a single `run_code`\n\ntool powered by a Monty sandbox. The model writes Python that calls multiple tools with loops, conditionals, and `asyncio.gather`\n\n— 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.\n\nOther 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](https://pydantic.dev/docs/ai/harness/overview/) tracks each item’s implementation status.\n\n## Core Got Leaner — Pydantic AI V2 Providers Are Now Opt-In\n\nPreviously, `pip install pydantic-ai`\n\npulled 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.\n\n```\nuv add pydantic-ai              # OpenAI, Anthropic, Google\nuv add \"pydantic-ai[groq]\"     # add Groq\nuv add \"pydantic-ai[mistral]\"  # add Mistral\n```\n\nThis 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](https://pydantic.dev/docs/ai/core-concepts/capabilities/) documents what ships with each install variant.\n\n## Breaking Changes and How to Migrate\n\nV2 breaks four things worth knowing before upgrading:\n\n**OpenAI model names** now target the Responses API. Use the`openai-chat:`\n\nprefix 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'`\n\n).\n\nThe 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.\n\nV2 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.\n\n## Should You Migrate Now?\n\n**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.\n\n**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.\n\n**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.\n\nPydantic 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.", "url": "https://wpnews.pro/news/pydantic-ai-v2-capabilities-the-harness-and-what-changed", "canonical_source": "https://byteiota.com/pydantic-ai-v2-capabilities-harness-stable/", "published_at": "2026-07-10 05:09:22+00:00", "updated_at": "2026-07-10 05:13:04.891056+00:00", "lang": "en", "topics": ["artificial-intelligence", "developer-tools", "ai-agents", "ai-tools", "ai-products"], "entities": ["Pydantic", "LangChain", "Anthropic", "OpenAI", "Google", "FastAPI", "Monty", "Pydantic AI V2"], "alternates": {"html": "https://wpnews.pro/news/pydantic-ai-v2-capabilities-the-harness-and-what-changed", "markdown": "https://wpnews.pro/news/pydantic-ai-v2-capabilities-the-harness-and-what-changed.md", "text": "https://wpnews.pro/news/pydantic-ai-v2-capabilities-the-harness-and-what-changed.txt", "jsonld": "https://wpnews.pro/news/pydantic-ai-v2-capabilities-the-harness-and-what-changed.jsonld"}}