PydanticAI

Overview

PydanticAI is a type-safe Python agent framework built on top of Pydantic, designed for developers who want strong typing, validation, and a clean API for building AI agents. It leverages Pydantic's powerful data validation to ensure your agents produce reliable, structured outputs.

Key Features

📝 Type-Safe Structured Outputs

PydanticAI's standout feature is its deep integration with Pydantic models:

from pydantic import BaseModel, Field
from pydantic_ai import Agent

class WeatherResponse(BaseModel):
    temperature: float = Field(description="Temperature in Celsius")
    condition: str = Field(description="Weather condition description")
    humidity: int = Field(description="Humidity percentage")

agent = Agent('openai:gpt-4o', result_type=WeatherResponse)
result = agent.run_sync('What is the weather in London?')
print(result.data.temperature)  # Type-safe access!

🔧 Tool Definition with Type Hints

Tools are defined using standard Python functions with type hints:

from pydantic_ai import Agent, RunContext
from typing import TypedDict

class Database(TypedDict):
    users: list[dict]

@agent.tool
async def get_user(ctx: RunContext[Database], user_id: str) -> dict:
    """Get a user by ID from the database."""
    return ctx.deps['users'][int(user_id)]

🔄 Dependency Injection

Built-in dependency injection for clean, testable code:

class AppState:
    db: Database
    cache: Cache

agent = Agent('openai:gpt-4o', deps_type=AppState)

async with agent.run('Query the database', deps=AppState(db=..., cache=...)) as run:
    result = await run.get_data()

🧪 Built-in Testing

PydanticAI includes comprehensive testing utilities:

from pydantic_ai import capture_run_messages

def test_weather_agent():
    with capture_run_messages() as messages:
        result = agent.run_sync('What is the weather?')
    
    assert result.data.temperature > 0
    assert len(messages) > 1  # Verify tool calls

Installation

pip install pydantic-ai
pip install pydantic-ai[openai]  # For OpenAI support
pip install pydantic-ai[anthropic]  # For Anthropic support
pip install pydantic-ai[vertex]  # For Google Vertex support

Supported Models

Provider	Models	Status
OpenAI	GPT-4o, GPT-4o mini, GPT-4 Turbo, o1	✅ Full
Anthropic	Claude 3.5 Sonnet, Claude 3 Opus	✅ Full
Google Vertex	Gemini 1.5 Pro, Gemini 2.0	✅ Full
Groq	Llama 3.3, Mixtral	✅ Full
DeepSeek	DeepSeek V3, R1	✅ Full
Mistral	Mistral Large, Small	✅ Full

Advanced Patterns

Multi-Step Agents

from pydantic_ai import Agent, ModelRetry

search_agent = Agent('openai:gpt-4o', name='Searcher')
analysis_agent = Agent('openai:gpt-4o', name='Analyst')

@search_agent.tool
async def search_web(query: str) -> str:
    """Search the web for information."""
    # Search implementation
    return search_results

@analysis_agent.tool
async def analyze_data(data: str) -> str:
    """Analyze the collected data."""
    return analysis

# Chain agents
search_result = search_agent.run_sync('Find information about AI agents')
final_result = analysis_agent.run_sync(
    f'Analyze this: {search_result.data}'
)

Streaming with Type Safety

async for chunk in agent.run_stream('What is the weather?'):
    print(chunk.data.temperature)  # Type-safe streaming

Custom Model Endpoints

from pydantic_ai.models import OpenAIChatModel

# Custom endpoint
model = OpenAIChatModel(
    model_name='gpt-4o',
    base_url='https://your-custom-endpoint.com/v1',
    api_key='your-key'
)

agent = Agent(model, result_type=YourResponseType)

Pros

• ✅ Excellent Type Safety: Full Pydantic integration means compile-time (well, type-checker-time) guarantees
• ✅ Multi-Provider Support: Works with OpenAI, Anthropic, Google, Groq, DeepSeek, and more
• ✅ Clean API: Pythonic design that feels natural to Python developers
• ✅ Great Testing Tools: Built-in testing utilities for reliable agent development
• ✅ Active Development: Rapidly evolving with strong community feedback
• ✅ No Vendor Lock-in: Easy to switch between model providers

Cons

• ❌ Python Only: No official TypeScript/JavaScript support yet
• ❌ Newer Ecosystem: Smaller community than LangChain
• ❌ Pydantic Dependency: Requires understanding of Pydantic for full power
• ❌ Limited Pre-built Tools: Fewer pre-built integrations than LangChain

When to Use

Choose PydanticAI when:

• You're building in Python and value type safety
• You need structured outputs with validation
• You want flexibility across model providers
• You prefer clean, minimal APIs

Consider alternatives when:

• You need TypeScript/JavaScript support
• You want the largest ecosystem of pre-built tools
• You need enterprise support contracts

Resources

• Official Docs: https://ai.pydantic.dev/
• GitHub: https://github.com/pydantic/pydantic-ai
• PyPI: https://pypi.org/project/pydantic-ai/
• Examples: https://ai.pydantic.dev/examples/

Use Cases

Use Case	Why PydanticAI
Structured Data Extraction	Pydantic models guarantee output format
Type-safe APIs	End-to-end type safety from input to output
Multi-provider Deployments	Switch models without code changes
Testing-heavy Projects	Built-in testing utilities
Python-centric Teams	Natural fit for Python developers

Comparison with Alternatives

Feature	PydanticAI	LangChain	CrewAI	DSPy
Type Safety	Excellent	Good	Moderate	Excellent
Model Flexibility	Excellent	Excellent	Good	Good
Learning Curve	Low-Medium	High	Low	High
Python Only	Yes	No	Yes	Yes
Testing Tools	Excellent	Good	Moderate	Good
Production Ready	Yes	Yes	Yes	Yes
Best for	Type-safe Python	Complex integrations	Team workflows	Production RAG

Best Practices

1. Define Pydantic models first — Start with your output schema
2. Use RunContext for dependencies — Clean dependency injection
3. Leverage capture_run_messages — Test tool calls effectively
4. Use TypedDict for dynamic deps — Flexible but typed state
5. Stream with type safety — Maintain types during streaming
6. Test with realistic data — Validate Pydantic models against real inputs

Troubleshooting

Issue	Solution
Type errors	Ensure Pydantic models match expected schema
Tool call failures	Verify tool function signatures and decorators
Dependency injection issues	Check deps_type matches actual deps
Model switching fails	Verify model string format (e.g., openai:gpt-4o)
Validation errors	Use Field(description=...) for clearer errors

---

Last updated: May 2026