Tech With Galvan
Back to Articles
AIMar 22, 2026 • 5 min read

Build an AI Agent with Pydantic AI (Typed Outputs & Tools)

Build a typed AI agent in Python with Pydantic AI — validated outputs, tool calling, and provider switching, with working code and a real example.

Galvan
Galvan

Founder & Creator

Introduction

In the first AI agent tutorial, we built an agent from scratch with raw requests and a hand-written loop. That’s the right way to understand agents. But shipping one? You want typed outputs, validated tool args, and easy provider switching.

Pydantic AI gives you exactly that — an agent framework from the Pydantic team that feels like FastAPI for LLMs. In this post you’ll build an agent that extracts structured data from text and calls a real tool, with full type safety.

Why Pydantic AI?

  • Typed outputs — the agent returns a validated Pydantic model, not a string you have to parse.
  • Validated tool args — tool arguments are checked before your function runs.
  • Provider-agnostic — change one string to switch between OpenAI, Anthropic, Gemini, Ollama.
  • Testable — built-in test helpers and dependency injection.

Setup

uv init pydantic-agent && cd pydantic-agent
uv add pydantic-ai python-dotenv

Create a .env:

MISTRAL_API_KEY=your_key_here

Step 1: A typed output agent

from pydantic import BaseModel
from pydantic_ai import Agent
from dotenv import load_dotenv
import os

load_dotenv()

class MovieReview(BaseModel):
    title: str
    sentiment: str          # "positive" | "negative" | "neutral"
    score: int             # 0-10
    one_line_summary: str

agent = Agent(
    "mistral:mistral-small-latest",
    output_type=MovieReview,
    system_prompt="You analyze movie reviews. Be concise and accurate.",
)

result = agent.run_sync("Just watched Dune Part Two. Visually stunning, "
                        "but the pacing dragged in the middle. 7/10.")
print(result.output)
# MovieReview(title='Dune Part Two', sentiment='mixed', score=7, ...)

No json.loads, no regex, no try/except. The framework guarantees result.output is a valid MovieReview — or raises a typed validation error you can handle.

Step 2: Add a tool

Tools are just Python functions with type hints and docstrings:

import httpx

@agent.tool_plain
def get_box_office(movie: str) -> str:
    """Look up approximate box office for a movie."""
    # Fake data for the example
    data = {"Dune Part Two": "$714M worldwide", "Oppenheimer": "$975M worldwide"}
    return data.get(movie, "unknown")

result = agent.run_sync("How much did Dune Part Two make, and was the review positive?")
print(result.output)
print(result.all_messages())   # full tool-call trace

The model decides when to call get_box_office, the framework validates the movie argument, runs your function, and feeds the result back into the loop — the same agent loop you built by hand, but typed.

Step 3: Dependency injection (the killer feature)

Real agents need DB connections, API clients, and user context. Pydantic AI passes them via RunContext instead of globals:

from dataclasses import dataclass
from pydantic_ai import RunContext

@dataclass
class Deps:
    user_id: str
    db: dict  # pretend database

agent = Agent("mistral:mistral-small-latest", deps_type=Deps, output_type=str)

@agent.tool
def get_user_favorites(ctx: RunContext[Deps]) -> list[str]:
    """Return the current user's favorite movies."""
    return ctx.deps.db.get(ctx.deps.user_id, [])

result = agent.run_sync(
    "Recommend a movie based on my favorites.",
    deps=Deps(user_id="galvan", db={"galvan": ["Dune", "Blade Runner 2049"]}),
)
print(result.output)

This makes agents testable: pass fake Deps in tests, real ones in production. No monkeypatching.

Step 4: Switch providers in one line

# Mistral
agent = Agent("mistral:mistral-small-latest", ...)

# OpenAI
agent = Agent("openai:gpt-4o-mini", ...)

# Local Ollama
agent = Agent("ollama:llama3.2", ...)

# Anthropic
agent = Agent("anthropic:claude-sonnet-4-0", ...)

Same code, different model. Great for benchmarking which model handles your task best.

Step 5: Streaming (for UIs)

For Streamlit/React frontends, stream tokens as they arrive:

import asyncio

async def main():
    async with agent.run_stream("Summarize the plot of Dune") as response:
        async for chunk in response.stream_text():
            print(chunk, end="", flush=True)

asyncio.run(main())

Wire this into st.write_stream for a live typing effect in Streamlit — perfect for your chatbot tutorial.

Common mistakes

  • Vague output types — str defeats the purpose. Define a real BaseModel with constrained fields (Literal, int ranges).
  • Tool descriptions as afterthoughts — the docstring is what the model reads. Write them for an LLM, not a human.
  • Ignoring validation errors — ValidationError is your friend; catch it and retry with a clearer prompt.
  • Global state in tools — use RunContext + deps_type instead; your future self (and your tests) will thank you.

Key Concepts

  • Typed agent = LLM + validated Pydantic output
  • Tools = functions with type hints + docstrings
  • RunContext = dependency injection for agents
  • Provider string = "provider:model" for instant switching
  • Streaming = token-by-token output for responsive UIs

What to Try Next

  • Rebuild the Mistral chatbot with Pydantic AI and typed chat history.
  • Add a tool that queries your SQLite-backed habit tracker data.
  • Expose the agent as an MCP server so Claude Desktop can call it.
  • Benchmark Mistral vs Ollama on your task using the provider-switch trick.

FAQ

Pydantic AI vs LangChain — which one?

LangChain is a big toolbox (chains, memory, retrievers, 100+ integrations). Pydantic AI is a focused agent framework with type safety at its core. If you want validated outputs and testable agents, Pydantic AI. If you need RAG pipelines and a huge ecosystem, LangChain. Many teams use both.

Does it work with local Ollama models?

Yes — agent = Agent("ollama:llama3.2", ...). Quality depends on the model’s tool-calling ability; larger models (8B+) work much better.

How do I handle tool errors gracefully?

Wrap tool bodies in try/except and return an error string — the model will see it and can retry or explain the failure to the user. Never let an exception crash the run loop.