Pydantic AI v2.0.0 went stable on June 23, 2026, after seven betas, and the release notes want you to talk about the Harness — a composable bundle of tools, hooks, instructions, and model settings that the team is betting is the right primitive for an agent, a bet they lay out in the launch post. That's the interesting design story. It is not the story that will wake you up.

The one that will is four characters long. In v2, the bare model string openai:gpt-5 no longer means what it meant in v1.

The prefix moved under you#

In v1, openai: resolved to OpenAIChatModel — the Chat Completions API, the endpoint every OpenAI integration has spoken for years. In v2, the same bare prefix resolves to OpenAIResponsesModel — the Responses API. The change was deliberate, tracked in issue #4041, "Default openai: to Responses API (add explicit chat prefix)", and the reasoning is sound: Chat Completions is the older surface, OpenAI treats Responses as the forward path, so the unqualified default should point at the API more likely to still be current next year.

The reasoning isn't the problem. The silence is.

Why your upgrade checklist can't catch it#

Pydantic's own upgrade guide gives the responsible migration path: move to the latest v1 first, clear every deprecation warning, and — in their words — almost nothing else should break. That advice is good and it is usually sufficient, because most of v2's breaking changes were staged as v1 deprecations. You get warned, you fix the call site, you upgrade clean.

A changed default resolution is a different species of break, and it slips through the exact mechanism that's supposed to protect you.

A deprecation warning fires on a symbol you're still calling. It has nothing to say about a symbol whose meaning changed while the call stayed identical.

openai:gpt-5 is not deprecated. It's not renamed. It's not removed. Your code calls it in v1 and calls the same string in v2 — so there is no deprecated call site for the warning system to attach to. You can clear every warning, ship a "clean" upgrade, and still have silently swapped which OpenAI API your agent talks to. The migration checklist is complete and wrong at the same time.

Two APIs are not one API#

If Chat Completions and Responses were the same endpoint with a new name, none of this would matter. They aren't. Responses is stateful where Chat Completions is stateless — it can carry conversation items server-side rather than you replaying the full message list each turn. The tool-calling surface differs. Structured-output handling differs. Reasoning models expose reasoning items through Responses that Chat Completions doesn't surface the same way. Streaming emits a different event shape.

None of that is catastrophic on its own. All of it means "same model, same prompt, same code" can produce a different run after the version bump — a tool call that parses differently, a structured response that validates differently, a stream your consumer handles differently. The failure isn't a crash at import time, which would be easy. It's a behavior drift at runtime, which is the kind you find in production.

The fix is to stop trusting the bare prefix#

The remedy is mechanical and worth doing before you upgrade, not after. Stop shipping the unqualified openai: prefix at all, because it is now a moving default — and a default that moved once can move again.

Either way, the lesson generalizes past this one release: a bare provider prefix is a convenience, not a contract. In any framework that resolves model strings to model classes, the unqualified form is whatever today's maintainer thinks the sensible default is, and that opinion is allowed to change on a major.

The governance tell#

There's a second line in v2 worth reading next to this one. Pydantic shortened its no-breaking-changes window between major versions from six months to three, on the honest logic that the field moves too fast to commit further out. The Harness is the bet that gets the headline; the halved stability window is the fine print that tells you how to plan.

Both point at the same operating posture. In a stack that re-decides its defaults every quarter, the durable move is to pin the surfaces you depend on — the API, not just the model — explicitly, and to treat a warning-clean upgrade as necessary but not sufficient. The bare openai: was always a default. V2 is just the release that made you notice.