Pydantic AI Guide: Build Type-Safe AI Agents for Production

What Is Pydantic AI and Why Does It Matter for Production?

In short

Pydantic AI is a Python agent framework built by the creators of Pydantic that enforces type-safe, validated outputs from LLMs — solving the core reliability problem that makes most agent frameworks fragile in production.

LLMs return unstructured text. Most agent frameworks trust that text blindly — and that trust causes silent failures in production.

Wrong data types, missing fields, hallucinated JSON keys: these errors surface downstream, far from the LLM call that caused them. They are nearly impossible to catch without runtime validation.

Pydantic AI solves this by applying Pydantic's validation engine directly to every LLM output before it reaches your application code.

Framework Origin and Credibility

Pydantic AI was built by Samuel Colvin and the Pydantic team — the creators of Pydantic v2, which records 300M+ monthly downloads on PyPI and is the validation engine underpinning FastAPI. Developers who know FastAPI already understand the mental model.

This is not a startup framework. It is built by the team that already owns Python's validation layer — and Pydantic AI applies that same discipline to the least reliable component in any AI system: the LLM's raw output.

How Pydantic AI Compares: Feature Matrix

The 2025 AI Agent Index (Staufer et al., arXiv 2025) documents output reliability and safety as the most critical failure dimensions across 30+ deployed agent systems. Pydantic AI directly addresses both through schema-enforced validation and structured error handling.

For a broader comparison of agent frameworks, see our guide to best AI agent frameworks in 2026.

Core Concepts: Agents, Models, Tools, and Dependencies

In short

Pydantic AI is built on four primitives — Agent, Model, Tools, and Dependencies — whose strict separation of concerns makes agents testable, maintainable, and safe to run in production.

Understanding the four core primitives is the fastest path to productive Pydantic AI development. Each has a single responsibility.

• AgentThe central object. Wraps an LLM model, system prompt, output type, and registered tools. Created once, reused across requests.
• ModelThe LLM provider interface. All providers — OpenAI, Anthropic, Gemini, Ollama, Groq — share the same API. Switch providers by changing one string.
• ToolsPython functions decorated with @agent.tool. The LLM can call these functions during a run. Type annotations generate the tool schema automatically — no manual JSON schema required.
• DependenciesTyped objects injected at runtime via RunContext. Contains database connections, HTTP clients, user context, or any external resource. Never stored in global state.

This separation of concerns is what makes Pydantic AI agents testable. Prompts stay clean. Tools are independently unit-testable. Dependencies are explicit and mockable.

Compare this to frameworks where database connections leak into prompt templates or where tool logic is entangled with LLM orchestration — both common patterns in early LangChain implementations that Alice Labs has refactored in production engagements.

Here is the conceptual relationship between the four primitives:

For a deeper look at how these patterns apply to enterprise architectures, see our guide on AI agent architecture patterns.

Steps 1–2: Install Pydantic AI and Configure Your LLM Provider

In short

Install Pydantic AI with pip, set your API key as an environment variable, and instantiate an Agent with your chosen model string — the entire setup takes under 5 minutes.

Installation is a single pip command. Provider-specific extras are optional but recommended for type hints and provider-specific features.

• Core install: pip install pydantic-ai
• OpenAI extras: pip install 'pydantic-ai[openai]'
• Anthropic extras: pip install 'pydantic-ai[anthropic]'
• Vertex AI extras: pip install 'pydantic-ai[vertexai]'
• All extras: pip install 'pydantic-ai[all]'

Pydantic AI reads API keys from standard environment variables automatically. No custom config layer is needed.

Set OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_API_KEY in your environment — the framework picks them up via its model configuration layer.

Supported Providers and Model String Format

Provider switching in Pydantic AI requires changing exactly one string. No adapter classes, no re-wiring tool schemas, no prompt reformatting. This is a key advantage over the raw SDK approach.

Pydantic AI also integrates with Logfire for production observability. When Logfire is configured, agents emit distributed traces automatically — covering every LLM call, tool invocation, and validation step.

Running Your First Agent: Sync, Async, and Streaming

In short

Pydantic AI agents support three execution modes — run_sync() for scripts, run() for async production apps, and run_stream() for real-time UIs — all returning the same validated result shape.

The simplest agent run is three lines. Here is the complete minimal example using run_sync():

from pydantic_ai import Agent

agent = Agent('openai:gpt-4o', system_prompt='Be concise.')
result = agent.run_sync('What is the capital of Sweden?')
print(result.data)      # → 'Stockholm'
print(result.usage())   # → Usage(requests=1, request_tokens=27, response_tokens=2)

The result object has a consistent shape regardless of which execution mode you use. Key fields:

• result.data — the validated output (str by default; your Pydantic model instance when result_type is set)
• result.usage() — token counts across all LLM calls in the run
• result.all_messages() — full message history including tool calls and responses

