Pydantic AI: Build Type-Safe LLM Agents in Python

Source
pydantic-aillm-agentsstructured-outputpydanticpythontype-safetytool-callingdependency-injectionvalidationgeminiopenaianthropicollama

Summary

Pydantic AI is a Python framework that brings type-safe, validated structured outputs to LLM agent development. It uses Pydantic BaseModel classes to define expected response shapes, automatically validates LLM outputs, and supports tool calling via decorated Python functions. Dependency injection keeps agents testable and free of global state. Validation retries increase reliability but also API costs.

Key Insight

  • Structured outputs via Pydantic models — define a BaseModel class as the agent’s output_type and the framework forces the LLM to return data matching that schema, with automatic validation
  • Agent creation pattern — Agent("provider:model", output_type=MyModel, instructions="system prompt") is the core abstraction; supports Google Gemini, OpenAI, and Anthropic as providers
  • Tool registration — @agent.tool decorator exposes Python functions to the LLM; the LLM decides when to call them based on the function’s docstring and parameter types
  • @agent.tool — receives RunContext for accessing dependencies
  • @agent.tool_plain — no context, simpler signature for stateless tools
  • Dependency injection — deps_type parameter on the Agent lets you pass typed runtime context (DB connections, API clients, config) without global state; accessed via RunContext.deps
  • Validation retries — when the LLM returns data that fails Pydantic validation, the framework automatically retries the query with error feedback; increases reliability but multiplies token costs
  • Cost awareness — every tool call adds input + output tokens; validation retries compound this; structured output mode itself adds overhead vs plain text
  • Provider differences — not all models support structured outputs equally; Gemini, GPT-4o, and Claude work best; local models via Ollama may struggle with complex schemas
  • Async support — agents can run async for IO-heavy workloads
  • MCP support — framework integrates with Model Context Protocol for external tool servers
  • Multi-agent apps — supports composing multiple agents for complex workflows