Pydantic AI integration

AI Gateway

Route your LLM calls through the AI Gateway with a single base URL change. Zero vendor lock-in: always run on the best model at the lowest cost for your use case.

Observability

Instrument your code with OpenTelemetry to capture traces, logs, and metrics for every LLM call, agent step, and tool use.

AI Gateway

Overview

Pydantic AI is a Python agent framework designed to make it easier to build production-grade applications with Generative AI. By connecting Pydantic AI to Toqan Router’s AI Gateway, you transform experimental agents into production-ready systems with enterprise-grade capabilities.

Key Benefits

Toqan Router’s AI Gateway enhances your Pydantic AI agents with:

Complete Observability

Track every agent step, tool use, and interaction with detailed traces and analytics

Built-in Reliability

Automatic fallbacks, retries, and load balancing for production resilience

Cost Optimization

Real-time cost tracking and spend management across all your AI operations

Multi-Provider Access

Access 500+ LLMs and 30+ providers through a single, unified integration

Prerequisites

Before integrating Pydantic AI with Toqan Router, ensure you have:

A Toqan Router account and API Key
Python 3.9 or higher
Pydantic AI SDK installed

To setup your API key, see API keys & Endpoints.

Installation

Install Pydantic AI and the OpenAI SDK:

pip install pydantic-ai openai

Configuration

Configure Pydantic AI to use Toqan Router’s AI Gateway by passing a custom OpenAI client:

Python

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider
from openai import AsyncOpenAI
import os

# Configure OpenAI client with Toqan Router AI Gateway
client = AsyncOpenAI(
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router"
)

# Create provider with custom client
provider = OpenAIProvider(openai_client=client)

# Create model and agent
model = OpenAIChatModel("openai/gpt-5.6-sol", provider=provider)
agent = Agent(model=model)

base_url: https://router.toqan.ai/eu/v3/router

Basic Agent Example

Here’s a complete example of creating and running a Pydantic AI agent through Toqan Router:

Python

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider
from openai import AsyncOpenAI
import os

# Configure client with Toqan Router AI Gateway
client = AsyncOpenAI(
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router"
)

# Create provider and model
provider = OpenAIProvider(openai_client=client)
model = OpenAIChatModel("openai/gpt-5.6-sol", provider=provider)

# Create agent
agent = Agent(
    model=model,
    system_prompt="You are a helpful assistant."
)

# Run the agent
result = agent.run_sync("Explain quantum computing in simple terms")
print(result.output)

Agent with Tools

Pydantic AI agents can use tools while routing through Toqan Router:

Python

from pydantic_ai import Agent, RunContext
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider
from openai import AsyncOpenAI
import os

# Configure client
client = AsyncOpenAI(
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router"
)

# Create provider and model
provider = OpenAIProvider(openai_client=client)
model = OpenAIChatModel("openai/gpt-5.6-sol", provider=provider)

# Create agent
agent = Agent(model=model)

@agent.tool
async def get_weather(ctx: RunContext[None], location: str) -> str:
    """Get current weather for a location."""
    return f"The weather in {location} is sunny and 75°F"

# Run agent with tool access
result = agent.run_sync("What's the weather in San Francisco?")
print(result.output)

Structured Outputs

Pydantic AI excels at structured outputs with type-safe validation:

Python

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider
from openai import AsyncOpenAI
from pydantic import BaseModel
import os

class CityInfo(BaseModel):
    name: str
    country: str
    population: int
    famous_for: str

# Configure client
client = AsyncOpenAI(
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router"
)

# Create provider and model
provider = OpenAIProvider(openai_client=client)
model = OpenAIChatModel("openai/gpt-5.6-sol", provider=provider)

# Create agent with structured output
agent = Agent(model=model, output_type=CityInfo)

result = agent.run_sync("Tell me about Paris")
print(f"{result.output.name}, {result.output.country}")
print(f"Population: {result.output.population:,}")
print(f"Famous for: {result.output.famous_for}")

Model Selection

With Toqan Router, you can use any supported model from 30+ providers:

Python

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider
from openai import AsyncOpenAI
import os

# Configure client
client = AsyncOpenAI(
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router"
)

# Create provider
provider = OpenAIProvider(openai_client=client)

# Use Claude
claude_model = OpenAIChatModel("anthropic/claude-sonnet-5", provider=provider)
claude_agent = Agent(model=claude_model)

# Use Gemini
gemini_model = OpenAIChatModel("google/gemini-2.5-flash", provider=provider)
gemini_agent = Agent(model=gemini_model)

# Use any other model
groq_model = OpenAIChatModel("groq/qwen/qwen3.8-27b", provider=provider)
groq_agent = Agent(model=groq_model)

Observability

Getting Started

Integrate Pydantic AI with Toqan Router’s observability to gain complete insights into your AI agent interactions, tool usage, model performance, and conversation flows using OpenTelemetry.

Prerequisites

Before you begin, ensure you have:

A Toqan Router account and API Key
Pydantic AI installed in your project
Python 3.9+