For production applications, always use the async interface inside an async function:

import asyncio
from pydantic_ai import Agent

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

async def main():
    result = await agent.run('What is the capital of Sweden?')
    print(result.data)

asyncio.run(main())

For streaming responses, use agent.run_stream(). Pydantic AI supports structured streaming — partial validated objects are emitted token-by-token as the LLM generates them.

async def stream_example():
    async with agent.run_stream('Summarise this document: ...') as response:
        async for text in response.stream_text():
            print(text, end='', flush=True)
    print()
    print(response.usage())

This streaming pattern enables real-time UI updates with full type safety — a significant advantage over frameworks that require you to choose between streaming and validation.

Step 3: Define Structured Output Models for Type-Safe Responses

In short

Pass a Pydantic BaseModel as the result_type parameter to your Agent — Pydantic AI generates a JSON schema, instructs the LLM to conform to it, and validates the response before returning, retrying automatically on validation failure.

Default string outputs are useful for chatbots. For any agent where downstream code parses the response, strings are a reliability liability.

Structured outputs are Pydantic AI's core value proposition. Here is a realistic production example — a research report model:

from pydantic import BaseModel, Field, field_validator
from pydantic_ai import Agent

class ResearchReport(BaseModel):
    title: str = Field(description="Concise title for the report")
    summary: str = Field(description="2-3 sentence executive summary")
    sources: list[str] = Field(description="List of URLs or citations used")
    confidence_score: float = Field(
        description="Confidence in findings, 0.0 to 1.0"
    )

    @field_validator('confidence_score')
    @classmethod
    def validate_confidence(cls, v: float) -> float:
        if not 0.0 <= v <= 1.0:
            raise ValueError('confidence_score must be between 0.0 and 1.0')
        return v

agent = Agent(
    'openai:gpt-4o',
    result_type=ResearchReport,
    system_prompt='You are a research analyst. Return structured reports.'
)

result = await agent.run('Research the state of AI agents in 2025.')
report = result.data  # Fully typed ResearchReport instance

print(report.title)            # str — validated
print(report.confidence_score) # float — guaranteed 0.0–1.0
print(report.sources)          # list[str] — validated list

What happens under the hood: Pydantic AI generates a JSON schema from the model and injects it into the LLM request. The raw response is validated against the schema before result.data is populated.

If validation fails, Pydantic AI retries the LLM call with the validation error appended as context — up to a configurable retry limit. The caller never sees a malformed object.

Key structured output patterns for production:

• Field descriptions: Use Field(description='...') on every field. The description is injected into the LLM's schema — it is the most effective LLM guidance mechanism available without prompt engineering.
• Nested models: Pydantic AI handles arbitrary nesting. An agent can return a model containing lists of other models — all validated recursively.
• Optional fields: Use Optional[str] = None for fields the LLM may not always populate. Pydantic handles None safely at the type level.
• Union types: result_type=str | ResearchReport allows the agent to return different output types based on the input — useful for agents that handle both conversational and structured workflows.

In Alice Labs' 50+ enterprise AI implementations, structured output validation is the single highest-leverage reliability improvement. It eliminates an entire class of downstream parsing failures that plague unstructured agent outputs — failures that are nearly impossible to catch in monitoring because they appear as application errors, not LLM errors.

The 2025 AI Agent Index (Staufer et al., arXiv 2025) identifies output reliability as a top-cited deployment risk across production agent systems. Structured output enforcement is the direct technical solution.

Step 4: Register Tools and Inject Dependencies with RunContext

In short

Decorate Python functions with @agent.tool to give the LLM callable actions, and use a typed Deps dataclass with RunContext to inject databases, HTTP clients, and config at runtime without global state.

Tools transform a conversational agent into a capable system that can search the web, query databases, call APIs, or run calculations.

Pydantic AI generates the tool's JSON schema automatically from Python type annotations. No manual schema writing required.

Here is a complete example with tools and typed dependency injection:

import httpx
from dataclasses import dataclass
from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext

# 1. Define typed dependencies
@dataclass
class Deps:
    http_client: httpx.AsyncClient
    search_api_key: str

# 2. Define structured output
class SearchResult(BaseModel):
    query: str
    answer: str = Field(description="Synthesised answer from search results")
    sources: list[str] = Field(description="URLs of sources consulted")

# 3. Create agent with deps_type and result_type
agent = Agent(
    'openai:gpt-4o',
    deps_type=Deps,
    result_type=SearchResult,
    system_prompt='Search the web and synthesise accurate answers.'
)

# 4. Register a tool
@agent.tool
async def web_search(
    ctx: RunContext[Deps],
    query: str
) -> str:
    """Search the web for current information on a topic."""
    response = await ctx.deps.http_client.get(
        'https://api.search.example.com/search',
        params={'q': query, 'key': ctx.deps.search_api_key}
    )
    return response.json()['results'][0]['snippet']

