Pydantic AI 2.0: How capabilities change AI agent design

Pydantic AI 2.0 is a major shift in how you build production agents. Instead of wiring instructions, tools, hooks, and guardrails into one messy constructor, you package each responsibility as a reusable capability. That makes agents easier to compose, easier to maintain, and easier to share across

MMichael SwindellJuly 19, 202616 min read

Pydantic AI 2.0 is a major shift in how you build production agents. Instead of wiring instructions, tools, hooks, and guardrails into one messy constructor, you package each responsibility as a reusable capability. That makes agents easier to compose, easier to maintain, and easier to share across projects. A capability can include model settings, lifecycle hooks, MCP servers, and tool access, then be dropped into multiple agents without rewriting it. For teams building serious agent workflows, this design moves closer to a real control plane, similar in spirit to agent-first development platforms that organize work around reusable units, verification, and shared context.

At a Glance

Pydantic AI 2.0 replaces scattered agent wiring with composable capabilities.

Core idea: A capability bundles instructions, tools, hooks, and settings into one reusable unit.
Why it matters: You can share the same behavior across multiple agents without duplicating code.
Practical gain: Progressive disclosure helps agents load only the capabilities needed for the current task.
Best fit: Teams shipping production agents that need structure, control, and reuse.
Trade-off: Coding agent SDKs may still feel faster for personal or lightweight workflows.

What is a capability in Pydantic AI 2.0?

A capability is a self-contained building block for an agent. It groups the agent behavior needed for one responsibility, including instructions, tools, hooks, and settings, so you can compose agents from reusable parts instead of one large, tightly coupled definition.

The main design change in Pydantic AI 2.0 is conceptual simplicity. Instead of thinking about an agent as a long list of prompts, tools, model knobs, and guardrails, you think about it as a set of capabilities.

Each capability represents a responsibility. For example, an agent might need to search a knowledge base, escalate a support case, perform reasoning, or execute code in a sandbox. In 2.0, each of those concerns can live in its own unit.

This matters because AI agents usually grow messy over time. The first version often starts small, then picks up extra tools, safety checks, and special instructions. Eventually, a once-simple agent becomes hard to understand and even harder to reuse. Capabilities are meant to stop that drift.

Why is this better than the old way of defining agents?

The older pattern worked, but it encouraged agents to become unstructured bundles of behavior. Capabilities improve that by introducing organization and composability, so the same logic can be reused across agents without redefining tools, instructions, and hooks from scratch.

In a typical 1.0 style setup, you could still define tools, prompts, and model settings clearly enough. The problem was not raw functionality. The problem was packaging.

If two agents needed the same knowledge base lookup behavior, you often had to recreate that logic manually. If you improved one version later, the other agent would not automatically benefit. Over time, this creates drift between agents that should behave consistently.

With capabilities, the reusable unit becomes the default unit. That makes sharing behavior much cleaner.

A good mental model is this:

Old model: An agent is one large definition with many embedded parts.
New model: An agent is a composition of smaller, purpose-built blocks.

This is especially useful in organizations with multiple internal agents. Once a capability improves, every agent using it can improve at the same time.

How do capabilities relate to MCP servers, hooks, and guardrails?

Capabilities sit above individual primitives like MCP servers, hooks, and guardrails. Those pieces still matter, but now they can be grouped together under one reusable interface that captures a complete responsibility rather than a loose collection of agent parts.

This is one of the most useful parts of the 2.0 design. Capabilities do not replace existing patterns. They organize them.

MCP, short for Model Context Protocol, is already a packaging idea for tools that agents can access. In that sense, an MCP server can be part of a capability. But a capability can include more than tool access.

It can also include:

Instructions: How the agent should behave for that responsibility
Tools: Functions or external systems it can call
Hooks: Deterministic actions before or after certain events
Guardrails: Constraints that shape safe or expected behavior
Model settings: Parameters tailored to that responsibility

