Pydantic AI is a Python framework for building LLM agents that return validated, structured outputs using Pydantic models. Instead of parsing raw strings from LLMs, you get type-safe objects with automatic validation.
If you’ve used FastAPI or Pydantic before, then you’ll recognize the familiar pattern of defining schemas with type hints and letting the framework handle the type validation for you.
By the end of this tutorial, you’ll understand that:
- Pydantic AI uses
BaseModelclasses to define structured outputs that guarantee type safety and automatic validation. - The
@agent.tooldecorator registers Python functions that LLMs can invoke based on user queries and docstrings. - Dependency injection with
deps_typeprovides type-safe runtime context like database connections without using global state. - Validation retries automatically rerun queries when the LLM returns invalid data, which increases reliability but also API costs.
- Google Gemini, OpenAI, and Anthropic models support structured outputs best, while other providers have varying capabilities.
Before you invest time learning Pydantic AI, it helps to understand when it’s the right tool for your project. This decision table highlights common use cases and what to choose in each scenario:
| Use Case | Pydantic AI | If not, look into … |
|---|---|---|
| You need structured, validated outputs from an LLM | ✅ | - |
| You’re building a quick prototype or single-agent app | ✅ | - |
| You already use Pydantic or FastAPI | ✅ | - |
| You need a large ecosystem of pre-built integrations (vector stores, retrievers, and so on) | - | LangChain or LlamaIndex |
| You want fine-grained control over prompts with no framework overhead | - | Direct API calls |
Pydantic AI emphasizes type safety and minimal boilerplate, making it ideal if you value the FastAPI-style development experience.
Get Your Code: Click here to download the free sample code you’ll use to work with Pydantic AI and build type-safe LLM agents in Python.
Take the Quiz: Test your knowledge with our interactive “Pydantic AI: Build Type-Safe LLM Agents in Python” quiz. You’ll receive a score upon completion to help you track your learning progress:
Interactive Quiz
Pydantic AI: Build Type-Safe LLM Agents in PythonLearn the trade-offs of using Pydantic AI in production, including validation retries, structured outputs, tool usage, and token costs.
Start Using Pydantic AI to Create Agents
Before you dive into building agents with Pydantic AI and Python, you’ll need to install it and set up an API key for your chosen language model provider. For this tutorial, you’ll use Google Gemini, which offers a free tier perfect for experimentation.
Note: Pydantic AI is LLM-agnostic and supports multiple AI providers. Check the Model Providers documentation page for more details on other providers.
You can install Pydantic AI from the Python Package Index (PyPI) using a package manager like pip. Before running the command below, you should create and activate a virtual environment:
(venv) $ python -m pip install pydantic-ai
This command installs all supported model providers, including Google, Anthropic, and OpenAI. From this point on, you just need to set up your favorite provider’s API key to use their models with Pydantic AI. Note that in most cases, you’d need a paid subscription to get a working API key.
Note: You can also power your Pydantic AI apps with local language models. To do this, you can use Ollama with your favorite local models. In this scenario, you won’t need to set up an API key.
If you prefer a minimal installation with only Google Gemini support, you can install the slim package instead:
(venv) $ python -m pip install "pydantic-ai-slim[google]"
You need a personal Google account to use the Gemini free tier. You’ll also need a Google API key to run the examples in this tutorial, so head over to ai.google.dev to get a free API key.
Once you have the API key, set it as an environment variable:
With the installation complete and your API key configured, you’re ready to create your first agent. The Python professionals on Real Python’s team have technically reviewed and tested all the code examples in this tutorial, so you can work through them knowing they run as shown.