# 5. Run with injected deps
async def run_search(query: str) -> SearchResult:
    async with httpx.AsyncClient() as client:
        deps = Deps(
            http_client=client,
            search_api_key='sk-...'
        )
        result = await agent.run(query, deps=deps)
        return result.data

The RunContext[Deps] parameter gives the tool access to injected dependencies — without importing them as globals or threading them through function arguments manually.

This pattern mirrors FastAPI's dependency injection. If your team already builds FastAPI services, the mental model transfers directly.

Tool registration patterns in production:

• @agent.tool — standard tool with RunContext access to dependencies
• @agent.tool_plain — tool without RunContext, for pure functions that need no external resources
• Docstrings as descriptions: The function docstring becomes the tool description sent to the LLM. Write them clearly — they directly affect tool selection quality.
• Return types: Tools can return str, int, float, dict, or any JSON-serialisable type. Pydantic validates tool return values too.

For production deployments, keep tool functions small and independently testable. Alice Labs' implementation standard: every tool must pass unit tests using a mocked RunContext before the agent is integrated. This catches tool logic errors before they interact with LLM behaviour.

For more detail on tool use patterns across different agent architectures, see our guide to AI agent tool use patterns.

Multi-Agent Orchestration: Hierarchical and Parallel Patterns

In short

Pydantic AI supports native multi-agent orchestration where agents call other agents as tools — enabling hierarchical workflows, parallel sub-agents, and specialised agent pipelines without third-party orchestration frameworks.

Complex production workflows require more than one agent. A research pipeline might need a search agent, a summarisation agent, and a validation agent — all coordinated.

Pydantic AI handles this natively. Agents can call other agents as tools, creating hierarchical execution trees without external orchestration frameworks.

Here is the core multi-agent pattern — an orchestrator calling specialised sub-agents:

from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext

# Sub-agent 1: Research specialist
class ResearchOutput(BaseModel):
    findings: str
    sources: list[str]

research_agent = Agent(
    'openai:gpt-4o',
    result_type=ResearchOutput,
    system_prompt='You are a research specialist. Find accurate information.'
)

# Sub-agent 2: Writing specialist
class ReportOutput(BaseModel):
    title: str
    body: str = Field(description="Full formatted report body")

writing_agent = Agent(
    'openai:gpt-4o',
    result_type=ReportOutput,
    system_prompt='You are a writing specialist. Write clear, structured reports.'
)

# Orchestrator agent
class FinalReport(BaseModel):
    title: str
    executive_summary: str
    full_report: str

orchestrator = Agent(
    'openai:gpt-4o',
    result_type=FinalReport,
    system_prompt='Coordinate research and writing to produce final reports.'
)

@orchestrator.tool
async def run_research(ctx: RunContext, topic: str) -> str:
    result = await research_agent.run(f'Research: {topic}')
    return f"Findings: {result.data.findings}\nSources: {result.data.sources}"

@orchestrator.tool
async def write_report(ctx: RunContext, research: str, topic: str) -> str:
    result = await writing_agent.run(
        f'Write a report on {topic} using: {research}'
    )
    return result.data.body

For parallel execution, use Python's asyncio.gather() to run multiple sub-agents simultaneously:

import asyncio

async def parallel_research(topics: list[str]) -> list[ResearchOutput]:
    tasks = [research_agent.run(f'Research: {topic}') for topic in topics]
    results = await asyncio.gather(*tasks)
    return [r.data for r in results]

Multi-Agent Pattern Comparison

Alice Labs has deployed hierarchical multi-agent systems for enterprise clients across Sweden and Europe — including pipelines where a coordinator agent routes tasks to domain-specific sub-agents based on query classification. The Pydantic AI native approach eliminates the orchestration complexity and overhead of third-party frameworks.

For broader context on multi-agent architecture, see our guide on multi-agent systems explained.

Step 5: Test Agents Offline with TestModel and FunctionModel

In short

Pydantic AI's TestModel returns deterministic outputs without API calls, enabling full agent unit testing in CI/CD pipelines — validating schema conformance, tool invocation sequences, and retry logic with zero API cost.

Testing AI agents is the most frequently skipped step in production deployments — and the most consequential omission.

Pydantic AI provides two offline testing primitives that eliminate the need for live API calls during testing.

TestModel — returns minimal valid outputs matching the agent's result_type, without making any LLM calls:

import pytest
from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from your_app import research_agent, ResearchReport

