Building Smarter AI Apps: The Pydantic AI Way (Type Safety and Structured Responses)

Gabriel Meléndez

Gabriel Meléndez

— 5 min read
Building Smarter AI Apps: The Pydantic AI Way (Type Safety and Structured Responses)

The landscape of AI Development has been transformed by large language models, but building production-ready AI applications remains challenging. Developers often struggle with unpredictable outputs, inconsistent data formats, and the complexity of integrating AI models into existing Python codebases. Pydantic AI is a useful agent framework that solves these pain points by bringing the reliability and developer experience of modern Python libraries to Gen AI.

What is Pydantic AI and Why Does It Matter?

Designed to make it less painful to build production grade applications with Generative AI.

Traditional AI development often feels like this:

  • You send a prompt to an LLM
  • You get back a string response that might be formatted correctly or maybe not
  • You spend hours writing custom parsing logic
  • You handle edge cases, the AI returns unexpected formats
  • Your application breaks in production when AI decides to be creative with its responses

Pydantic AI eliminates this chaos by ensuring AI responses conform to predefined, validated data structures. Instead of wrestling with unpredictable string responses, you get typed Python objects that integrate seamlessly with your existing codebase.

Now let's see how to implement Pydantic AI with a few examples.

  1. Type Safety and Validation First

When you define a response structure, Pydantic AI ensures the AI's output always conforms to that structure:

from pydantic import BaseModel
from pydantic_ai import Agent

# Define exactly what you expect back
class WeatherResponse(BaseModel):
    temperature: int
    condition: str
    humidity: float
    forecast_confidence: str  # "high", "medium", "low"

# Create an agent that MUST return this structure
weather_agent = Agent('openai:gpt-4o', result_type=WeatherResponse)

# This will ALWAYS return a WeatherResponse object, never a string
result = await weather_agent.run("What's the weather in New York?")
print(f"Temperature: {result.data.temperature}°F")  # Type-safe access
  1. Structured Responses with Built-in Validation

The output will be validated with Pydantic to guarantee it is a SupportOutput, since the agent is generic, it'll also be typed as a SupportOutput to aid with static type checking. This means:

  • No more parsing failures
  • Consistent data formats
  • Immediate error detection
  1. Python-Centric Design Philosophy

Pydantic AI leverages standard Python practices you already know.

from typing import List, Optional
from enum import Enum

class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium" 
    HIGH = "high"

class Task(BaseModel):
    title: str
    description: str
    priority: Priority
    due_date: Optional[str] = None
    tags: List[str] = []

If you understand Pydantic models, you understand Pydantic AI responses

  1. Built-in Error Handling and Retries

When validations fails, Pydantic AI doesn't just crash, retries by sending the validation error back to the model with instructions to fix the response

from pydantic_ai import ModelRetry

@agent.tool
def validate_email(email: str) -> str:
    """Validate an email address format."""
    if "@" not in email or "." not in email.split("@")[1]:
        raise ModelRetry("Please provide a valid email address with @ and domain")
    return email

Getting Started: Step-by-Step Implementation of Pydantic AI

Let's build a comprehensive understanding through progressively complex samples.

Step 1: Basic Agent Setup

First, install Pydantic AI and set your environment:

pip install pydantic-ai
export OPENAI_API_KEY='your-api-key-here'

Create your first structured AI responses:

from pydantic import BaseModel
from pydantic_ai import Agent
import asyncio

# Step 1: Define your response structure
class BookRecommendation(BaseModel):
    title: str
    author: str
    genre: str
    rating: float  # 1.0 to 5.0
    reason: str
    similar_books: list[str] = []

# Step 2: Create an agent with this response structure
book_agent = Agent(
    'openai:gpt-4o',
    result_type=BookRecommendation,
    system_prompt="""You are a knowledgeable librarian. When recommending books, 
    always provide ratings between 1.0 and 5.0, and suggest 2-3 similar books."""
)

