What the Capability Primitive Bundles
The Pydantic team shipped Pydantic AI v2 as a stable release on June 23, 2026. Its centerpiece is the capability primitive, which binds instructions, tools, lifecycle hooks, and model configuration into a single composable unit. Extensions like memory and guardrails, previously bolted onto each agent separately, now unify into one concept across every layer, so the answer to "which guardrails does this agent carry" collapses into a single place in code.
Why harness-first Keeps the Core Thin
v2 adopts a harness-first architecture: it keeps only the loop, the providers, and the capability and hook APIs small in the core, and pushes everything else into the Harness layer. A thin core loosens the coupling between framework version and feature logic, so an upgrade no longer spills into rewriting features. This release also makes OpenAI model names default to the Responses API and ships WebSearch and WebFetch natively — the kind of default changes a thin core absorbs more easily.
A Non-Breaking Window Cut From Six Months to Three
v2 shortens the major-to-major non-breaking window from six months to three. That a team with more than 100 non-breaking releases since v1 has halved this window means any in-house assets layered on the framework now face a compatibility check every three months. The more tightly an organization has coupled hooks and middleware to a framework version, the harder that compressed cadence lands.
Turning Copy-Paste Into a Company Capability Standard
Start planning from what you will measure, not from success stories. Set three metrics: the reuse rate of shared modules (how many agents import the same guardrail), the propagation time for a one-line guardrail policy change to reach every agent, and the elapsed time to complete a major upgrade. Realistic starting bars are a 90%+ shared-capability reuse rate for new agents, policy-change propagation within one day, and upgrade time inside 30 days — one third of the non-breaking window.
Failure tends to arrive in three forms. First, copy-pasting guardrail logic per agent means a rule change misses a spot or two and policy quietly diverges. Second, coupling hooks and middleware to a specific framework version scatters the edit surface across the codebase inside a window now only three months wide. Third, not booking the shortened upgrade window into the schedule pushes compatibility checks into overtime right before a release.
Recovery branches all converge toward the standard module. When a copy-paste trace surfaces, promote that logic into a shared capability and replace the original with an import; when version coupling shows up, wrap the hook behind the capability API so only a thin adapter is exposed to the version. To answer the narrower window, pre-schedule compatibility work against release dates such as the June 23 GA, which keeps checks off the deadline.
Lock the operations checklist before deploying. Record the owning team and policy version as metadata on every capability, and force identical log fields — capability ID, version, policy outcome, masked input — across guardrail blocks, memory reads, and audit writes so you can trace which agent ran them from one dashboard. Mask PII on both memory storage and the audit log, and when attaching a new agent, gate the release on whether all three shared capabilities are actually imported.
Keep the improvement loop short to match the cadence. Weekly, list the capabilities with low reuse and the top logic still left as copy-paste, and before the three-month window closes, manage the adapter layer's change log separately from feature code. Extract your three shared capabilities in this order: (1) collect all guardrail, memory, and audit-log code across agents and tabulate the duplicated logic; (2) separate policy decisions from execution and fix the guardrail capability interface first (input checks, block reasons, bypass logging); (3) bundle the memory capability's storage schema, retrieval scope, retention period, and masking rules into one unit; (4) standardize the audit-log capability so the events emitted by the first two share common fields; (5) apply all three to a single pilot agent, measure propagation time and reuse rate, then roll out fully.
The Migration in One Page
A capability is a device for killing copy-paste, not a framework bragging point. Borrow v2's primitive that binds instructions, tools, hooks, and model config into one unit, extract guardrails, memory, and audit logging as standard in-house modules, and declare the bars — 90% reuse, one-day propagation, 30-day upgrade — in code. Then even as the non-breaking window narrows to three months, a one-line policy edit reaches every agent within a day.
References
Pydantic AI v2: capabilities, a leaner core, and the Harness — Pydantic