Pydantic AI v2 migration: the change that throws no error

The change that produces no error

In v2, openai: model names resolve to the Responses API instead of Chat Completions. Nothing errors. Your agent runs, returns text, and bills against a different API surface than the one you tested on v1.

The v2 release notes put it in one line: openai: model names now use the Responses API, and openai-chat: keeps you on Chat Completions.

The Responses API is OpenAI's newer stateful endpoint. It handles built-in tools and reasoning items in a different way from Chat Completions. So the changes you may notice are in tool-call shape, reasoning-token counts and streaming events, not in whether the call works.

Two safe options exist:

1. Pin the old behaviour first. Change openai:gpt-5.4 to openai-chat:gpt-5.4, ship the upgrade, and change nothing else.
2. Move to the Responses API deliberately, in its own pull request, with your evaluation suite watching tool-call accuracy.

Doing both in one commit is how teams spend a week arguing about which change caused a regression.

Your token dashboards may quietly read zero

The second silent change is instrumentation. In v2, use_aggregated_usage_attribute_names defaults to True, so agent run spans report token usage under gen_ai.aggregated_usage.*, while model request spans keep gen_ai.usage.*.

That default exists for a good reason. It stops backends counting parent and child spans twice. But any dashboard or budget alert that reads token usage from run spans under the old names now sees nothing. No error is raised, because nothing failed. Cost tracking just goes quiet.

Set use_aggregated_usage_attribute_names=False if you need the v1 attribute names for now, then migrate the queries. For example, a spend alert wired to gen_ai.usage.input_tokens on run spans has to move to the aggregated name or point at request spans instead.

What breaks loudly, and is therefore safer

Loud breakage is the easy half of this migration. Your imports fail, you fix them, you move on. The v2 announcement lists 6 changes worth checking before you deploy, and only 2 of them are silent.

Change in v2	Fails loudly?	What to do
openai: now uses the Responses API	No	Use openai-chat: to stay on Chat Completions
Aggregated usage attributes default on	No	Repoint dashboards or set the flag to False
MCPServerStdio, MCPServerSSE, MCPServerStreamableHTTP removed	Yes	Move to the current MCP interface
Provider extras no longer bundled	Yes	Install the extra, such as pydantic-ai[bedrock]
Web search and fetch native by default	Partly	Check for duplicate tool definitions
Function tools now run alongside a successful output tool	No	Review end_strategy assumptions

Provider extras are worth a second look. Bedrock, Groq, Mistral and Cohere no longer come with a bare pip install pydantic-ai. So a container that built fine in June can now fail at import time.

The two-step upgrade that actually works

Do not jump from an old v1 to v2 in one move. The Pydantic AI upgrade guide recommends a staged path, and it removes most of the work before v2 is ever installed:

1. Upgrade to the latest v1 release and pin it.
2. Run your test suite with warnings visible, then clear every deprecation warning.
3. Bump to v2 and fix the import errors, which surface immediately.
4. Grep the codebase for openai: and decide, per model string, which API you want.
5. Re-point observability queries, then compare a day of token spend against the previous week.

Steps one and two handle roughly 80% of the work, per Pydantic's upgrade guidance. Steps four and five are the ones nobody schedules, and they are where the silent changes live.

The clock is now shorter than it was

Pydantic changed its version policy alongside the release. The no-breaking-changes window between major versions moves from six months to three, as stated in the Pydantic AI version policy.

That halves the planning horizon for anyone who treats framework upgrades as an annual chore. In practice, a team on this framework should assume a possible major every quarter, and should keep an evaluation suite that can tell whether agent quality moved after an upgrade. If you have watched agents fail in production, you already know that a passing unit test says very little about agent behaviour.

Upgrade now, or wait?

Upgrade now if you call OpenAI models through Pydantic AI. The openai: change sits in your code path either way. Waiting does not remove it. It only delays the day you find out.

The dates make the case. Version 2 landed on June 23, 2026, and the version policy now promises just 3 months of stability between majors. A team that skips this one may face two migrations at once.

Wait a few weeks if you rely on a provider extra and your build has no lockfile. Fix the lockfile first, then upgrade. For example, an image that installs from a loose requirements.txt will pull v2 on the next build with no review at all.

Skip the rush entirely if your agents are on Anthropic or Google models, use no MCP servers, and have no token dashboards. That configuration touches none of the silent changes, so the migration is a genuine afternoon.

One planning note either way: agent memory that does not wreck your prompt cache is a separate concern from this upgrade, but both land in the same request path. Change one at a time, or you will not know which one moved your cost per run.