# Step 3: Use the agent
async def get_recommendation():
    result = await book_agent.run("I love mystery novels with complex characters")
    book = result.data  # This is guaranteed to be a BookRecommendation object
    
    print(f"📚 {book.title} by {book.author}")
    print(f"⭐ Rating: {book.rating}/5.0")
    print(f"📝 Why: {book.reason}")
    print(f"📖 Similar books: {', '.join(book.similar_books)}")

# Run the example
asyncio.run(get_recommendation())

Step 2: Adding Function Tools for External Integration

Function tools allow your AI agents to interact with external systems and APIs:

from pydantic_ai import Agent
from datetime import datetime
import httpx

# Create an agent that can access external functions
weather_agent = Agent('openai:gpt-4o')

@weather_agent.tool
async def get_current_weather(city: str) -> dict:
    """Get the current weather for a specific city using a weather API."""
    # Simulated API call (in production, use a real weather API)
    weather_data = {
        "temperature": 72,
        "condition": "sunny",
        "humidity": 45,
        "wind_speed": 8
    }
    return weather_data

@weather_agent.tool  
async def get_current_time() -> str:
    """Get the current date and time."""
    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

@weather_agent.tool
async def calculate_comfort_index(temperature: int, humidity: int) -> str:
    """Calculate a comfort index based on temperature and humidity."""
    if temperature < 60 or temperature > 80:
        return "uncomfortable"
    elif humidity > 60:
        return "muggy"
    else:
        return "comfortable"

# Use the agent with access to all these tools
async def weather_demo():
    result = await weather_agent.run(
        "What's the weather like in San Francisco and how comfortable is it?"
    )
    print(result.data)

Step 3: Managing Complex Conversations with Context

Pydantic AI provides access to message exchange during an agent run. These messages can be used both to continue a coherent conversation and to understand how an agent performed:

from pydantic_ai import Agent, RunContext
from pydantic import BaseModel

class UserPreferences(BaseModel):
    user_id: str
    preferences: dict
    conversation_history: list = []
    session_data: dict = {}

class PersonalizedResponse(BaseModel):
    response: str
    personalization_used: list[str]
    recommendations: list[str] = []

# Agent with persistent context
personal_assistant = Agent(
    'openai:gpt-4o',
    deps_type=UserPreferences,
    result_type=PersonalizedResponse,
    system_prompt="""You are a personal assistant. Use the user's preferences 
    and conversation history to provide personalized responses."""
)

@personal_assistant.tool
async def save_preference(preference_key: str, preference_value: str, ctx: RunContext[UserPreferences]) -> str:
    """Save a user preference for future conversations."""
    ctx.deps.preferences[preference_key] = preference_value
    return f"Saved preference: {preference_key} = {preference_value}"

@personal_assistant.tool
async def get_user_history(ctx: RunContext[UserPreferences]) -> list:
    """Retrieve the user's conversation history."""
    return ctx.deps.conversation_history[-5:]  # Last 5 interactions

async def personalized_conversation():
    # Initialize user context
    user_context = UserPreferences(
        user_id="user123",
        preferences={"communication_style": "friendly", "interests": ["tech", "books"]},
        conversation_history=["Asked about Python tutorials", "Interested in AI development"]
    )
    
    result = await personal_assistant.run(
        "I want to learn more about web development",
        deps=user_context
    )
    
    print(f"Response: {result.data.response}")
    print(f"Personalization used: {result.data.personalization_used}")
    print(f"Recommendations: {result.data.recommendations}")

What's happening under the hood?

When personal_assistant.run() is called with deps=user_context:

  • The AI's system prompt immediately gets access to the context implied by user_context.
  • If the AI decides it needs to save a preference (e.g, if the user says "I like dark mode"), it can call the save_preference tool, and that tool will receive the same user_context object (specifically, ctx.deps). Any changes made within the tool will persist in that user_context instance for the duration of the run.
  • Similarly, if the AI wants to recall past interactions, it can call get_user_history, which will access ctx.deps.conversation_history.

This powerful pattern allows you to build stateful AI agents that truly understand and adapt to individual users over time. No more "who are you again?" moments.

Pydantic AI isn't just a library; it's a philosophy for building robust and intuitive AI Solutions. So, what are you waiting for? Dive in, experiment, and start building the next generation of intelligent agents that truly understand the world and the users around them.