Pydantic AI Tutorial: Build Type-Safe AI Agents (2026)

Pydantic AI is a Python agent framework that brings FastAPI’s developer experience to GenAI — type-safe, model-agnostic, and built for production from day one. If you’ve ever been frustrated by LangChain’s complexity or wanted structured outputs without fighting JSON parsing, Pydantic AI is the framework to try. It’s built by the same team behind Pydantic, the most downloaded Python validation library.

Who this is for:

• Junior engineers: You want a clean, intuitive way to build your first AI agent without learning a massive framework
• Senior engineers: You need type-safe, testable agents with dependency injection and structured outputs for production

Building AI agents in 2026 means choosing between frameworks that each have painful trade-offs:

“How do I build a Pydantic AI agent with structured output?” — the answer is surprisingly simple: define a Pydantic model, pass it as output_type, and the framework handles the rest.

The core insight: Pydantic AI treats agent building like API development. You declare inputs, outputs, and dependencies — the framework handles the rest. If you’ve used FastAPI, you’ll feel right at home.

Think of Pydantic AI like FastAPI, but for LLM interactions. In FastAPI, you define an endpoint with typed parameters and a response model. In Pydantic AI, you define an Agent with typed dependencies and an output model.

1. Agent — The core object. You give it a model name, an output type, and system instructions. It handles the LLM conversation loop, tool calls, and response validation.

2. Output Types — A Pydantic BaseModel that defines what the agent must return. The framework generates the JSON schema, sends it to the LLM, and validates the response automatically. No manual parsing.

3. Tools — Python functions decorated with @agent.tool. The framework extracts the function signature, generates a tool schema, and handles the call/response cycle. You write plain Python; the framework does the LLM wiring.

4. Dependencies — A typed dataclass passed via RunContext. This is how you inject database connections, API clients, or user context into tools — without global state.

Unlike LangChain where you compose chains of abstractions, Pydantic AI keeps you close to plain Python. An agent is a class. A tool is a function. An output is a Pydantic model. No chains, no runnables, no LCEL syntax.

You’ll build a customer support agent that takes a user message and returns a structured response with advice, risk level, and recommended action.

pip install pydantic-ai

This is the Pydantic model the agent must return. Every field is validated:

from pydantic import BaseModel

class SupportResponse(BaseModel):
    advice: str
    """The support advice to give the customer."""
    risk_level: int
    """Risk level from 1 (low) to 10 (high)."""
    block_card: bool
    """Whether to block the customer's card."""
    escalate: bool
    """Whether to escalate to a human agent."""

Dependencies are injected into tools via RunContext. Define them as a dataclass:

from dataclasses import dataclass

@dataclass
class SupportDeps:
    customer_id: int
    customer_name: str
    account_balance: float

from pydantic_ai import Agent

support_agent = Agent(
    "openai:gpt-4o",
    deps_type=SupportDeps,
    output_type=SupportResponse,
    instructions=(
        "You are a bank support agent. Assess the customer's issue, "
        "provide clear advice, and rate the risk level. "
        "Use the customer's name in your response."
    ),
)

Tools let the agent access external data. The RunContext parameter gives you typed access to dependencies:

from pydantic_ai import RunContext

@support_agent.tool
async def get_recent_transactions(ctx: RunContext[SupportDeps]) -> str:
    """Retrieve the customer's recent transactions."""
    # In production, this would query your database
    return f"Last 3 transactions for customer {ctx.deps.customer_id}: $50 grocery, $200 electronics, $15 coffee"

@support_agent.tool
async def check_fraud_alerts(ctx: RunContext[SupportDeps]) -> str:
    """Check if there are any fraud alerts on the account."""
    return f"No fraud alerts for customer {ctx.deps.customer_id}"

import asyncio

async def main():
    deps = SupportDeps(
        customer_id=123,
        customer_name="Alice",
        account_balance=1500.00
    )

    result = await support_agent.run(
        "I just noticed a $200 charge I didn't make!",
        deps=deps
    )

    # result.output is a validated SupportResponse
    print(f"Advice: {result.output.advice}")
    print(f"Risk: {result.output.risk_level}")
    print(f"Block card: {result.output.block_card}")
    print(f"Escalate: {result.output.escalate}")
    print(f"Tokens used: {result.usage()}")

asyncio.run(main())

The output is a fully validated SupportResponse object — not a string, not a dict, but a type-safe Pydantic model.

Pydantic AI processes requests through four sequential stages: input assembly, the agent orchestration loop, tool execution, and Pydantic model validation of the final output.

The key architectural insight: Pydantic AI separates what your agent does (your code at the top) from how it communicates with LLMs (the framework layers below). Switching from GPT-4o to Claude is a one-line change because the model interface abstracts provider differences.

These three patterns demonstrate Pydantic AI’s most distinctive capabilities: model-agnostic switching, deterministic CI testing with TestModel, and dynamic system instructions from dependencies.

One of Pydantic AI’s strongest features — switch models without changing any agent code:

# Same agent, different models
agent_gpt = Agent("openai:gpt-4o", output_type=SupportResponse, ...)
agent_claude = Agent("anthropic:claude-sonnet-4-20250514", output_type=SupportResponse, ...)
agent_gemini = Agent("gemini-2.0-flash", output_type=SupportResponse, ...)
agent_local = Agent("ollama:llama3.2", output_type=SupportResponse, ...)

