Integração com o OpenAI Agents SDK

AI Gateway

Roteie suas chamadas de LLM pelo AI Gateway alterando apenas a base URL. Sem dependência de fornecedor: use 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 OpenAI Agents SDK permite uma automação poderosa orientada por IA por meio de conversas estruturadas e chamadas de ferramentas. Ao conectar o Agents SDK 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 OpenAI Agents com:

Observabilidade completa

Acompanhe cada etapa de 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

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

Acesso a múltiplos provedores

Acesse mais de 500 LLMs e mais de 30 provedores por meio de uma integração única e unificada

Pré-requisitos

Antes de integrar o OpenAI Agents SDK ao Toqan Router, certifique-se de ter:

Uma conta no Toqan Router e uma chave de API
Python 3.8 ou superior
O OpenAI Agents SDK instalado

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

Instalação

Instale o OpenAI Agents SDK:

pip install openai-agents openai

Configuração

Configure o OpenAI Agents SDK para usar o AI Gateway do Toqan Router definindo um cliente AsyncOpenAI personalizado:

Python

from openai import AsyncOpenAI
from agents import set_default_openai_client, set_tracing_disabled
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"
)

# Set as default client for all agents
set_default_openai_client(client)

# Disable the SDK's built-in OpenAI tracing exporter for router-only use
set_tracing_disabled(True)

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

Tracing integrado da OpenAI

O OpenAI Agents SDK inclui um tracing integrado que, por padrão, exporta para o dashboard de Traces hospedado pela OpenAI. Quando você usa o AI Gateway do Toqan Router com TOQAN_API_KEY e não configura credenciais de tracing da OpenAI, o SDK pode exibir No API key provided for OpenAI tracing exporter. Exports will be skipped.

Não defina OPENAI_API_KEY apenas para silenciar esse aviso. Isso envia os traces do SDK para o dashboard da OpenAI em vez do Toqan Router. Escolha um destes caminhos: Opção A: desabilitar o tracing integrado da OpenAI no SDK. Use esta opção em exemplos que usam apenas o router, quando você não precisa de traces de agentes no Toqan Router.

export OPENAI_AGENTS_DISABLE_TRACING=1

Ou desabilite-o no código:

TypeScript

import { setTracingDisabled } from "@openai/agents";

setTracingDisabled(true);

Python

from agents import set_tracing_disabled

set_tracing_disabled(True)

Opção B: enviar traces de agentes ao Toqan Router. Mantenha a camada de tracing do SDK habilitada e registre um exporter OpenTelemetry para o Toqan Router antes de executar os agentes:

pip install openinference-instrumentation-openai-agents opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

Python

import os
from opentelemetry import trace as trace_api
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor

exporter = OTLPSpanExporter(
    endpoint="https://router.toqan.ai/eu/v2/otel/v1/traces",
    headers={"Authorization": f"Bearer {os.environ['TOQAN_API_KEY']}"},
)
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))
trace_api.set_tracer_provider(provider)

OpenAIAgentsInstrumentor().instrument(tracer_provider=provider)

A seção Observabilidade abaixo usa o mesmo coletor OTLP do Toqan Router e mostra exemplos completos, incluindo o flush de spans em buffer em scripts curtos.

Exemplo básico de agente

Veja um exemplo completo de criação e execução de um agente OpenAI por meio do Toqan Router:

Python

from openai import AsyncOpenAI
from agents import Agent, Runner, OpenAIResponsesModel, set_default_openai_client, set_tracing_disabled
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"
)
set_default_openai_client(client)
set_tracing_disabled(True)

# Create agent
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant that explains complex concepts simply.",
    model=OpenAIResponsesModel(model="openai/gpt-5.6-sol", openai_client=client)
)

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

Agente com ferramentas

Os OpenAI Agents podem usar ferramentas ao rotear pelo Toqan Router:

Python

from openai import AsyncOpenAI
from agents import Agent, Runner, OpenAIResponsesModel, set_default_openai_client, set_tracing_disabled, function_tool
import os

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

# Define a tool using the @function_tool decorator
@function_tool
def get_weather(location: str) -> str:
    """Get the current weather for a location."""
    return f"The weather in {location} is sunny and 72°F"

