Pydantic AI

The core object is an Agent: a model (chosen with a provider-prefixed string such as openai:...), instructions, tools, an output type and a dependencies type. A run loops between the model and tools until it can return a validated output. Capabilities package tools, instructions and hooks so they can be reused across agents, and toolsets bring in external tools, including MCP servers.

The multi-agent guide describes increasing levels: agent delegation (a tool on one agent runs another agent and control returns to the caller, optionally via the Harness SubAgents capability), programmatic hand-off (application code decides which agent runs next), graph-based control flow with the separate pydantic-graph package, and deep agents with planning and sandboxed execution. Agents are stateless and meant to be defined once at module level.

Conversation state is not stored by the framework: the docs recommend serializing message history to your own database, with StepPersistence in Pydantic AI Harness as a ready-made option. Durable execution integrations checkpoint model and tool calls so a run survives restarts.

Human approval goes through deferred tools. A tool registered with requires_approval=True (or one that raises ApprovalRequired) is not executed immediately. Either a HandleDeferredToolCalls capability resolves the pending calls inside the run with your handler, or the run ends with a DeferredToolRequests output; the caller then collects approvals or denials and starts a new run with the previous message history and DeferredToolResults. The same mechanism hands a tool call to a frontend or background worker for external execution. The AG-UI adapter can surface tool approvals in a frontend, and the durable execution guide covers long human waits.

pip install pydantic-ai

from pydantic_ai import Agent, RunContext, UsageLimits

researcher = Agent('openai:gpt-5.2', name='researcher',
                   instructions='Return three short facts about the topic.')
writer = Agent('openai:gpt-5.2', name='writer',
               instructions='Write a one-paragraph brief. Call research() first.')

@writer.tool
async def research(ctx: RunContext, topic: str) -> str:
    """Ask the research agent for facts about a topic."""
    result = await researcher.run(topic, usage=ctx.usage)  # share the usage budget
    return result.output

# needs OPENAI_API_KEY
result = writer.run_sync('The Agent2Agent protocol',
                         usage_limits=UsageLimits(request_limit=6))
print(result.output)
print(result.usage)

• Requires Python 3.10+.
• Model strings need a provider prefix (openai:...); in V2 the prefix-less form raises UserError. Set the provider key, for example OPENAI_API_KEY.
• V2 (stable since 2026-06-23 per the upgrade guide) moved many Agent(...) arguments onto capabilities and removed Agent.to_a2a() and Agent.to_ag_ui(); the docs recommend upgrading through the latest V1 and clearing deprecation warnings first.
• A bare pip install pydantic-ai no longer pulls extras such as ag-ui, temporal, groq or bedrock; add the ones you use, or install pydantic-ai-slim[...].
• GitHub releases on 2026-09-30 include both v2.52.0 and v1.107.7; the repository's latest-release flag points at the V1 tag, so check which major you pin.

Yes, as a client over Streamable HTTP, SSE or stdio, plus provider-native MCP tools. The docs also show calling agents inside tools of an MCP server you write.

AG-UI is built in through AGUIAdapter. A2A only works through the separate fasta2a package, because V2 removed Agent.to_a2a().

The framework is MIT-licensed. Pydantic sells Logfire (observability, with a free tier) and enterprise support for Pydantic AI; neither is required.

The upgrade guide lists V2.0.0 as stable since 2026-06-23, and V2 releases continue alongside V1 patch releases. New projects can start on V2; V1 code should follow the migration map.

Mostly by delegation: a tool on one agent runs another agent and returns its output. Hand-offs in application code and typed graphs via pydantic-graph cover more structured flows.