Pydantic AI 2.0 shifts to capabilities as its core primitive for agents

Capabilities become the core building block

A crash-course tutorial published on dev.to walks through agent development with Pydantic AI 2.0, and the change it leads with is architectural. According to the post, version 2 has fully reorganised the framework around capabilities, making them the fundamental unit from which agents are assembled. Rather than configuring each agent as an ad hoc bundle of prompts, tools and settings, developers now work with capability units that can be used as-is, composed together, or written from scratch.

Capabilities are also meant to be reused rather than rebuilt for every project. The tutorial demonstrates how to consume existing ones, how to author your own, and walks through two taken from the Pydantic AI harness, which the author describes as an official set of pre-built capabilities maintained by Pydantic. A companion Google Colab notebook ships alongside the video so viewers can follow along with the code.

The rest of the agent toolkit

Capabilities do not replace the other components of an agent, and the tutorial covers those as well. Per the post, the curriculum includes:

• Instructions, including dynamic instructions
• Tools, the functions a model can call during a run
• Dependencies
• Structured output
• MCP support, referring to the Model Context Protocol
• Observability with Logfire

By the end, the author says, viewers should be able to put together agents of their own on top of these pieces.

The security note deserves the most attention

The part of the post with the widest applicability is a short warning about secrets. The author cautions that everything placed in a system prompt or in an agent's instructions is transmitted to whichever inference provider backs the model — and if the agent is wired to an observability tool such as Logfire, its full context is also sent to that third-party service. API keys and other sensitive values therefore have no place in prompts.

The recommended fix is structural rather than cautionary. Whenever you feel the urge to embed a secret in a prompt, treat that urge as a sign the logic belongs in a tool function instead. Tools execute on your own server, so they can load secrets from environment variables directly. The one rule that must hold, the post notes, is that the tool never hands those values back to the model.

Why it matters

A framework's core primitive shapes how everyone builds with it. Positioning capabilities at the centre of Pydantic AI 2.0 pushes agent development toward composability — assembling behaviour from reusable units, either written in-house or pulled from the official harness — rather than repeating per-agent configuration for every project. For developers, that could mean less boilerplate and a shorter path from idea to working agent, with the harness functioning as something like a standard library of agent parts.

The security guidance is the second takeaway, and arguably the one that travels furthest beyond this framework. As observability tooling becomes a default part of the agent stack, the number of external services receiving an agent's complete context grows. Prompt hygiene — keeping secrets out of anything the model can see — stops being a nice-to-have and becomes a baseline requirement for shipping agents safely.