BroadRouter

Rodar o OpenAI Agents SDK na BroadNet Inference

Atualizado em

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.
pip install openai-agents
export BROADNET_API_KEY='your-broadnet-key'
  1. Crie o cliente, o modelo e o agente.
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())
  1. 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:

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 Ferramentas e saída estruturada listadas; contexto de 1M
Entrada de imagens com ferramentas Qwen3.8 27B Contexto de 262K; testado em árabe
Agentes de longa duração com preço fixo 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.

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.
  • 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.
  • Agentes em paralelo num plano. Uma sessão do plano ilimitado 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.

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.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity