> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pydantic AI integration

> Connect Pydantic AI to Orq.ai's AI Router for complete observability, built-in reliability, and access to 300+ LLMs across 20+ providers.

<CardGroup cols={2}>
  <Card title="AI Router" icon="arrow-right-arrow-left" href="#ai-router">
    Route your LLM calls through the AI Router with a single base URL change. Zero vendor lock-in: always run on the best model at the lowest cost for your use case.
  </Card>

  <Card title="Observability" icon="chart-line" href="#observability">
    Instrument your code with OpenTelemetry to capture traces, logs, and metrics for every LLM call, agent step, and tool use.
  </Card>
</CardGroup>

## AI Router

### 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 Orq.ai's AI Router, you transform experimental agents into production-ready systems with enterprise-grade capabilities.

### Key Benefits

Orq.ai's AI Router enhances your Pydantic AI agents with:

<CardGroup cols={2}>
  <Card title="Complete Observability" icon="chart-line">
    Track every agent step, tool use, and interaction with detailed traces and analytics
  </Card>

  <Card title="Built-in Reliability" icon="shield-check">
    Automatic fallbacks, retries, and load balancing for production resilience
  </Card>

  <Card title="Cost Optimization" icon="chart-pie">
    Real-time cost tracking and spend management across all your AI operations
  </Card>

  <Card title="Multi-Provider Access" icon="cubes">
    Access 300+ LLMs and 20+ providers through a single, unified integration
  </Card>
</CardGroup>

### Prerequisites

Before integrating Pydantic AI with Orq.ai, ensure you have:

* An Orq.ai account and [API Key](/docs/administer/api-keys)
* Python 3.9 or higher
* Pydantic AI SDK installed

<Info>
  To setup your API key, see [API keys & Endpoints](/docs/administer/api-keys).
</Info>

### Installation

Install Pydantic AI and the OpenAI SDK:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install pydantic-ai openai
```

### Configuration

Configure Pydantic AI to use Orq.ai's AI Router by passing a custom OpenAI client:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 Orq.ai AI Router
client = AsyncOpenAI(
    api_key=os.getenv("ORQ_API_KEY"),
    base_url="https://api.orq.ai/v3/router"
)

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

# Create model and agent
model = OpenAIChatModel("gpt-4o", provider=provider)
agent = Agent(model=model)
```

> **base\_url**: `https://api.orq.ai/v3/router`

### Basic Agent Example

Here's a complete example of creating and running a Pydantic AI agent through Orq.ai:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 Orq.ai AI Router
client = AsyncOpenAI(
    api_key=os.getenv("ORQ_API_KEY"),
    base_url="https://api.orq.ai/v3/router"
)

# Create provider and model
provider = OpenAIProvider(openai_client=client)
model = OpenAIChatModel("gpt-4o", 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 Orq.ai:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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("ORQ_API_KEY"),
    base_url="https://api.orq.ai/v3/router"
)

# Create provider and model
provider = OpenAIProvider(openai_client=client)
model = OpenAIChatModel("gpt-4o", 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 Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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("ORQ_API_KEY"),
    base_url="https://api.orq.ai/v3/router"
)

# Create provider and model
provider = OpenAIProvider(openai_client=client)
model = OpenAIChatModel("gpt-4o", 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 Orq.ai, you can use any supported model from 20+ providers:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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("ORQ_API_KEY"),
    base_url="https://api.orq.ai/v3/router"
)

# Create provider
provider = OpenAIProvider(openai_client=client)

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

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

# Use any other model
groq_model = OpenAIChatModel("llama-3.3-70b-versatile", provider=provider)
groq_agent = Agent(model=groq_model)
```

## Observability

### Getting Started

Integrate Pydantic AI with Orq.ai'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:

* An Orq.ai account and [API Key](/docs/administer/api-keys)
* Pydantic AI installed in your project
* Python 3.9+

### Install Dependencies

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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 Orq.ai

Set up your environment variables to connect to Orq.ai's OpenTelemetry collector:

**Unix/Linux/macOS:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.orq.ai/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <ORQ_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):**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://api.orq.ai/v2/otel"
$env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer <ORQ_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:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.orq.ai/v2/otel
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <ORQ_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 Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 avoids exporting to /v2/otel which only accepts traces.
logfire.configure(
    service_name='orq-traces',
    send_to_logfire=False,
    metrics=False,
)

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

# Route LLM calls through the AI Router while collecting traces.
client = AsyncOpenAI(
    api_key=os.getenv("ORQ_API_KEY"),
    base_url="https://api.orq.ai/v3/router",
)
provider = OpenAIProvider(openai_client=client)
model = OpenAIChatModel("gpt-4o-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)
```

<Tip>
  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**.
</Tip>

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 Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import asyncio
import logfire
from pydantic_ai import Agent

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

agent = Agent('openai:gpt-4o-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 Router** 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://api.orq.ai/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](/docs/observability/overview) in the **Traces** tab.

<Info>
  Visit your [AI Studio](https://my.orq.ai) to view real-time analytics and traces.
</Info>

## Evaluations & Experiments

Once your agents are running, use **Evaluatorq** to score outputs across a dataset and **Experiments** to compare configurations side-by-side.

<CardGroup cols={2}>
  <Card title="Run Evaluations with Evaluatorq" icon="flask" href="/docs/evaluators/build#evaluatorq">
    Run parallel evaluations across your agents and compare results.
  </Card>

  <Card title="Run Experiments via the API" icon="flask-vial" href="/docs/experiments/api">
    Compare agent configurations and view results in the AI Studio.
  </Card>
</CardGroup>