If you build agents on Pydantic AI, July handed you a decision you can't defer much longer. V2 shipped on June 23 and has been moving fast — v2.10.0 landed July 14. V1 is still here too, and still getting patched — v1.107.1 came out July 10. Two live release trains, and you're standing on the platform.
The instinct is to treat this like every other major version: upgrade when you get around to it. That instinct is wrong here for one specific reason, and the reason is what makes this a real choice rather than a chore.
V1 isn't deprecated — that's the whole point#
Most "V2 is out" posts assume V1 is now a ghost. It isn't. In September 2025, Pydantic AI made an explicit stability promise: no breaking changes until V2. V1 has been in long-term maintenance ever since, and it's still receiving security backports. That July 10 v1.107.1 release wasn't a courtesy — it carried a real fix.
So the framing "migrate or fall behind" doesn't apply. V1 is a supported place to stand. The actual question is narrower and more honest: do the V2 primitives buy you enough to spend an afternoon migrating, or is a maintained V1 fine for another quarter?
What V2 actually redesigned#
V2 is not a feature bump. It's a "harness-first" rewrite built around a single new abstraction: capabilities.
In V1, an agent's configuration is spread across Agent() arguments — tools here, instructions there, hooks and model settings elsewhere. A capability, per the changelog, is "a single, composable unit that bundles an agent's tools, hooks, instructions, and model settings, reaching every layer of the agent through one concept." Instead of wiring the same cross-cutting behavior into five places, you define it once and it applies consistently.
The second half of the redesign is a deliberate shrink. Pydantic AI V2 keeps a small core; additional capabilities ship in a first-party Harness package, and beyond that they're third-party or your own. The philosophy the changelog states plainly: "Pydantic AI stays a small core: some capabilities ship with it, more come from the first-party Pydantic AI Harness, and others are third-party or your own." If you've ever fought a framework that wanted to own your whole stack, this is the opposite bet — and it's the reason V2 needed to break things V1 couldn't.
V1 isn't the past you're escaping. It's a maintained line you're choosing to leave — or not.
Practical additions have followed quickly. v2.9.0 exposes the run's usage_limits to tools and capabilities and adds a /usage slash command to the clai CLI for cumulative token spend — directly useful if you're trying to cap an agent's token bill. v2.4.0 added a GEval evaluator and quality rubrics for LLMJudge. None of these are why you'd migrate, but they're the texture of a line under active development versus one that's frozen.
The thing that forces your hand#
Here's the wrinkle that turns "someday" into "this month." A moderate-severity advisory — GHSA-jpr8-2v3g-wgf9 (CWE-863), in the AG-UI UIAdapter.sanitize_messages dangling-tool-call strip — was fixed in V2 at v2.5.0 (July 3) and backported to V1 at v1.107.1 (July 10).
If your agent uses AG-UI, that means the "do nothing" option is gone. You have to move off any pre-patch version regardless of which train you're on. And once you're already touching versions and reading a changelog, the marginal cost of evaluating V2 drops close to zero. That's the quiet logic of this moment: the security patch makes inertia impossible, and inertia was the only thing making V1-forever attractive.
How to decide, and how to move#
The decision reduces to two cases.
- Migrate to V2 now if you're starting a new agent, if capabilities would clean up config you've already duplicated across agents, or if you want the eval/usage tooling and the small-core extensibility model. New projects have no reason to start on a maintenance line.
- Stay on V1 (patched) if you have a working agent, no appetite for a migration this sprint, and no AG-UI exposure forcing your hand beyond a version bump. V1 is maintained; a quarter on it is a legitimate choice, not technical debt you're hiding.
If you do migrate, don't big-bang it. Upgrade to the latest V1 first — most of what V2 removes was already deprecated as of v1.100.0, so V1 will emit warnings that name exactly what breaks. Resolve those against a running test suite, then bump to V2. You can jump straight across and work the breaking-change list by hand, but the staged path converts a scary rewrite into a checklist you can knock out between other work. If you're also weighing Pydantic AI against the rest of the field, we mapped where it sits versus the Microsoft and LlamaIndex stacks separately.
The mistake to avoid is reading "V2 is out" as "V1 is over." It isn't. You're choosing between two supported lines — one being built out, one being kept alive — and the security patch just made sure you actually make the choice instead of drifting into it.