Install Dependencies

# Core Pydantic AI packages
pip install pydantic-ai openai

# Core OpenTelemetry packages (logfire>=4 required for instrument_pydantic_ai)
pip install opentelemetry-sdk opentelemetry-exporter-otlp 'logfire>=4'

Configure Toqan Router

Set up your environment variables to connect to Toqan Router’s OpenTelemetry collector: Unix/Linux/macOS:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://router.toqan.ai/eu/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <TOQAN_API_KEY>"
export OTEL_RESOURCE_ATTRIBUTES="service.name=pydantic-ai-app,service.version=1.0.0"
export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"

Windows (PowerShell):

$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://router.toqan.ai/eu/v2/otel"
$env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer <TOQAN_API_KEY>"
$env:OTEL_RESOURCE_ATTRIBUTES = "service.name=pydantic-ai-app,service.version=1.0.0"
$env:OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"

Using .env file:

OTEL_EXPORTER_OTLP_ENDPOINT=https://router.toqan.ai/eu/v2/otel
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <TOQAN_API_KEY>
OTEL_RESOURCE_ATTRIBUTES=service.name=pydantic-ai-app,service.version=1.0.0
OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>

Integration Example

Using LogFire for OpenTelemetry tracing:

Python

import logfire
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider
from openai import AsyncOpenAI
import os

# Configure Logfire. metrics=False keeps this setup to traces only.
logfire.configure(
    service_name='toqan-traces',
    send_to_logfire=False,
    metrics=False,
)

# Instrument Pydantic AI automatically (requires logfire>=4).
logfire.instrument_pydantic_ai()

# Route LLM calls through the AI Gateway while collecting traces.
client = AsyncOpenAI(
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)
provider = OpenAIProvider(openai_client=client)
model = OpenAIChatModel("gpt-5.4-mini", provider=provider)

# Name the agent so it shows up in Traces. Without name=, the root displays as "agent run".
agent = Agent(model=model, name='capital_helper')

result = agent.run_sync('What is the capital of France?')
print(result.output)

Always pass name= to Agent(...). Without it, gen_ai.agent.name defaults to the literal string 'agent' and every trace root renders as agent run in Traces.

Use logfire.span('label') to set a custom name on the trace root for ad-hoc per-call labelling. The wrapper becomes the trace root and the agent runs as its child.

Python

with logfire.span('weather lookup for user 42'):
    result = agent.run_sync('What is the weather in Paris?')

Streaming

Use agent.run_stream(...) to consume tokens incrementally. Traces capture the same shape as run_sync: a chat span under the agent run, with usage recorded on the final chunk.

Python

import asyncio
import logfire
from pydantic_ai import Agent

logfire.configure(service_name='toqan-traces', send_to_logfire=False, metrics=False)
logfire.instrument_pydantic_ai()

agent = Agent('openai:gpt-5.4-mini', name='capital_helper')

async def main():
    async with agent.run_stream('What is the capital of France?') as result:
        async for chunk in result.stream_text():
            print(chunk, end='', flush=True)
    print()

asyncio.run(main())

The same async pattern works with the AI Gateway configuration shown in Integration Example by replacing the agent construction with the OpenAIChatModel(provider=OpenAIProvider(...)) form.

Troubleshooting

404 on span export: verify OTEL_EXPORTER_OTLP_ENDPOINT is exactly https://router.toqan.ai/eu/v2/otel with no trailing path. The OpenTelemetry SDK appends /v1/traces automatically. Traces missing entirely: call logfire.instrument_pydantic_ai() before any Agent(...) invocation, and confirm logfire>=4 is installed.

View Traces

View your traces in the AI Studio in the Traces tab.

Visit your AI Studio to view real-time analytics and traces.

Overview

Instrument your app

Explore

Monitor

Export

Review

Data privacy & security

Framework integrations

AI Gateway

Observability

AI Gateway

Overview

Key Benefits

Complete Observability

Built-in Reliability

Cost Optimization

Multi-Provider Access

Prerequisites

Installation

Configuration

Basic Agent Example

Agent with Tools

Structured Outputs

Model Selection

Observability

Getting Started

Prerequisites

Install Dependencies

Configure Toqan Router

Integration Example

Streaming

Troubleshooting

View Traces

AI Gateway

Observability

​AI Gateway

​Overview

​Key Benefits

Complete Observability

Built-in Reliability

Cost Optimization

Multi-Provider Access

​Prerequisites

​Installation

​Configuration

​Basic Agent Example

​Agent with Tools

​Structured Outputs

​Model Selection

​Observability

​Getting Started

​Prerequisites

​Install Dependencies

​Configure Toqan Router

​Integration Example

​Streaming

​Troubleshooting

​View Traces

AI Gateway

Overview

Key Benefits

Prerequisites

Installation

Configuration

Basic Agent Example

Agent with Tools

Structured Outputs

Model Selection

Observability

Getting Started

Prerequisites

Install Dependencies

Configure Toqan Router

Integration Example

Streaming

Troubleshooting

View Traces