Building AI Agents with Pydantic AI and OpenRouter

Introduction

In this tutorial, we will explore how to build robust, type-safe AI agents using Pydantic AI and connect them to a vast array of models through OpenRouter.

Pydantic AI is a revolutionary framework that brings the power of Pydantic’s data validation to the world of LLMs, ensuring that your agent’s inputs and outputs are always strictly typed and validated.

Why Pydantic AI?

• Type Safety: Leverage Python type hints for agent logic.
• Validation: Automatic validation of structured outputs.
• Dependency Injection: Cleanly manage external tools and services.
• Model Agnostic: Works seamlessly with various providers.

Installation

First, let’s set up our environment. You will need Python 3.9+ installed.

pip install pydantic-ai logfire

NOTE We also install logfire for better observability, though it’s optional.

Configuring OpenRouter

OpenRouter provides a unified API for interacting with almost any LLM. To use it with Pydantic AI, we can use the OpenAI-compatible interface.

1. Get your API key from OpenRouter.
2. Set your environment variables:

export OPENROUTER_API_KEY="your_key_here"

Creating the Client

We’ll use the OpenAI provider but point it to OpenRouter’s base URL.

import os
from pydantic_ai.models.openai import OpenAIModel

model = OpenAIModel(
    'openai/gpt-4o', # You can use any OpenRouter model string here
    base_url='https://openrouter.ai/api/v1',
    api_key=os.getenv('OPENROUTER_API_KEY'),
)

Defining a Structured Agent

One of the best features of Pydantic AI is the ability to define exactly what kind of data you want back.

The Response Schema

from pydantic import BaseModel, Field

class WeatherRecommendation(BaseModel):
    city: str
    temperature: float = Field(description="Temperature in Celsius")
    clothing_suggestion: str
    is_raining: bool

Initializing the Agent

from pydantic_ai import Agent

agent = Agent(
    model,
    result_type=WeatherRecommendation,
    system_prompt="You are a helpful weather assistant. Provide clothing advice based on the weather.",
)

Running the Agent

Now, let’s run our agent and see the magic happen.

async def main():
    result = await agent.run("What should I wear in Paris today?")
    print(f"City: {result.data.city}")
    print(f"Advice: {result.data.clothing_suggestion}")

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Expected Output Example

Advanced Features: Tools

You can also give your agents tools to perform actions or fetch real-time data.

@agent.tool
async def get_current_time(city: str) -> str:
    # In a real app, you'd call a Time API
    return f"The time in {city} is 2:00 PM"

Conclusion

Combining Pydantic AI with OpenRouter gives you a powerful, flexible, and type-safe foundation for building the next generation of AI applications.

Key Takeaways

1. Use Pydantic for reliable data structures.
2. Use OpenRouter for unparalleled model access.
3. Use Pydantic AI to glue it all together with minimal boilerplate.

Happy coding!