That broader packaging is the point. A capability is not just an arm for the agent. It is a fuller operating unit.

For teams coordinating many coding agents, this kind of bundling maps well to how agent-first systems work in practice. One way to handle this at scale is through a shared control layer such as Levr’s project, testing, and observability features, where reusable agent responsibilities can be tracked alongside verification gates and project context.

How does capability reuse work in real agent design?

Capability reuse works by separating responsibilities into modules that can be attached to different agents unchanged. If two agents both need the same knowledge base access, they can share one capability while differing on other responsibilities like escalation or execution.

A support workflow makes this concrete.

Imagine one support agent that can:

Search a knowledge base
Reason about the answer
Escalate certain cases to a human

Now imagine a second agent used only in an FAQ widget. It still needs the knowledge base behavior, but not escalation.

Without capabilities, both agents can end up with duplicate logic. With capabilities, the knowledge base unit can be reused directly. The support agent gets the knowledge base capability plus the escalation capability. The FAQ agent only gets the knowledge base capability.

That means:

You write shared behavior once.
You improve shared behavior once.
Every dependent agent stays aligned.

This is one of the strongest arguments for Pydantic AI 2.0 as a production framework rather than just a prototyping tool.

What is progressive disclosure, and why does it matter?

Progressive disclosure lets an agent know which capabilities exist without fully loading all of their instructions immediately. The agent can inspect a lightweight catalog first, then pull in the full detail only when a capability is actually needed for the task.

This matters for both cost and focus.

If an agent has dozens of capabilities, loading every instruction block into every request would waste tokens and slow execution. Progressive disclosure helps avoid that. The agent only expands the capabilities relevant to the current prompt.

That means an agent can remain broad in what it can do without becoming bloated in every single interaction.

For example:

A customer asks whether a product integrates with Slack.
The agent uses reasoning and knowledge base search.
It does not load the escalation capability because escalation is irrelevant.

Then a different question arrives:

A customer says they were charged twice.
The agent now loads escalation because the task requires it.

This is similar to how skills work in some coding agent environments. The catalog tells the model what is available, but the expensive details stay dormant until needed.

That design fits a broader industry shift toward context efficiency. It also lines up with the practical concerns developers report around AI reliability and usefulness in day-to-day work, as seen in the Stack Overflow Developer Survey 2024.

Reusable agent behavior is only half the problem.

Once agents share capabilities, teams still need a way to coordinate tasks, tests, and approvals across runs. That is where an agent-first control plane becomes useful.

See how teams structure shared agent workflows

When should you use Pydantic AI instead of a coding agent SDK?

Pydantic AI makes the most sense when you are building production agents for other users or shared team workflows. Coding agent SDKs can be simpler for personal automations, but a framework becomes more useful when you need structure, reuse, and long-term maintainability.

This is not a zero-sum choice.

Coding agent SDKs are attractive because they make it very easy to get started. For personal workflows, that is often enough. If you are building something mainly for yourself, speed and convenience may matter more than framework rigor.

But frameworks still have clear strengths:

More explicit structure.
Cleaner reuse patterns.
Better fit for production systems.
Clearer control over tools, hooks, and settings.

The transcript material also notes a trade-off. SDK-based approaches may be slower and more token-heavy, while frameworks like Pydantic AI can offer a tighter production shape for agents that need discipline.

This matches broader adoption trends. GitHub’s Octoverse reporting has shown how mainstream AI-assisted development has become, but mainstream use does not remove the need for production architecture. As agents move from individual helper tools into shared systems, structure matters more.

How do the lean core and harness fit into the new model?

Pydantic AI 2.0 separates widely useful built-in capabilities from less universal ones. The lean core includes capabilities considered broadly essential, while the harness supports additional capabilities that are useful but not necessary for most agents.

This is a smart product design decision.

Frameworks often become heavy because they try to ship every feature directly in the center. Pydantic AI appears to be avoiding that by keeping the most common capabilities easy to access while leaving room for more specialized extensions.