def test_research_agent_returns_valid_schema():
    with research_agent.override(model=TestModel()):
        result = research_agent.run_sync('Research AI agents in 2025')

    # Validate output type
    assert isinstance(result.data, ResearchReport)

    # Validate required fields are present
    assert result.data.title is not None
    assert isinstance(result.data.confidence_score, float)
    assert 0.0 <= result.data.confidence_score <= 1.0

    # Validate tool was called
    messages = result.all_messages()
    tool_calls = [m for m in messages if hasattr(m, 'tool_calls')]
    assert len(tool_calls) > 0

FunctionModel — lets you define custom response logic for more complex test scenarios:

from pydantic_ai.models.function import FunctionModel, ModelContext
from pydantic_ai.messages import ModelResponse, TextPart
import json

def custom_model_function(
    messages: list, info: ModelContext
) -> ModelResponse:
    # Return deterministic test data
    return ModelResponse(parts=[
        TextPart(content=json.dumps({
            "title": "Test Report",
            "summary": "Test summary",
            "sources": ["https://example.com"],
            "confidence_score": 0.85
        }))
    ])

def test_research_agent_with_custom_response():
    with research_agent.override(model=FunctionModel(custom_model_function)):
        result = research_agent.run_sync('Any query')

    assert result.data.confidence_score == 0.85
    assert result.data.title == "Test Report"

Testing checklist for production Pydantic AI agents:

• Schema conformance: assert isinstance(result.data, YourModel)
• Field validators: test boundary values (e.g., confidence_score = -0.1 should raise)
• Tool invocation: verify tools are called with correct arguments via all_messages()
• Retry logic: verify agent retries on validation failure up to configured limit
• Dependency injection: mock deps dataclass with controlled test values
• Multi-agent routing: verify orchestrator calls correct sub-agent tool for each input type

Alice Labs includes TestModel-based tests in all production agent deployments as a CI/CD gate. Tests run in milliseconds, require no API keys, and catch schema regressions before they reach staging.

For more context on why AI projects fail in production, see our analysis of why AI projects fail.

Production Deployment: Observability, Error Handling, and EU AI Act

In short

Production Pydantic AI agents require Logfire observability for tracing, configurable retry limits for resilience, structured error handling for graceful failures, and output audit logs to satisfy EU AI Act transparency requirements.

Getting an agent running in development is straightforward. Running it reliably in production requires additional layers: observability, error handling, and governance.

Observability with Logfire: Pydantic AI integrates natively with Logfire. When configured, every agent run emits distributed traces covering LLM calls, tool invocations, validation steps, and retry attempts.

import logfire
logfire.configure()
logfire.instrument_pydantic_ai()

# All subsequent agent.run() calls emit traces automatically
result = await agent.run('Query', deps=deps)

Retry configuration: By default, Pydantic AI retries validation failures up to 1 time. Configure this per agent:

agent = Agent(
    'openai:gpt-4o',
    result_type=ResearchReport,
    retries=3  # Retry up to 3 times on validation failure
)

Error handling: Catch UnexpectedModelBehavior for validation exhaustion and ModelHTTPError for provider API failures:

from pydantic_ai.exceptions import UnexpectedModelBehavior, ModelHTTPError

try:
    result = await agent.run(query, deps=deps)
except UnexpectedModelBehavior as e:
    # LLM failed to produce valid output after all retries
    logger.error(f"Agent validation exhausted: {e}")
    raise
except ModelHTTPError as e:
    # Provider API error (rate limit, timeout, etc.)
    logger.error(f"Provider API error: {e.status_code}")
    raise

EU AI Act compliance: For enterprises deploying Pydantic AI agents in the EU, output audit logging is not optional for high-risk use cases. Log result.all_messages() to a tamper-evident store for every production run.

For a full EU AI Act compliance checklist for AI agent deployments, see our EU AI Act compliance checklist 2026.

Production Readiness Checklist

Enterprise Considerations: When to Use Pydantic AI vs Alternatives

In short

Pydantic AI is the right choice for enterprise teams that need type-safe structured outputs, offline testability, and clean dependency injection — it is not optimised for RAG pipelines, vector search, or no-code agent builders.

Pydantic AI is a deliberate, narrow framework. Understanding what it does not do is as important as understanding what it excels at.

Decision Matrix: When to Use Pydantic AI

Alice Labs' engineering standard for new enterprise agent projects since 2024: start with Pydantic AI for the agent runtime layer. Add specialist libraries (vector databases, RAG frameworks) as tool dependencies injected via RunContext. This keeps the agent logic clean while enabling the full ecosystem.

For a broader framework comparison including CrewAI, AutoGen, and LangGraph, see our open-source AI agent frameworks comparison.

For enterprise leaders evaluating whether to build custom agents or use commercial platforms, the key decision point is structured output reliability. If your downstream systems depend on precise data types and fields from LLM responses, Pydantic AI's validation layer is not optional — it is the architectural foundation.

For strategic context on the build-vs-buy decision, see our guide on build vs buy AI.