A lookup index for upgrading from Pydantic AI V1 to V2: find the V1 name you have in your code, read off the V2 name to replace it with.
The Upgrade Guide is the canonical source for why each change was made, the behavior changes that come with it, and the recommended upgrade path. This page is the fast path for the one question the guide answers in prose: what replaced what.
Agent configuration
Most V1 Agent(...) arguments that configured behavior moved onto capabilities, a single composable primitive that bundles an agent’s tools, hooks, instructions, and model settings.
V1
V2
Agent(builtin_tools=[...])
Agent(capabilities=[NativeTool(...)])
Agent(event_stream_handler=...)
Agent(capabilities=[ProcessEventStream(...)]) (the event_stream_handler= argument on run()/run_sync()/run_stream()/iter() is unchanged)
StreamedResponse.usage() (custom Model subclasses)
StreamedResponse.usage property
Model name prefixes
V1 prefix
V2 prefix
openai: (Chat Completions)
openai: now means the Responses API; use openai-chat: for Chat Completions, openai-responses: to be explicit
google-gla:
google:
google-vertex:, vertexai:
google-cloud:
gateway/gemini:, gateway/google-vertex:
gateway/google-cloud:
grok:
xai:
Model profiles
ModelProfile and its subclasses are now TypedDicts rather than dataclasses. Constructing one (OpenAIModelProfile(field=value)) is unchanged; reading, mutating, or merging one is not. The full recipe table is in the Upgrade Guide under ModelProfile is now a TypedDict.
V1
V2
profile.field
profile.get('field', <default>) — defaults are exported from pydantic_ai.profiles
OpenAIModelProfile.openai_unsupported_model_settings — not a rename, see below
OpenAIModelProfile.openai_builtin_tools
OpenAIModelProfile.openai_native_tools
Not a straight rename
Two of the OpenAI rows above need more than a find-and-replace:
openai_supports_sampling_settings → openai_unsupported_model_settings changes shape, not just name. The V1 field was a bool covering the sampling settings as a group; the V2 field is a sequence of the specific setting names to drop. openai_supports_sampling_settings=False becomes an explicit list of what the model doesn’t accept, e.g. openai_unsupported_model_settings=('temperature', 'top_p'). True was the default, so it simply goes away.
system_prompt_role moves from a model argument into a profile. If you were already passing profile= to the model, merge the setting into that profile rather than replacing it — a second OpenAIModelProfile(...) overrides the first wholesale. Profiles are TypedDicts in V2, so merging is {**existing_profile, 'openai_system_prompt_role': 'user'} or merge_profile().
MCP
The per-transport server classes collapsed into a single MCPToolset whose transport is inferred from the arguments you pass. Its defaults differ from the V1 classes’ — notably max_retries, read_timeout, init_timeout, and elicitation_handler — so re-read MCP Client rather than assuming your V1 timeouts carried over.
Return [] — returning None now raises TypeError instead of stripping all tools
WebSearch() / WebFetch() falling back to a local implementation
WebSearch(local='duckduckgo') / WebFetch(local=True) — both are native-only by default and now raise on models that don’t support them
Messages, events and usage
The serialized part_kind wire values and the old field names’ validation aliases are retained, so message history written by V1 still deserializes in V2.
V1
V2
BuiltinToolCallPart, BuiltinToolReturnPart
NativeToolCallPart, NativeToolReturnPart
BuiltinToolCallEvent, BuiltinToolResultEvent
Removed — native tool calls surface via PartStartEvent/PartDeltaEvent only
FunctionToolCallEvent/FunctionToolResultEvent for output tools
async with agent.run_stream_events(...) as events: then iterate — it is an async context manager only
Pydantic Graph
V1
V2
from pydantic_graph.beta import GraphBuilder
from pydantic_graph import GraphBuilder
pydantic_graph.persistence
No pydantic_graph equivalent — the builder API doesn’t snapshot graph state. To save, resume, and fork agent run state, Pydantic AI Harness ships StepPersistence
Removed; versions 2–4 still work but warn. The default is version 5
Reading run-span token usage from gen_ai.usage.*
Run spans report gen_ai.aggregated_usage.*; set use_aggregated_usage_attribute_names=False to keep the V1 names
Packaging
A bare uv add pydantic-ai / pip install pydantic-ai now installs a slimmer set of extras. bedrock, groq, mistral, cohere, xai, huggingface, temporal, ag-ui, ui, and spec are no longer included by default — add the ones you use, e.g. uv add 'pydantic-ai[bedrock,groq]'. The outlines-*, vertexai, fastmcp, and a2a extras are removed outright. See the installation guide for the full list.
Behavior changes with no code change
These flip without any symbol changing name, so they can’t be found by grepping for an old name. Each is explained in full in the Upgrade Guide under changes not covered by deprecation warnings.
The default end_strategy changed from 'early' to 'graceful', so function tools requested alongside a successful output tool now run instead of being skipped. See Parallel Output Tool Calls.
sequential=True on a tool is now a per-tool barrier rather than a batch-wide serial switch, and applies to output tools too.
capture_run_messages() also captures the partial request/response of an interrupted run, marked state='interrupted'.
A resolved model profile now carries fields from other profile classes, where V1 filtered them out.