# Create agent with tools
agent = Agent(
    name="Weather Assistant",
    instructions="You are a weather assistant. Use the get_weather function to provide weather information.",
    tools=[get_weather],
    model=OpenAIResponsesModel(model="openai/gpt-5.6-sol", openai_client=client)
)

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

Seleção de modelo

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

Python

from openai import AsyncOpenAI
from agents import Agent, Runner, OpenAIResponsesModel, set_default_openai_client, set_tracing_disabled
import os

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

# Use Claude
claude_agent = Agent(
    name="Claude Assistant",
    model=OpenAIResponsesModel(model="anthropic/claude-sonnet-5", openai_client=client),
    instructions="You are a helpful assistant."
)

# Use Gemini
gemini_agent = Agent(
    name="Gemini Assistant",
    model=OpenAIResponsesModel(model="google/gemini-2.5-flash", openai_client=client),
    instructions="You are a helpful assistant."
)

# Use any other model
groq_agent = Agent(
    name="Groq Assistant",
    model=OpenAIResponsesModel(model="groq/qwen/qwen3.8-27b", openai_client=client),
    instructions="You are a helpful assistant."
)

# Run with different models
result = Runner.run_sync(claude_agent, "Explain machine learning")
print(result.final_output)

O mesmo wrapper OpenAIResponsesModel funciona para todos os provedores. Passe a string completa provider/model, e o AI Gateway roteia a solicitação para o provedor correspondente.

Observabilidade

Primeiros passos

Integre os OpenAI Agents à observabilidade do Toqan Router para obter insights completos sobre desempenho dos agentes, uso de tokens, utilização de ferramentas e fluxos de conversa usando OpenTelemetry.

Pré-requisitos

Antes de começar, certifique-se de ter:

Uma conta no Toqan Router e uma chave de API
Chave de API da OpenAI
Python 3.8+

Instalar dependências

pip install openai-agents openinference-instrumentation-openai-agents opentelemetry-sdk opentelemetry-instrumentation opentelemetry-exporter-otlp-proto-http

Configurar 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=openai-agents-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=openai-agents-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=openai-agents-app,service.version=1.0.0
OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>

Armadilhas comuns

Não defina uma base_url personalizada ao usar OTEL. Apontar o cliente OpenAI para o AI Gateway e, ao mesmo tempo, exportar spans resulta em traces duplicados: um do router e outro do exporter OTEL. Use o router quando precisar de roteamento entre múltiplos provedores ou de fallbacks. Use sua OPENAI_API_KEY diretamente quando precisar apenas de observabilidade.
Desabilite o tracing do SDK apenas em execuções somente com o router. OPENAI_AGENTS_DISABLE_TRACING=1 e set_tracing_disabled(True) são adequados quando você quer silenciar o aviso do exporter da OpenAI sem exportar traces de agentes. Não os use com os exemplos de Observabilidade, pois eles impedem que spans no nível do agente cheguem ao Toqan Router.
Envolva as execuções em agent_trace(workflow_name=...). Sem isso, o span raiz recebe o nome "Agent workflow" em todas as execuções, o que torna impossível distinguir os traces.
Chame provider.shutdown() antes de sair em scripts curtos. O BatchSpanProcessor armazena spans em buffer com base em um temporizador e pode não fazer o flush antes de o processo terminar.

Exemplo básico

Python

import os
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from agents import Agent, Runner
from agents import trace as agent_trace

os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://router.toqan.ai/eu/v2/otel"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Bearer {os.environ['TOQAN_API_KEY']}"

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
OpenAIAgentsInstrumentor().instrument(tracer_provider=provider)

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

with agent_trace(workflow_name="Haiku-Workflow"):
    result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
    print(result.final_output)

provider.shutdown()  # flush BatchSpanProcessor before exit

Exemplo avançado com function calling

Python

import os
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from agents import Agent, Runner, function_tool
from agents import trace as agent_trace

os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://router.toqan.ai/eu/v2/otel"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Bearer {os.environ['TOQAN_API_KEY']}"

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
OpenAIAgentsInstrumentor().instrument(tracer_provider=provider)

