Pydantic AI

1.70.0 · active · verified Tue Mar 24

Official agent framework from the Pydantic team. Type-safe, model-agnostic. Built by the same team behind pydantic validation used in OpenAI SDK, LangChain, Anthropic SDK. Released November 2024. Reached V1 in September 2025 with API stability commitment. Current version is 1.70.0 (Mar 2026). V2 planned no earlier than April 2026.

Warnings

breaking result.data was removed. Use result.output. Affects all code written against 0.x docs and tutorials.
Fix: Replace result.data with result.output everywhere.
breaking result_type= parameter on Agent() was removed. Use output_type= instead.
Fix: Agent('model', output_type=MyModel) not result_type=MyModel
breaking result_retries= parameter removed. Use output_retries= instead.
Fix: Agent('model', output_retries=3)
breaking Agent.result_validator decorator removed. Use @agent.output_validator instead.
Fix: @agent.output_validator
breaking Agent.last_run_messages property removed. Access messages via RunResult.
Fix: Use result.all_messages() to access message history.
gotcha pydantic v1 is not supported. pydantic-ai requires pydantic v2. Will silently fail or raise confusing errors if pydantic v1 is installed.
Fix: pip install 'pydantic>=2.0'
gotcha Model strings use provider:model-name format. 'openai:gpt-4o', 'anthropic:claude-sonnet-4-5', 'google-gla:gemini-2.5-flash'. Wrong format raises UnknownModelError.
Fix: Use provider-prefixed strings: 'openai:gpt-4o' not just 'gpt-4o'.
gotcha Before V1 (< 1.0.0), minor versions introduced breaking changes without deprecation warnings. Any code from tutorials written before September 2025 may be broken.
Fix: Upgrade to >= 1.0.0 and follow the official upgrade guide at ai.pydantic.dev/changelog/
gotcha run_sync() is a convenience wrapper. In async contexts use await agent.run() instead. Calling run_sync() inside an existing event loop raises RuntimeError.
Fix: Use await agent.run() in async code. run_sync() only for top-level scripts.

Install

pip install pydantic-ai Python (core)
pip install 'pydantic-ai[logfire]' Python (with Logfire observability)
pip install 'pydantic-ai[openai]' Python (with OpenAI provider)

Imports

Agent
```
from pydantic_ai import Agent, RunContext
```
result.data was renamed to result.output in v0.x. result_type parameter renamed to output_type. All old names raise AttributeError or TypeError on current versions.
RunContext
```
from pydantic_ai import Agent, RunContext

@agent.tool
async def my_tool(ctx: RunContext[MyDeps]) -> str:
    return ctx.deps.some_value
```
Tools that need dependency injection must accept RunContext[DepsType] as first argument. Use @agent.tool_plain for tools that don't need deps.

Quickstart

Minimal agent using pydantic-ai 1.x with run_sync.

from pydantic_ai import Agent

agent = Agent(
    'openai:gpt-4o',
    system_prompt='You are a helpful assistant.'
)

result = agent.run_sync('What is the capital of France?')
print(result.output)  # not result.data

view raw JSON →