---
title: "OpenAI Agents SDK com provedor compatível com a OpenAI"
description: "Use o OpenAI Agents SDK para Python com a BroadNet Inference via AsyncOpenAI e OpenAIChatCompletionsModel, e desative o tracing que exige uma chave da OpenAI."
url: https://broadrouter.com/pt/guides/openai-agents-sdk-custom-provider/
lang: pt-BR
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Traduzido do inglês com ajuda de IA. [Leia o original em inglês](https://broadrouter.com/guides/openai-agents-sdk-custom-provider/) (atualizado em 2026-11-16).

# Rodar o OpenAI Agents SDK na BroadNet Inference

Atualizado em 2026-11-16

Crie um cliente AsyncOpenAI com base\_url https://inference.broadnet.ai/v1 e a sua chave da BroadNet, envolva-o em OpenAIChatCompletionsModel com um ID de modelo como broadnet/glm-5.3 e passe esse modelo para o seu Agent. Chame set\_tracing\_disabled(True), a menos que você tenha uma chave da OpenAI separada para o tracing.

O OpenAI Agents SDK é um framework Python para agentes com ferramentas, handoffs e guardrails. A documentação dele explica como conectar provedores que não são da OpenAI. Para uma API compatível com a OpenAI, como a BroadNet Inference, você entrega ao SDK o seu próprio cliente `AsyncOpenAI` e usa a classe de modelo de Chat Completions. Por padrão, o SDK usa a Responses API, que muitos provedores não servem.

## Configuração

1.  **Instale o SDK.** Ele exige Python 3.10 ou mais recente.

```bash
pip install openai-agents
export BROADNET_API_KEY='your-broadnet-key'
```

2.  **Crie o cliente, o modelo e o agente.**

```python
import asyncio
import os

from agents import (
    Agent,
    AsyncOpenAI,
    OpenAIChatCompletionsModel,
    Runner,
    function_tool,
    set_tracing_disabled,
)

set_tracing_disabled(disabled=True)  # tracing needs a platform.openai.com key

client = AsyncOpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)

model = OpenAIChatCompletionsModel(model="broadnet/glm-5.3", openai_client=client)

@function_tool
def get_order_status(order_id: str) -> str:
    """Look up an order."""
    return f"Order {order_id}: shipped"

agent = Agent(
    name="Support agent",
    instructions="Answer briefly. Use tools when you need order data.",
    model=model,
    tools=[get_order_status],
)

async def main():
    result = await Runner.run(agent, "Where is order 4471?")
    print(result.final_output)

asyncio.run(main())
```

3.  **Rode.** O agente deve chamar `get_order_status` e responder com base no resultado.

## Três formas de conectar o provedor

A documentação do SDK lista estas opções nativas:

-   **Por agente:** passe `OpenAIChatCompletionsModel` como `Agent.model`, como acima. Use quando agentes diferentes usam provedores diferentes.
-   **Padrão global:** `set_default_openai_client(client)` torna o seu cliente o padrão. Combine com `set_default_openai_api("chat_completions")`.
-   **Por execução:** passe um `ModelProvider` personalizado em `RunConfig(model_provider=...)`.

O padrão global fica assim:

```python
import os
from agents import (
    Agent,
    AsyncOpenAI,
    set_default_openai_api,
    set_default_openai_client,
    set_tracing_disabled,
)

client = AsyncOpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
set_default_openai_client(client, use_for_tracing=False)
set_default_openai_api("chat_completions")
set_tracing_disabled(True)

agent = Agent(name="Assistant", instructions="Be brief.", model="broadnet/glm-5.3")
```

Só com variáveis de ambiente, defina `OPENAI_BASE_URL=https://inference.broadnet.ai/v1` e `OPENAI_API_KEY` com a sua chave da BroadNet, depois faça as mesmas chamadas a `set_default_openai_api` e `set_tracing_disabled`.

Quando você passa por Chat Completions, a documentação do SDK diz que ele descarta em silêncio os campos que só existem na Responses API, como `previous_response_id`, `conversation_id` e `prompt`. Para receber um erro em vez disso, defina `strict_feature_validation=True` em `OpenAIProvider`. Guarde o estado da conversa no seu próprio código, por exemplo passando a lista de entrada do resultado anterior para a próxima execução. Ferramentas hospedadas da OpenAI, como web search e file search, não existem em outros provedores. Use `function_tool` para tudo o que o agente precisar chamar.

## Tracing

O tracing vem ligado por padrão e envia os traces para a OpenAI. A documentação do SDK diz que, sem uma chave de API do platform.openai.com, você deve desativá-lo com `set_tracing_disabled()` ou configurar outro processador de tracing. Se você tiver uma chave da OpenAI, pode manter o tracing ligado e passar essa chave com `set_tracing_export_api_key(...)`. O SDK a usa só para enviar os traces. A sua chave da BroadNet não serve para isso.

## Qual modelo escolher

| Tipo de agente | Modelo | Observações |
| --- | --- | --- |
| Agentes que usam ferramentas | [GLM 5.3](https://broadrouter.com/pt/models/glm-5.3/) | Ferramentas e saída estruturada listadas; contexto de 1M |
| Entrada de imagens com ferramentas | [Qwen3.8 27B](https://broadrouter.com/pt/models/qwen3.8-27b/) | Contexto de 262K; testado em árabe |
| Agentes de longa duração com preço fixo | [DeepSeek V4.1 Flash](https://broadrouter.com/pt/models/deepseek-v4.1-flash/) | Planos ilimitados; ferramentas não listadas pela BroadNet |

A documentação do SDK avisa que alguns provedores não suportam saídas estruturadas com JSON schema. Se você definir `output_type` em um agente, use GLM 5.3 ou Qwen3.8 27B. Compare os preços na [página de preços](https://broadrouter.com/pt/pricing/).

## Solução de problemas

-   **401.** A chave da BroadNet está errada, expirou ou ficou sem cota de pagamento por uso. Erros de tracing nos logs são outra coisa: indicam que o tracing continua ligado sem uma chave da OpenAI.
-   **404 ou “not found”.** Provavelmente você está na Responses API. Use `OpenAIChatCompletionsModel` ou `set_default_openai_api("chat_completions")`. Se isso já estiver definido, confira se o ID do modelo é exatamente o da BroadNet. Os modelos pagos exigem uma recarga; o crédito de $5 cobre o Gemma 4 VL 26B e os dois modelos Transcribe.
-   **`final_output` vazio.** O raciocínio conta em `max_tokens`. Se você define `ModelSettings(max_tokens=...)`, aumente o valor. [Por que as respostas voltam vazias](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/).
-   **429.** Uma chave de pagamento por uso permite 30 requisições por minuto e 4 ao mesmo tempo. Cada ida e volta de ferramenta é uma nova requisição. Veja [erros e novas tentativas](https://broadrouter.com/pt/guides/errors-and-retries/).
-   **Agentes em paralelo num plano.** Uma [sessão do plano ilimitado](https://broadrouter.com/pt/guides/unlimited-llm-api-sessions/) roda uma requisição por vez. Agentes iniciados juntos com `asyncio.gather` precisam de uma sessão cada, senão entram na fila. Veja [agentes em paralelo com preço fixo](https://broadrouter.com/pt/blog/run-parallel-coding-agents-flat-rate/).

## Termos neste guia

[Tool calling (chamada de ferramentas)](https://broadrouter.com/pt/glossary/tool-calling/)

Tool calling, também chamado de function calling ou chamada de ferramentas, é um recurso de APIs de LLM em que o modelo devolve um pedido estruturado para executar uma função definida pelo desenvolvedor, com argumentos JSON. A aplicação executa a função e devolve o resultado; o modelo nunca executa código sozinho.

[Pagamento por uso (pay-as-you-go)](https://broadrouter.com/pt/glossary/pay-as-you-go/)

Pagamento por uso é um modelo de preço em que você paga só pelo que usa, medido por unidade, como tokens, requisições ou minutos de áudio, sem assinatura nem compromisso mínimo. A maioria das APIs de LLM cobra assim, a partir de um saldo pré-pago ou de uma fatura periódica.

[Chat Completions API](https://broadrouter.com/pt/glossary/chat-completions-api/)

A Chat Completions API é o endpoint HTTP da OpenAI, POST /v1/chat/completions, que recebe o nome de um modelo e uma lista de mensagens marcadas com papéis e devolve a próxima mensagem do modelo. O formato da requisição e da resposta virou o padrão comum que provedores e SDKs compatíveis com a OpenAI reutilizam.

[Concorrência (concurrency)](https://broadrouter.com/pt/glossary/concurrency/)

Concorrência é o número de requisições que um cliente tem em andamento ao mesmo tempo. APIs de LLM muitas vezes a limitam por chave ou por plano, separadamente das requisições por minuto, porque cada requisição aberta ocupa capacidade de GPU até a resposta terminar.

[Guardrails (barreiras de proteção para LLM)](https://broadrouter.com/pt/glossary/guardrails/)

Guardrails são checagens que uma aplicação executa em volta de uma chamada a um modelo de linguagem para mantê-la dentro de limites definidos. Guardrails de entrada filtram o que entra no modelo, os de saída verificam o que sai e os de ferramenta validam ações antes que rodem. Uma checagem que falha bloqueia, reescreve ou sinaliza a requisição.

[Rate limit (limite de taxa)](https://broadrouter.com/pt/glossary/rate-limit/)

Um rate limit é um teto que uma API impõe a quanto um cliente pode usá-la em um intervalo de tempo, como requisições por minuto ou tokens por minuto. As requisições acima do limite são recusadas, normalmente com HTTP 429 Too Many Requests, até que o uso volte a ficar abaixo dele.

[Saída estruturada (structured output)](https://broadrouter.com/pt/glossary/structured-output/)

Saída estruturada é um recurso de APIs de LLM que restringe a resposta de um modelo a um formato definido pelo desenvolvedor, normalmente um JSON Schema, para que o código consiga interpretá-la de forma confiável. É mais rigorosa que o JSON mode, que garante um JSON válido, mas não uma estrutura específica.

[API compatível com a OpenAI](https://broadrouter.com/pt/glossary/openai-compatible-api/)

Uma API compatível com a OpenAI é uma API HTTP que aceita os mesmos formatos de requisição e de resposta da API da OpenAI, como POST /v1/chat/completions, de modo que SDKs e ferramentas da OpenAI podem usá-la trocando só a base URL, a chave de API e o nome do modelo.

## Perguntas frequentes

### Por que o Agents SDK dá erro 404 com uma base URL personalizada?

O SDK usa a Responses API por padrão, e a BroadNet serve chat completions. Use OpenAIChatCompletionsModel, ou chame set\_default\_openai\_api("chat\_completions") se você configura o cliente por variáveis de ambiente.

### Por que o Agents SDK reclama do tracing?

O tracing envia dados para a OpenAI e exige uma chave do platform.openai.com. A documentação do SDK recomenda set\_tracing\_disabled() quando você não tem uma, ou um outro processador de tracing.

### Dá para configurar o Agents SDK só com variáveis de ambiente?

Sim. Defina OPENAI\_BASE\_URL como https://inference.broadnet.ai/v1 e OPENAI\_API\_KEY com a sua chave da BroadNet, depois chame set\_default\_openai\_api("chat\_completions") e set\_tracing\_disabled(True). OPENAI\_DEFAULT\_MODEL define o modelo dos agentes que não indicam um.

### Quantas sessões do plano uma execução com vários agentes precisa?

Uma por requisição que roda ao mesmo tempo. Os handoffs rodam um agente depois do outro, então uma sessão basta. Agentes rodando em paralelo com asyncio.gather precisam de uma sessão cada.

## Guias relacionados

-   [Como usar o SDK Python da OpenAI com a BroadNet Inference](https://broadrouter.com/pt/guides/openai-python-sdk/)
-   [Como funcionam os planos de API de LLM ilimitada para agentes](https://broadrouter.com/pt/guides/unlimited-llm-api-sessions/)
-   [Por que um modelo de raciocínio devolve uma resposta vazia](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/)
-   [Como rotear o LiteLLM para a BroadNet Inference (SDK e proxy)](https://broadrouter.com/pt/guides/litellm-proxy-custom-provider/)
-   [Todas as ferramentas que funcionam com a BroadNet Inference (em inglês)](https://broadrouter.com/integrations/): SDKs, agentes de programação, interfaces de chat e ferramentas de automação, com as configurações exatas de cada uma

Teste com a sua carga de trabalho real. Contas novas começam com US$ 5 de crédito para Gemma e transcrição. DeepSeek, GLM e Qwen3.8 exigem uma recarga.

[Começar](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-guides-openai-agents-sdk-custom-provider&utm_content=page-cta) ·

**Fontes**

-   [Documentação do OpenAI Agents SDK, Models (provedores que não são da OpenAI) (conferido em 2026-11-14)](https://openai.github.io/openai-agents-python/models/)
-   [PyPI, pacote openai-agents (0.24, Python 3.10+, conferido em 2026-11-14)](https://pypi.org/project/openai-agents/)
-   [Referência da API da BroadNet Inference (em inglês)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-guides-openai-agents-sdk-custom-provider&utm_content=sources)