@function_tool
def get_weather(location: str) -> str:
    """Mock weather function"""
    return f"The weather in {location} is sunny, 72°F"

agent = Agent(
    name="Weather Assistant",
    instructions="You are a weather assistant. Use the get_weather function to provide weather information.",
    tools=[get_weather]
)

with agent_trace(workflow_name="Weather-Workflow"):
    result = Runner.run_sync(agent, "What's the weather like in Boston?")
    print(result.final_output)

provider.shutdown()

Spans personalizados para operações de agentes

Python

import os
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from agents import Agent, Runner
from agents import trace as agent_trace

os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://router.toqan.ai/eu/v2/otel"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Bearer {os.environ['TOQAN_API_KEY']}"

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
OpenAIAgentsInstrumentor().instrument(tracer_provider=provider)

tracer = provider.get_tracer(__name__)

agent = Agent(
    name="Research Assistant",
    instructions="You are a research assistant specialized in data analysis.",
)

with agent_trace(workflow_name="Research-Workflow"):
    with tracer.start_as_current_span("agent-execution") as exec_span:
        result = Runner.run_sync(agent, "Analyze the trends in the uploaded dataset")
        exec_span.set_attribute("execution.status", "completed")
    print("Final output:", result.final_output)

provider.shutdown()

Visualizar traces

Visualize seus traces no AI Studio, na aba Traces.

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

Captura de agentes e ferramentas

Agentes, ferramentas e modelos são derivados dos spans e renderizados em Agent Graphs.

Instalação

pip install openinference-instrumentation-openai-agents openai-agents opentelemetry-sdk opentelemetry-instrumentation opentelemetry-exporter-otlp-proto-http

Configuração

Defina as variáveis de ambiente OTLP e inicialize o tracer provider com o OpenAIAgentsInstrumentor antes de executar quaisquer agentes:

Python

import os
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor

os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://router.toqan.ai/eu/v2/otel"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"]  = "Authorization=Bearer <your-toqan-api-key>"

tracer_provider = TracerProvider()
tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))

OpenAIAgentsInstrumentor().instrument(tracer_provider=tracer_provider)

Exemplos

Agente sem ferramentas: captura agent/Assistant, model/gpt-5.6-sol

Python

import os
from openai import AsyncOpenAI
from agents import Agent, Runner, OpenAIResponsesModel, set_default_openai_client

# Call OpenAI directly; the OpenTelemetry exporter records the spans
client = AsyncOpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
)
set_default_openai_client(client)

agent = Agent(
    name="Assistant",
    instructions="Be extremely concise.",
    model=OpenAIResponsesModel(model="gpt-5.6-sol", openai_client=client),
)

result = Runner.run_sync(agent, "What is the capital of France?")
print(result.final_output)

Agente com uma única ferramenta: captura agent/Weather Assistant, tool/get_weather, model/gpt-5.6-sol

Python

import os
from openai import AsyncOpenAI
from agents import Agent, Runner, OpenAIResponsesModel, set_default_openai_client, function_tool

# Call OpenAI directly; the OpenTelemetry exporter records the spans
client = AsyncOpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
)
set_default_openai_client(client)

@function_tool
def get_weather(location: str) -> str:
    """Get weather for a location."""
    data = {"tokyo": "Sunny, 22°C", "paris": "Cloudy, 15°C", "new york": "Rainy, 18°C"}
    return data.get(location.lower(), f"No data for {location}")

agent = Agent(
    name="Weather Assistant",
    instructions="Use get_weather to answer weather questions.",
    tools=[get_weather],
    model=OpenAIResponsesModel(model="gpt-5.6-sol", openai_client=client),
)

result = Runner.run_sync(agent, "What's the weather in Tokyo?")
print(result.final_output)

Fluxo de trabalho multiagente com handoff: captura agent/Assistant, agent/Spanish Assistant, tool/random_number_tool, model/gpt-5.6-sol

Python

import os
import random
from openai import AsyncOpenAI
from agents import Agent, Runner, OpenAIResponsesModel, set_default_openai_client, function_tool, handoff, trace as agent_trace
from agents.extensions import handoff_filters
from agents import HandoffInputData

