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

# Integração com Pydantic AI

> Conecte o Pydantic AI ao AI Gateway do Toqan Router para ter observabilidade completa, confiabilidade integrada e acesso a mais de 500 LLMs de mais de 30 provedores.

> [card] [AI Gateway](#ai-gateway)
>
> Encaminhe suas chamadas de LLM pelo AI Gateway alterando apenas a URL base. Sem dependência de fornecedor: execute sempre o melhor modelo pelo menor custo para o seu caso de uso.

> [card] [Observabilidade](#observability)
>
> Instrumente seu código com OpenTelemetry para capturar traces, logs e métricas de cada chamada de LLM, etapa de agente e uso de ferramenta.

## AI Gateway

### Visão geral

O Pydantic AI é um framework de agentes em Python criado para facilitar a construção de aplicações de nível de produção com IA generativa. Ao conectar o Pydantic AI ao AI Gateway do Toqan Router, você transforma agentes experimentais em sistemas prontos para produção, com recursos de nível empresarial.

### Principais benefícios

O AI Gateway do Toqan Router aprimora seus agentes Pydantic AI com:

> [card] Observabilidade completa
>
> Acompanhe cada etapa do agente, uso de ferramenta e interação com traces e análises detalhados

> [card] Confiabilidade integrada
>
> Fallbacks automáticos, novas tentativas e balanceamento de carga para resiliência em produção

> [card] Otimização de custos
>
> Rastreamento de custos em tempo real e gestão de gastos em todas as suas operações de IA

> [card] Acesso a vários provedores
>
> Acesse mais de 500 LLMs e mais de 30 provedores por meio de uma única integração unificada

### Pré-requisitos

Antes de integrar o Pydantic AI ao Toqan Router, verifique se você tem:

* Uma conta no Toqan Router e uma chave de API
* Python 3.9 ou superior
* O SDK do Pydantic AI instalado

> [!NOTE]
>
> Para configurar sua chave de API, consulte Chaves de API e endpoints.

### Instalação

Instale o Pydantic AI e o OpenAI SDK:

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

### Configuração

Configure o Pydantic AI para usar o AI Gateway do Toqan Router passando um cliente OpenAI personalizado:

```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 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`

### Exemplo básico de agente

Veja um exemplo completo de criação e execução de um agente Pydantic AI pelo Toqan Router:

```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 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)
```

### Agente com ferramentas

Agentes Pydantic AI podem usar ferramentas enquanto são encaminhados pelo Toqan Router:

```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("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)
```

### Saídas estruturadas

O Pydantic AI se destaca em saídas estruturadas com validação com segurança de tipos:

```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("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}")
```

### Seleção de modelo

Com o Toqan Router, você pode usar qualquer modelo compatível de mais de 30 provedores:

```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("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)
```

## Observabilidade

### Primeiros passos

Integre o Pydantic AI à observabilidade do Toqan Router para obter uma visão completa das interações dos seus agentes de IA, do uso de ferramentas, do desempenho dos modelos e dos fluxos de conversa usando OpenTelemetry.

### Pré-requisitos

Antes de começar, verifique se você tem:

* Uma conta no Toqan Router e uma chave de API
* O Pydantic AI instalado no seu projeto
* Python 3.9+

### Instale as dependências

```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 o Toqan Router

Configure suas variáveis de ambiente para se conectar ao coletor OpenTelemetry do Toqan Router:

**Unix/Linux/macOS:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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):**

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

**Usando um arquivo .env:**

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

### Exemplo de integração

Usando o LogFire para tracing com OpenTelemetry:

```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 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)
```

> [!TIP]
>
> Sempre passe `name=` para `Agent(...)`. Sem isso, `gen_ai.agent.name` assume por padrão a string literal `'agent'` e toda raiz de trace aparece como `agent run` em **Traces**.

Use `logfire.span('label')` para definir um nome personalizado na raiz do trace e rotular chamadas individualmente. O wrapper se torna a raiz do trace e o agente é executado como filho dele.

```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(...)` para consumir tokens de forma incremental. Os traces capturam a mesma estrutura de `run_sync`: um span de chat sob a execução do agente, com o uso registrado no chunk final.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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())
```

O mesmo padrão assíncrono funciona com a configuração do **AI Gateway** mostrada em **Exemplo de integração**, substituindo a construção do agente pela forma `OpenAIChatModel(provider=OpenAIProvider(...))`.

### Solução de problemas

**Erro 404 na exportação de spans**: verifique se `OTEL_EXPORTER_OTLP_ENDPOINT` é exatamente `https://router.toqan.ai/eu/v2/otel`, sem caminho adicional no final. O SDK do OpenTelemetry acrescenta `/v1/traces` automaticamente.

**Nenhum trace aparece**: chame `logfire.instrument_pydantic_ai()` antes de qualquer invocação de `Agent(...)` e confirme que `logfire>=4` está instalado.

### Visualize os traces

Veja seus traces no [AI Studio](/docs/pt-BR/ai-studio/observability/quickstart.md), na aba **Traces**.

> [!NOTE]
>
> Acesse seu [AI Studio](https://router.toqan.ai/eu) para ver análises e traces em tempo real.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.