Pydantic AI includes a TestModel that returns deterministic responses — no API keys needed:

from pydantic_ai.models.test import TestModel

async def test_support_agent():
    """Test the agent without making any LLM API calls."""
    with support_agent.override(model=TestModel()):
        deps = SupportDeps(customer_id=1, customer_name="Test", account_balance=100)
        result = await support_agent.run("Test message", deps=deps)

        # TestModel returns valid instances of your output type
        assert isinstance(result.output, SupportResponse)
        assert 1 <= result.output.risk_level <= 10

This is a game-changer for CI/CD pipelines. Your agent tests run in milliseconds, cost nothing, and never flake due to API timeouts.

Add context-aware instructions that read from dependencies:

@support_agent.instructions
async def add_context(ctx: RunContext[SupportDeps]) -> str:
    return (
        f"The customer's name is {ctx.deps.customer_name}. "
        f"Their account balance is ${ctx.deps.account_balance:.2f}."
    )

The instruction function runs before every agent call, injecting live context into the system prompt.

Pydantic AI trades ecosystem breadth for type safety and testability — the right choice depends on whether you need pre-built RAG components or clean, validated agent outputs.

Other gotchas:

• Output validation retries — If the LLM returns invalid JSON, Pydantic AI retries automatically. But if your output model is too complex (deeply nested, many optional fields), retries can consume extra tokens. Keep output models flat when possible.
• Async by default — agent.run() is async. For scripts and notebooks, use agent.run_sync(). Forgetting this causes RuntimeError: cannot be called from a running event loop.
• Tool signature matters — Pydantic AI generates tool schemas from your function signatures. Unclear parameter names or missing docstrings produce bad tool descriptions, causing the LLM to misuse tools.

These four questions cover the concepts interviewers use to assess whether you understand Pydantic AI’s design philosophy versus LangChain’s ecosystem approach.

What they’re testing: Can you articulate the architectural philosophy difference?

Strong answer: “Pydantic AI is a minimal agent framework built by the Pydantic team. It focuses on three things: type-safe structured outputs via Pydantic models, dependency injection via RunContext, and model-agnostic agents. LangChain is an ecosystem with hundreds of integrations — retrievers, vector stores, document loaders. Pydantic AI is lean by design; LangChain is batteries-included.”

Weak answer: “Pydantic AI is newer and simpler.”

What they’re testing: Do you understand the structured output mechanism vs. parsing JSON strings?

Strong answer: “You pass a Pydantic BaseModel as the output_type parameter. The framework sends the JSON schema to the LLM, the LLM responds with structured JSON, and Pydantic validates it automatically. If validation fails, the framework retries with the error message. You never parse JSON strings manually.”

What they’re testing: Production readiness — can you test AI code reliably?

Strong answer: “Pydantic AI has a built-in TestModel that returns valid instances of your output type without calling any LLM API. You use agent.override(model=TestModel()) in tests. This gives you deterministic, fast, free tests that run in CI without API credentials.”

What they’re testing: Can you match the framework to the problem?

Strong answer: “I’d choose Pydantic AI when I need structured outputs with validation, when testability is a priority, when I want to swap models easily, or when the team values type safety. I’d stick with LangChain if I need pre-built RAG components, vector store integrations, or the LangGraph state machine for complex agent orchestration.”

Here’s how teams use Pydantic AI in production:

Structured API backends: The most common pattern is using Pydantic AI agents behind a FastAPI endpoint. The agent’s output_type becomes the API response model — one Pydantic model serves both the LLM validation and the HTTP response schema.

Multi-model routing: Teams define one agent with the same tools and output type, then create multiple instances with different models. A router sends simple queries to a cheaper model (GPT-4o mini) and complex queries to a stronger model (Claude Sonnet). Since Pydantic AI is model-agnostic, this takes 3 lines of code.

Observability: Pydantic AI integrates with Logfire (also from the Pydantic team) for tracing. Every agent call, tool execution, and retry becomes a traceable span. For teams already using other observability tools, Pydantic AI also works with OpenTelemetry.

Cost control: The result.usage() method returns exact token counts and costs. Teams log this per-request and set alerts on cost anomalies. Since output models are validated, you don’t burn tokens on retry loops from malformed responses (a common LangChain problem).

For more on how Pydantic AI fits into the broader agent framework landscape, see our comparison guide.

• Pydantic AI brings FastAPI’s developer experience to AI agents — type-safe, model-agnostic, and production-first
• Structured outputs are first-class — declare a Pydantic model, pass it as output_type, get validated objects back
• Dependency injection via RunContext replaces global state and makes agents testable
• TestModel enables deterministic testing — no API keys, no cost, no flaky tests in CI
• Model-agnostic — switch between OpenAI, Anthropic, Google, or local models with one string change
• Intentionally minimal — no built-in RAG, vector stores, or document loaders. Bring your own or combine with LangChain components
• Best for: Teams that value type safety, testability, and clean architecture over a large pre-built ecosystem

• Agentic Frameworks Compared — Pydantic AI vs LangChain vs CrewAI vs AutoGen
• AI Agents — Agent architectures and when to use each
• Agentic Design Patterns — ReAct, tool-use, and multi-agent patterns
• LangChain vs LangGraph — The ecosystem Pydantic AI competes with
• Python for GenAI — Python fundamentals for AI development

Last updated: February 2026 | Pydantic AI v1.x / Python 3.10+