# Call OpenAI directly; the OpenTelemetry exporter records the spans
client = AsyncOpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
)
set_default_openai_client(client)

@function_tool
def random_number_tool(max: int) -> int:
    """Return a random integer between 0 and the given maximum."""
    return random.randint(0, max)

def spanish_handoff_message_filter(handoff_message_data: HandoffInputData) -> HandoffInputData:
    handoff_message_data = handoff_filters.remove_all_tools(handoff_message_data)
    history = (
        tuple(handoff_message_data.input_history[2:])
        if isinstance(handoff_message_data.input_history, tuple)
        else handoff_message_data.input_history
    )
    return HandoffInputData(
        input_history=history,
        pre_handoff_items=tuple(handoff_message_data.pre_handoff_items),
        new_items=tuple(handoff_message_data.new_items),
    )

spanish_agent = Agent(
    name="Spanish Assistant",
    instructions="You only speak Spanish and are extremely concise.",
    handoff_description="A Spanish-speaking assistant.",
    model=OpenAIResponsesModel(model="gpt-5.6-sol", openai_client=client),
)

first_agent = Agent(
    name="Assistant",
    instructions="Be extremely concise.",
    tools=[random_number_tool],
    model=OpenAIResponsesModel(model="gpt-5.6-sol", openai_client=client),
)

second_agent = Agent(
    name="Assistant",
    instructions="Be helpful. If the user speaks Spanish, handoff to the Spanish assistant.",
    handoffs=[handoff(spanish_agent, input_filter=spanish_handoff_message_filter)],
    model=OpenAIResponsesModel(model="gpt-5.6-sol", openai_client=client),
)

async def run_workflow():
    with agent_trace(workflow_name="Multi-Agent Workflow"):
        result = await Runner.run(first_agent, input="Hi, my name is Sora.")
        result = await Runner.run(
            first_agent,
            input=result.to_input_list() + [
                {"content": "Generate a random number between 0 and 100.", "role": "user"}
            ],
        )
        result = await Runner.run(
            second_agent,
            input=result.to_input_list() + [
                {"content": "Por favor habla en español. ¿Cuál es mi nombre?", "role": "user"}
            ],
        )
    print(result.final_output)

# In Jupyter notebooks (async supported natively)
await run_workflow()

# In regular Python scripts
import asyncio
asyncio.run(run_workflow())

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 múltiplos provedores

Pré-requisitos

Instalação

Configuração

Tracing integrado da OpenAI

Exemplo básico de agente

Agente com ferramentas

Seleção de modelo

Observabilidade

Primeiros passos

Pré-requisitos

Instalar dependências

Configurar o Toqan Router

Armadilhas comuns

Exemplo básico

Exemplo avançado com function calling

Spans personalizados para operações de agentes

Visualizar traces

Captura de agentes e ferramentas

Instalação

Configuração

Exemplos

AI Gateway

Observabilidade

​AI Gateway

​Visão geral

​Principais benefícios

Observabilidade completa

Confiabilidade integrada

Otimização de custos

Acesso a múltiplos provedores

​Pré-requisitos

​Instalação

​Configuração

​Tracing integrado da OpenAI

​Exemplo básico de agente

​Agente com ferramentas

​Seleção de modelo

​Observabilidade

​Primeiros passos

​Pré-requisitos

​Instalar dependências

​Configurar o Toqan Router

​Armadilhas comuns

​Exemplo básico

​Exemplo avançado com function calling

​Spans personalizados para operações de agentes

​Visualizar traces

​Captura de agentes e ferramentas

​Instalação

​Configuração

​Exemplos

AI Gateway

Visão geral

Principais benefícios

Pré-requisitos

Instalação

Configuração

Tracing integrado da OpenAI

Exemplo básico de agente

Agente com ferramentas

Seleção de modelo

Observabilidade

Primeiros passos

Pré-requisitos

Instalar dependências

Configurar o Toqan Router

Armadilhas comuns

Exemplo básico

Exemplo avançado com function calling

Spans personalizados para operações de agentes

Visualizar traces

Captura de agentes e ferramentas

Instalação

Configuração

Exemplos