The split works like this:

Lean core: Core capabilities many agents are likely to need, such as reasoning or web-related support
Harness: Additional supported capabilities that are valuable but not universal, such as code execution in a sandbox

That keeps the core lightweight while still giving developers access to richer building blocks when needed.

A code-mode style capability is a good example. It can be important for many agents, but not for most support or retrieval agents. Treating it as part of a surrounding harness rather than the center of the framework keeps the abstraction cleaner.

How do you design good capabilities without creating new sprawl?

Good capabilities map to clear responsibilities, not vague themes. If a capability is too broad, it becomes another monolith. If it is too narrow, you create fragmentation. The sweet spot is a reusable responsibility with a clear tool set, policy, and execution boundary.

A few practical guidelines help:

Start from responsibilities, not features

Think in terms like knowledge retrieval, billing escalation, sandboxed code execution, or document classification. These are stable responsibilities.

Bundle only what belongs together

If a hook or guardrail applies only to one responsibility, keep it there. Do not stuff unrelated rules into a general capability.

Prefer reuse over convenience

If two agents need the same behavior, that is a sign the logic should likely live in one shared capability.

Keep descriptions crisp

Progressive disclosure depends on the agent understanding when to invoke a capability. If the description is vague, the model may load the wrong one or skip the right one.

Review capability boundaries over time

As agents evolve, some capabilities need splitting and others need merging. Reuse is the goal, not maximal granularity.

Teams using a shared workflow layer often apply similar principles at the project level. One way to do this in practice is the four-step pattern shown in Levr’s agentic workflow: define intent, let agents pick up tasks, run automated verification, then require human review.

What mistakes should teams avoid when adopting capability-based agents?

The biggest mistakes are overpacking capabilities, duplicating similar capabilities, and treating composability as a substitute for governance. Capabilities improve structure, but they do not automatically solve testing, observability, or human approval.

Common pitfalls include:

Creating giant capabilities: If one capability contains too many unrelated responsibilities, you lose the benefits of composability.
Copying rather than reusing: Teams sometimes create slightly different versions of the same capability instead of maintaining one shared unit.
Ignoring invocation quality: Progressive disclosure works only if capability descriptions and boundaries are clear.
Skipping verification: Reusable logic can still produce bad outcomes if outputs are not tested or reviewed.
Assuming all agents need the same stack: Not every agent needs code execution, escalation, web search, or reasoning.

This last point matters. The capability model encourages flexibility, but you still need discipline in how capabilities are assigned.

How do you manage capability-based agents across a team?

Managing capability-based agents across a team means treating capabilities like shared infrastructure. You need versioning, visibility, testing, and a clear path from agent intent to verified output so reused components do not become hidden sources of inconsistency.

Once multiple agents share capabilities, agent management starts to look more like software platform management.

Questions teams should answer:

Who owns each capability?
How are changes tested before rollout?
Which agents depend on which capabilities?
What human review gate exists for sensitive actions?

That is where agent orchestration tools become more relevant than a raw framework alone. For example, Levr focuses on multi-agent coordination with shared memory, routing, and agent-to-agent communication, which becomes useful when capabilities are only one layer of a larger agent network.

The framework defines the agent. The control plane defines how agent work is tracked, verified, and improved over time.

Technical Deep Dive FAQ

What is Pydantic AI 2.0?

Pydantic AI 2.0 is an agent framework update centered on a new primary abstraction called the capability. Instead of defining an agent as a loose bundle of prompts, tools, hooks, and settings, you define reusable units that package those concerns together. The result is a more composable way to build production agents. It is especially useful when you want to share behavior across multiple agents or keep agent architecture organized as systems grow.

What is an AI agent capability?

An AI agent capability is a self-contained unit of agent behavior. It can include instructions, tools, model settings, lifecycle hooks, guardrails, and related resources needed for a specific responsibility. Rather than thinking of an agent as one giant definition, you think of it as a collection of capabilities. This makes it easier to reuse logic, update shared behavior, and avoid duplicating the same setup across different agents.

