Integração com Pydantic AI

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.

Observabilidade

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:

Observabilidade completa

Acompanhe cada etapa do agente, uso de ferramenta e interação com traces e análises detalhados

Confiabilidade integrada

Fallbacks automáticos, novas tentativas e balanceamento de carga para resiliência em produção

Otimização de custos

Rastreamento de custos em tempo real e gestão de gastos em todas as suas operações de IA

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

Para configurar sua chave de API, consulte Chaves de API e endpoints.

Instalação

Instale o Pydantic AI e o OpenAI SDK:

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

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

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

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

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

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

# 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:

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

Usando um arquivo .env:

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

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)

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

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

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, na aba Traces.

Acesse seu AI Studio para ver análises e traces em tempo real.

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

AI Gateway

Observabilidade

AI Gateway

Visão geral

Principais benefícios

Observabilidade completa

Confiabilidade integrada

Otimização de custos

Acesso a vários provedores

Pré-requisitos

Instalação

Configuração

Exemplo básico de agente

Agente com ferramentas

Saídas estruturadas

Seleção de modelo

Observabilidade

Primeiros passos

Pré-requisitos

Instale as dependências

Configure o Toqan Router

Exemplo de integração

Streaming

Solução de problemas

Visualize os traces

AI Gateway

Observabilidade

​AI Gateway

​Visão geral

​Principais benefícios

Observabilidade completa

Confiabilidade integrada

Otimização de custos

Acesso a vários provedores

​Pré-requisitos

​Instalação

​Configuração

​Exemplo básico de agente

​Agente com ferramentas

​Saídas estruturadas

​Seleção de modelo

​Observabilidade

​Primeiros passos

​Pré-requisitos

​Instale as dependências

​Configure o Toqan Router

​Exemplo de integração

​Streaming

​Solução de problemas

​Visualize os traces

AI Gateway

Visão geral

Principais benefícios

Pré-requisitos

Instalação

Configuração

Exemplo básico de agente

Agente com ferramentas

Saídas estruturadas

Seleção de modelo

Observabilidade

Primeiros passos

Pré-requisitos

Instale as dependências

Configure o Toqan Router

Exemplo de integração

Streaming

Solução de problemas

Visualize os traces