How to beginner · 3 min read

How to get structured outputs with Pydantic AI

Quick answer

Use pydantic-ai by defining a pydantic.BaseModel schema for your expected output and passing it as the result_type parameter when creating an Agent. Then call agent.run_sync() or agent.run() with your prompt to get structured, validated data.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install pydantic-ai openai pydantic>=1.10

Setup

Install the pydantic-ai package along with openai and pydantic. Set your OpenAI API key as an environment variable.

bash

pip install pydantic-ai openai pydantic

output

Collecting pydantic-ai
Collecting openai
Collecting pydantic
Successfully installed pydantic-ai openai pydantic

Step by step

Define a pydantic.BaseModel for the structured output you want. Create a pydantic_ai.Agent with your model and call run_sync to get validated structured data.

python

import os
from pydantic import BaseModel
from pydantic_ai import Agent

# Define your structured output model
class UserInfo(BaseModel):
    name: str
    age: int

# Initialize the agent with OpenAI GPT-4o-mini
agent = Agent(
    "openai:gpt-4o-mini",
    result_type=UserInfo,
    system_prompt="You are a helpful assistant that extracts user info."
)

# Run the agent synchronously with a prompt
result = agent.run_sync("Extract: John is 30 years old")

# Access structured output
print(f"Name: {result.data.name}, Age: {result.data.age}")

output

Name: John, Age: 30

Common variations

Use await agent.run() for async calls.
Change the model by modifying the Agent string, e.g., "openai:gpt-4o".
Use custom system prompts to guide extraction.

python

import asyncio

async def async_example():
    result = await agent.run("Extract: Alice is 25 years old")
    print(f"Name: {result.data.name}, Age: {result.data.age}")

asyncio.run(async_example())

output

Name: Alice, Age: 25

Troubleshooting

If you get validation errors, ensure your prompt clearly matches the expected schema.
Check your API key is set in os.environ["OPENAI_API_KEY"].
Use explicit system prompts to improve extraction accuracy.

✅

Key Takeaways

Define a pydantic.BaseModel to specify the structured output schema.
Use pydantic_ai.Agent with result_type to get validated structured data.
Call run_sync or run to extract structured info from natural language prompts.
Adjust system prompts and model choice to improve extraction quality.
Always set your API key securely via environment variables.

Verified 2026-04 · gpt-4o-mini

Verify ↗