Stable, After Seven Betas
Pydantic AI v2 hardened into a stable release on June 23, 2026, after seven betas. LlamaIndex Workflows 1.0 stabilized inside the same 48-hour window, but the fact that two framework tracks hit stable together matters less than what v2 actually changed. The core of this release is a harness-first redesign and a new primitive: the capability.
Capability as a Single Primitive
A capability bundles tools, hooks, instructions, and model configuration into one composable unit. The four things that scattered across an agent definition in v1 now reach every layer through a single concept in v2. Pydantic spent a month dogfooding a headless coding agent built on this in their own repo, proving the idea in production rather than in a slide deck.
So this post does not consume the v2 release as news. Redrawing a v1-style flat tool list into capability boundaries takes the discipline of a refactoring project, and that discipline lives in three things: pinning, a regression golden set, and a measured migration coverage.
From Flat Tool Lists to Capability Assembly: A v1-to-v2 Migration Playbook
(a) Planning and target numbers. A migration nails down its definition of done in numbers before any file is opened. Measure capability reuse as the count of duplicate tool definitions: fold a tool declared three times across three agents into one capability, and that count drops from 3 to 1. Define migration coverage as the share of agent paths moved to v2, set a first target of 80% or higher, and treat per-capability regression pass rate above 98% and a post-upgrade tool-call schema validation failure rate under 0.5% as the opening acceptance bar.
Without those numbers, all you retain is the impression that things were "roughly moved to v2," with no basis for tracing what was left behind. Put the coverage metric on a dashboard instead, and the remaining 20% of agent paths becomes visible — the next sprint's backlog derives itself.
(b) Failure patterns and recovery. The first trap is porting the v1 flat tool list verbatim, listing tools with no capability boundaries at all. Without boundaries, nothing is reusable or unit-testable, so the first step of the move is grouping tools into domain capabilities and attaching an I/O contract to each. The second is hooks and instructions scattered outside capabilities, leaving prompt regressions untraceable — name the capability that owns each hook, and wire instruction changes to the golden set so you can see which capability's pass rate they move. The third is auto-upgrading from beta to stable without pinning and breaking production on an API change; the recovery branch is plain. Pin the version exactly, promote an upgrade only after it clears the regression golden set, and revert to the previous pin when schema validation failures cross the threshold.
(c) Operations checklist. Fix the move into four stages. First, lock the v2 version with a pin. Second, define capability boundaries by domain. Third, attach a regression golden set to each capability. Fourth, run it through a dogfooding stage on internal traffic before anything external. Log capability ID, tool-call schema validation result, owning hook, and regression pass flag as required fields, so per-capability pass rate and schema failure rate sit on the same screen. Dogfood exactly as Pydantic did for a month in its own repo — widen the scope starting from low-risk internal agent paths.
(d) Continuous improvement loop. Refresh migration coverage every sprint, and reinject the schema failures caught during dogfooding back into the regression golden set. If the duplicate-tool-definition count is not shrinking sprint over sprint, that is a signal your capability boundaries are a flat list with a new name, and the boundaries need redrawing. Two metrics carry this loop: the rise in capability reuse and the gain in coverage.
The Migration at a Glance
A v2 migration succeeds not on whether you grasp the harness-first structure but on whether you reassemble v1's scattered tools, hooks, and instructions into the single unit of a capability. Hold the four stages — pin the version, define capability boundaries by domain, attach a regression golden set per capability, dogfood from the inside out — and the duplicate-tool count falls while 80% coverage and a sub-0.5% schema failure rate remain as observable numbers.
References
Pydantic AI v2: capabilities, a leaner core, and the Harness — Pydantic