How are capabilities different from tools?

Tools are only one part of a capability. A tool gives the agent a function or external action it can perform, such as searching a database or creating a ticket. A capability includes those tools, but also the instructions that explain when and how to use them, the settings that shape model behavior, and any hooks or guardrails surrounding execution. In short, a capability is a larger packaging layer that can define a complete responsibility.

How do capabilities compare with MCP servers?

MCP servers package tool access for agents, which makes them a good fit inside a capability. But a capability is broader than an MCP server because it can also include prompts, hooks, model settings, and behavioral boundaries. It helps to think of MCP as one possible ingredient in a capability rather than an equivalent concept. If an agent needs a specific external tool interface, that MCP connection can be wrapped together with the logic that governs how it should be used.

What is progressive disclosure in agent frameworks?

Progressive disclosure means the agent can see a catalog of available capabilities without loading all their full instructions at once. The model first decides which capability seems relevant, then loads the complete information only for the ones it needs. This reduces token overhead, improves focus, and helps large agents scale better. Instead of forcing every request to carry every behavior definition, the system keeps most detail dormant until it is actually useful.

Can the same capability be reused across multiple agents?

Yes. Reuse is one of the main advantages of the new design. If several agents need the same responsibility, such as knowledge base search, that capability can be attached to each of them without changing the underlying logic. This is useful because updates to the capability propagate to every agent that depends on it. It also reduces inconsistency across agents, since the same behavior does not need to be rewritten by hand in multiple places.

Are coding agent SDKs still useful if Pydantic AI 2.0 exists?

Yes. Coding agent SDKs still make sense for lighter or more personal workflows where speed of setup matters more than long-term framework structure. They can be a good fit when you are building for yourself or experimenting quickly. Pydantic AI becomes more compelling when you need stronger composability, more explicit production architecture, and shared behavior across multiple agents. The right choice depends on whether convenience or maintainability is the bigger concern for your use case.

What kinds of capabilities should you create first?

The best starting capabilities are stable responsibilities that several workflows may need. Examples include retrieval from a knowledge base, escalation to a human operator, code execution in a sandbox, or a reasoning layer used before a critical action. Avoid designing around vague categories like “support stuff” or “admin tasks.” Capabilities work best when the responsibility is concrete, the boundaries are clear, and the behavior is likely to be reused in more than one place.

Does capability composition solve observability and governance too?

No. Capability composition improves code structure and agent reuse, but it does not by itself provide team-level observability, testing policy, or approval workflows. Those concerns still need supporting systems. In practice, teams often pair a framework with workflow management, logging, test automation, and human review gates. That is why the framework layer and the control-plane layer are separate concerns. One defines agent behavior. The other defines how that behavior is monitored, approved, and improved over time.

How does this model help production agent systems?

Production agent systems need repeatability, maintainability, and safe reuse. Capabilities help because they make agent behavior modular instead of tangled. Shared responsibilities can be updated centrally. Agents can stay narrower and more intentional. Progressive disclosure can control context bloat. All of that supports production quality, especially when combined with testing and review. It does not remove the need for operational discipline, but it gives teams a much cleaner way to organize the agent logic they intend to ship.

Key Takeaways

Pydantic AI 2.0 matters because it changes the unit of agent design from a messy definition to a reusable responsibility.

Capability-based design makes production agents easier to build, share, and evolve.

Main shift: Capabilities bundle instructions, tools, hooks, and settings into one composable primitive.
Main benefit: Shared responsibilities can be reused across multiple agents without duplication.
Main performance win: Progressive disclosure keeps large agent stacks from loading unnecessary context.
Main caution: Better composition does not replace the need for testing, observability, and review.

If you are building agents for real users rather than one-off experiments, this is the kind of simplification that actually improves system design.