Pydantic AI

By Pydantic

Type-safe agent framework from the Pydantic team — structured, validated results with any model

Website ↗ Repository ↗ Docs ↗

v2.16.02026-07-23PythonMIT

#agents #structured-output #pydantic #python

18.7k Completely free Open source

Doc version 1.0 · Updated June 28, 2026

Related tools

instructor

Structured Output & Typing

LiteLLM

Gateways & Routers

Overview

Pydantic AI is an agent framework from the team behind Pydantic, built around typed, validated results.
You give an Agent a model and (optionally) an output_type, and it returns plain Python objects you can trust — across OpenAI, Anthropic, Gemini, and more.

flowchart LR
  prompt[prompt] --> agent[Agent]
  agent --> model[model]
  model --> out[typed result]

The Code samples tab shows a plain agent and a structured-output agent — pick from the selector to compare.

When to use it

Choose Pydantic AI when you want an agent that fits a Python codebase — typed results, dependency injection, and validation — rather than a heavier framework.

Example

Python · agent

When to use

Reach for it when you want a small, typed agent that feels like writing ordinary Python.

How it flows

run_sync calls the model and returns a result; the reply is on result.output.

Structure

flowchart LR
  prompt[prompt] --> agent[Agent]
  agent --> model[model]
  model --> out[result]

from pydantic_ai import Agent

# Model id is "provider:model" — swap providers by changing the string.
agent = Agent("anthropic:claude-opus-4-8", system_prompt="Be concise.")

result = agent.run_sync("Summarize Pydantic AI in one sentence.")
print(result.output)

When to use

Pass an output_type when the agent's result should be a validated object, not free text.

How it flows

Pydantic AI constrains and validates the model output against your model, returning the typed instance.

Structure

flowchart LR
  prompt[prompt] --> agent[Agent]
  agent --> obj[typed object]

from pydantic import BaseModel
from pydantic_ai import Agent


class Place(BaseModel):
    city: str
    country: str


agent = Agent("openai:gpt-4o", output_type=Place)
result = agent.run_sync("Where is the Eiffel Tower?")
print(result.output)  # Place(city='Paris', country='France')

Example

Pydantic AI — a typed agent

A real, runnable mini-project. Download it and run with Docker.

View samples/pydantic-ai_1 on GitHub ↗

June 28, 2026

Pydantic AI — a typed agent

A tiny Pydantic AI script: it extracts a Person (name, age, occupation) from free text. The agent's output_type is a Pydantic model, so you get a validated object back — not a string to parse.

Configure

cd samples/pydantic-ai_1
cp .env.sample .env
# edit .env: set MODEL and the matching provider key

MODEL is a provider:model string:

Provider	`MODEL`	Key in `.env`
Anthropic Claude	`anthropic:claude-opus-4-8`	`ANTHROPIC_API_KEY`
OpenAI	`openai:gpt-4o`	`OPENAI_API_KEY`
Google AI Studio	`google-gla:gemini-2.5-flash`	`GEMINI_API_KEY`

.env is gitignored — only .env.sample is committed.

Run with Docker

cd samples/pydantic-ai_1
docker build -t aas-pydantic-ai .
docker run --rm --env-file .env aas-pydantic-ai \
  "Ada Lovelace, 36, was a mathematician and the first programmer."

Run with Docker (in a devcontainer with DooD)

In a dev container that talks to the host Docker daemon (Docker-outside-of-Docker), the foreground docker run above often prints nothing and exits 0 — but the run itself succeeds. The script runs to completion and Docker captures all of its output; only the live attached stream drops it over the VM boundary. Run detached and follow the logs instead:

cd samples/pydantic-ai_1
docker build -t aas-pydantic-ai .
docker logs -f "$(docker run -d --env-file .env aas-pydantic-ai \
  "Ada Lovelace, 36, was a mathematician and the first programmer.")"

Run locally

cd samples/pydantic-ai_1
pip install -r requirements.txt
python app.py "Ada Lovelace, 36, was a mathematician and the first programmer."

python-dotenv loads .env automatically.

Example run

Output varies by model and run — LLMs are non-deterministic. The shape is fixed by the Pydantic model; the values are extracted. Below is one run with anthropic:claude-opus-4-8.

name='Ada Lovelace' age=36 occupation='Mathematician'

Files

.env.sample

# Copy this file to `.env` and fill in the key for the provider you want.
#   cp .env.sample .env
#
# Pydantic AI model id is "provider:model".

# Pick the model. Examples:
#   anthropic:claude-opus-4-8    Anthropic Claude   -> needs ANTHROPIC_API_KEY
#   openai:gpt-4o                OpenAI             -> needs OPENAI_API_KEY
#   google-gla:gemini-2.5-flash  Google AI Studio   -> needs GEMINI_API_KEY
MODEL=anthropic:claude-opus-4-8

# Set only the key for the provider you chose; leave the rest blank.
ANTHROPIC_API_KEY=
OPENAI_API_KEY=
GEMINI_API_KEY=

app.py

"""Pydantic AI: a typed agent that returns a validated object.

Extracts a `Person` from free text. The agent's `output_type` is a Pydantic
model, so the result is a validated Python object — not text to parse. MODEL is
a "provider:model" string, so switch providers by changing it.

Run:
    docker build -t aas-pydantic-ai .
    docker run --rm --env-file .env aas-pydantic-ai "Ada Lovelace, 36, was a mathematician."
"""

import os
import sys

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

# Load .env when running locally; in Docker the keys come from --env-file.
load_dotenv()

MODEL = os.environ.get("MODEL", "anthropic:claude-opus-4-8")


class Person(BaseModel):
    name: str
    age: int
    occupation: str


def main() -> None:
    text = " ".join(sys.argv[1:]) or "Ada Lovelace, 36, was a mathematician and the first programmer."

    agent = Agent(MODEL, output_type=Person)
    result = agent.run_sync(f"Extract the person from: {text}")

    print(result.output)


if __name__ == "__main__":
    main()

Dockerfile

# Minimal image for the Pydantic AI sample.
FROM python:3.13-slim

ENV PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

# Provide your config at run time (.env is NOT baked into the image):
#   docker run --rm --env-file .env aas-pydantic-ai "<text to extract from>"
ENTRYPOINT ["python", "app.py"]

Related tools

Overview

When to use it

Pricing

When to use

How it flows

When to use

How it flows

Configure

Run with Docker

Run with Docker (in a devcontainer with DooD)

Run locally

Example run