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 —
strdefeats the purpose. Define a realBaseModelwith constrained fields (Literal,intranges). - Tool descriptions as afterthoughts — the docstring is what the model reads. Write them for an LLM, not a human.
- Ignoring validation errors —
ValidationErroris your friend; catch it and retry with a clearer prompt. - Global state in tools — use
RunContext+deps_typeinstead; 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.