# Pydantic AI: features, protocols, quickstart

## TL;DR

Pydantic AI is the Pydantic team's MIT-licensed Python agent framework: a typed agent loop with validated structured output, dependency injection and a model string for most providers. Multi-agent work uses delegation through tools, hand-offs in code, or the separate pydantic-graph package. It suits Python teams that want type-checked agents.

## Key facts

| Field | Value |
| --- | --- |
| Type | Framework |
| Languages / SDKs | Python |
| License | MIT |
| Pricing model | [Open core](https://pydantic.dev/pricing) |
| Orchestration pattern | Supervisor |
| GitHub stars | 20,278 (as of 2026-09-30) |
| GitHub forks | 2,828 |
| Last push | 2026-09-30 |
| Latest release | v1.107.7 |
| Repository | [pydantic/pydantic-ai](https://github.com/pydantic/pydantic-ai) |
| Website | [pydantic.dev](https://pydantic.dev/pydantic-ai) |
| Documentation | [pydantic.dev](https://pydantic.dev/docs/ai/) |
| Last verified | 2026-09-30 |

## Key features

- `Agent` with an `output_type`: runs return validated, typed results, and tool arguments are validated before your code runs. ([source](https://github.com/pydantic/pydantic-ai/blob/main/README.md))
- Typed dependency injection: tools and instructions receive a `RunContext` carrying your own dependencies. ([source](https://pydantic.dev/docs/ai/core-concepts/dependencies/))
- Capabilities: reusable bundles of tools, instructions, hooks and model settings attached to an agent. ([source](https://pydantic.dev/docs/ai/capabilities/overview/))
- Multi-agent options: delegation through tools, programmatic hand-off, graph-based control flow and deep agents. ([source](https://pydantic.dev/docs/ai/guides/multi-agent-applications/))
- Deferred tools: calls that need human approval or run outside the process, resolved inline or by the caller. ([source](https://pydantic.dev/docs/ai/tools-toolsets/deferred-tools/))
- Durable execution on Temporal, DBOS, Prefect, Restate, AWS Lambda and other engines. ([source](https://pydantic.dev/docs/ai/capabilities/durable_execution/overview/))
- MCP client over Streamable HTTP, SSE or stdio, plus provider-native MCP tools. ([source](https://pydantic.dev/docs/ai/mcp/client/))
- UI adapters for AG-UI and the Vercel AI SDK event stream protocols. ([source](https://pydantic.dev/docs/ai/integrations/ui/overview/))

## Architecture and orchestration pattern

Pattern: Supervisor.

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 in the loop

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.

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://pydantic.dev/docs/ai/mcp/client/) | Client: agents connect to MCP servers over Streamable HTTP, SSE or stdio and can use provider-native MCP tools; the docs also show agents used inside your own MCP server's tools. |
| A2A | Partial (checked 2026-09-30) | [link](https://pydantic.dev/docs/ai/overview/interfaces/) | Only through the separate `fasta2a` package (github.com/datalayer/fasta2a); V2 removed `Agent.to_a2a()` and the `a2a` extra. |
| AG-UI | Yes (checked 2026-09-30) | [link](https://pydantic.dev/docs/ai/integrations/ui/ag-ui/) | Server side: `pydantic_ai.ui.ag_ui.AGUIAdapter` (`pydantic-ai-slim[ag-ui]`) streams agent events to CopilotKit and other AG-UI frontends; the AG-UI README lists Pydantic AI as 1st party. |

## Best for

- Python services that need validated, typed outputs from LLM calls
- Support or back-office agents with typed dependencies and approval-gated tools
- Long-running agents on an existing Temporal, DBOS or Prefect setup
- Research agents that delegate subtasks to specialist agents through tools

## Not for

- Projects that need built-in A2A serving; it now requires the separate fasta2a package
- Teams that want a role-based crew abstraction instead of composing agents in code
- Non-Python stacks

## Quickstart

```sh
pip install pydantic-ai
```

Install not yet verified by this site.

```python
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)
```

### Common pitfalls

- 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.

Official quickstart: https://pydantic.dev/docs/ai/overview/install/

## Pros

- Outputs and tool arguments are validated with Pydantic, so type checkers and IDEs see the real result types. ([source](https://github.com/pydantic/pydantic-ai/blob/main/README.md))
- Switching model providers is a change of model string across a long list of providers. ([source](https://pydantic.dev/docs/ai/models/overview/))
- Durable execution integrations exist for several engines, five of them co-maintained with the engine vendors. ([source](https://pydantic.dev/docs/ai/capabilities/durable_execution/overview/))
- AG-UI support is part of the package, including shared state and tool approval. ([source](https://pydantic.dev/docs/ai/integrations/ui/ag-ui/))
- Instrumentation is plain OpenTelemetry, so any OTel backend works, not only Logfire. ([source](https://pydantic.dev/docs/ai/integrations/logfire/))

## Cons

- V2 is a breaking release: many `Agent(...)` arguments moved to capabilities and several V1 APIs were removed. ([source](https://pydantic.dev/docs/ai/overview/migration/))
- A2A is no longer built in; `Agent.to_a2a()` was removed in favour of the external fasta2a package. ([source](https://pydantic.dev/docs/ai/overview/migration/))
- Some V2 default behaviors changed without deprecation warnings, such as the default `end_strategy` becoming `'graceful'`. ([source](https://pydantic.dev/docs/ai/project/changelog/))
- Subagents, memory, planning and step persistence helpers live in the separate `pydantic-ai-harness` package. ([source](https://pydantic.dev/docs/ai/harness/))
- The framework does not store conversations for you; persistence means serializing message history yourself or adding Harness. ([source](https://pydantic.dev/docs/ai/core-concepts/persistence/))

## Alternatives

- [OpenAI Agents SDK (Python)](https://multiagentguide.top/tools/openai-agents-sdk.md)
- [LangGraph](https://multiagentguide.top/tools/langgraph.md)
- [Agno](https://multiagentguide.top/tools/agno.md)
- [Google ADK (Python)](https://multiagentguide.top/tools/google-adk.md)
- [CrewAI](https://multiagentguide.top/tools/crewai.md)

## FAQ

### Does Pydantic AI support MCP?

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.

### Does Pydantic AI support A2A and AG-UI?

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

### Is Pydantic AI free?

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

### Which version should I use?

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.

### How does multi-agent work in Pydantic AI?

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.

## Sources

- [Pydantic AI GitHub repository](https://github.com/pydantic/pydantic-ai)
- [Pydantic AI documentation](https://pydantic.dev/docs/ai/)
- [Pydantic AI README](https://github.com/pydantic/pydantic-ai/blob/main/README.md)
- [Pydantic AI product page](https://pydantic.dev/pydantic-ai)
- [Installation (Pydantic AI docs)](https://pydantic.dev/docs/ai/overview/install/)
- [Interfaces, including A2A via fasta2a (Pydantic AI docs)](https://pydantic.dev/docs/ai/overview/interfaces/)
- [Dependencies (Pydantic AI docs)](https://pydantic.dev/docs/ai/core-concepts/dependencies/)
- [Capabilities overview (Pydantic AI docs)](https://pydantic.dev/docs/ai/capabilities/overview/)
- [Multi-agent applications (Pydantic AI docs)](https://pydantic.dev/docs/ai/guides/multi-agent-applications/)
- [Pydantic Graph (Pydantic AI docs)](https://pydantic.dev/docs/ai/graph/graph/)
- [Deferred tools (Pydantic AI docs)](https://pydantic.dev/docs/ai/tools-toolsets/deferred-tools/)
- [Durable execution (Pydantic AI docs)](https://pydantic.dev/docs/ai/capabilities/durable_execution/overview/)
- [Persistence (Pydantic AI docs)](https://pydantic.dev/docs/ai/core-concepts/persistence/)
- [Model Context Protocol overview (Pydantic AI docs)](https://pydantic.dev/docs/ai/mcp/overview/)
- [MCP client (Pydantic AI docs)](https://pydantic.dev/docs/ai/mcp/client/)
- [AG-UI protocol integration (Pydantic AI docs)](https://pydantic.dev/docs/ai/integrations/ui/ag-ui/)
- [UI event stream integrations (Pydantic AI docs)](https://pydantic.dev/docs/ai/integrations/ui/overview/)
- [Models overview (Pydantic AI docs)](https://pydantic.dev/docs/ai/models/overview/)
- [Logfire and OpenTelemetry instrumentation (Pydantic AI docs)](https://pydantic.dev/docs/ai/integrations/logfire/)
- [Pydantic AI Harness](https://pydantic.dev/docs/ai/harness/)
- [V1 to V2 migration map (Pydantic AI docs)](https://pydantic.dev/docs/ai/overview/migration/)
- [Upgrade guide and changelog (Pydantic AI docs)](https://pydantic.dev/docs/ai/project/changelog/)
- [Enterprise support for Pydantic AI](https://pydantic.dev/docs/ai/overview/enterprise-support/)
- [Pydantic pricing (Logfire)](https://pydantic.dev/pricing)
- [Pydantic AI v2.52.0 release](https://github.com/pydantic/pydantic-ai/releases/tag/v2.52.0)
- [Pydantic AI v1.107.7 release](https://github.com/pydantic/pydantic-ai/releases/tag/v1.107.7)
- [fasta2a repository](https://github.com/datalayer/fasta2a)
- [AG-UI README, supported integrations](https://github.com/ag-ui-protocol/ag-ui/blob/main/README.md)

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/pydantic-ai