> ## 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 o OpenAI Agents SDK

> Conecte o OpenAI Agents SDK 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)
>
> 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.

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

> [card] Observabilidade completa
>
> Acompanhe cada etapa de 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
>
> Acompanhamento de custos em tempo real e gestão de gastos em todas as suas operações de IA

> [card] 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

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

### Instalação

Instale o OpenAI Agents SDK:

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

> [!WARNING]
>
> 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export OPENAI_AGENTS_DISABLE_TRACING=1
```

Ou desabilite-o no código:

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { setTracingDisabled } from "@openai/agents";

setTracingDisabled(true);
```

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

```bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install openinference-instrumentation-openai-agents opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

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

> [!NOTE]
>
> 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

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

```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=openai-agents-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=openai-agents-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=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 Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/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.

### Captura de agentes e ferramentas

Agentes, ferramentas e modelos são derivados dos spans e renderizados em [Agent Graphs](/docs/pt-BR/ai-studio/observability/agent-graphs.md).

#### Instalação

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


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