BroadRouter

Usare l’OpenAI Agents SDK con BroadNet Inference

Aggiornato

Crea un client AsyncOpenAI con base_url https://inference.broadnet.ai/v1 e la tua chiave BroadNet, avvolgilo in OpenAIChatCompletionsModel con un ID di modello come broadnet/glm-5.3 e passa quel modello al tuo Agent. Chiama set_tracing_disabled(True), a meno che tu non abbia una chiave OpenAI separata per il tracing.

L’OpenAI Agents SDK è un framework Python per agenti con strumenti, handoff e guardrail. La sua documentazione spiega come collegare provider diversi da OpenAI. Per un’API compatibile con OpenAI come BroadNet Inference, passi all’SDK il tuo client AsyncOpenAI e usi la classe di modello per Chat Completions. L’SDK usa di default la Responses API, che molti provider non servono.

Configurazione

  1. Installa l’SDK. Richiede Python 3.10 o successivo.
pip install openai-agents
export BROADNET_API_KEY='your-broadnet-key'
  1. Crea il client, il modello e l’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. Eseguilo. L’agente dovrebbe chiamare get_order_status e rispondere in base al risultato.

Tre modi per collegare il provider

La documentazione dell’SDK elenca queste opzioni integrate:

  • Per agente: passa OpenAIChatCompletionsModel come Agent.model, come sopra. Usalo quando agenti diversi usano provider diversi.
  • Default globale: set_default_openai_client(client) rende il tuo client quello predefinito. Abbinalo a set_default_openai_api("chat_completions").
  • Per esecuzione: passa un ModelProvider personalizzato in RunConfig(model_provider=...).

Il default globale ha questo aspetto:

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

Con le sole variabili d’ambiente, imposta OPENAI_BASE_URL=https://inference.broadnet.ai/v1 e OPENAI_API_KEY con la tua chiave BroadNet, poi fai le stesse chiamate a set_default_openai_api e set_tracing_disabled.

Quando passi per Chat Completions, secondo la documentazione dell’SDK i campi che esistono solo nella Responses API, come previous_response_id, conversation_id e prompt, vengono scartati senza avviso. Per ottenere invece un errore, imposta strict_feature_validation=True su OpenAIProvider. Gestisci lo stato della conversazione nel tuo codice, per esempio passando la lista di input del risultato precedente all’esecuzione successiva. Gli strumenti ospitati da OpenAI, come web search e file search, non esistono sugli altri provider. Usa function_tool per tutto ciò che l’agente deve chiamare.

Tracing

Il tracing è attivo di default e invia le tracce a OpenAI. La documentazione dell’SDK dice che, senza una chiave API di platform.openai.com, devi disattivarlo con set_tracing_disabled() o configurare un altro processore di tracing. Se hai una chiave OpenAI, puoi lasciare attivo il tracing e passarla con set_tracing_export_api_key(...). L’SDK la usa solo per caricare le tracce. La tua chiave BroadNet non funziona a questo scopo.

Quale modello scegliere

Tipo di agente Modello Note
Agenti che usano strumenti GLM 5.3 Strumenti e output strutturato indicati; contesto da 1M
Input di immagini con strumenti Qwen3.8 27B Contesto da 262K; testato in arabo
Agenti di lunga durata a tariffa fissa DeepSeek V4.1 Flash Piani illimitati; strumenti non indicati da BroadNet

La documentazione dell’SDK avverte che alcuni provider non supportano gli output strutturati con JSON schema. Se imposti output_type su un agente, usa GLM 5.3 o Qwen3.8 27B. Confronta i prezzi nella pagina dei prezzi.

Risoluzione dei problemi

  • 401. La chiave BroadNet è sbagliata, scaduta o ha esaurito la quota a consumo. Gli errori di tracing nei log sono un’altra cosa: indicano che il tracing è ancora attivo senza una chiave OpenAI.
  • 404 o “not found”. Probabilmente stai usando la Responses API. Usa OpenAIChatCompletionsModel o set_default_openai_api("chat_completions"). Se è già impostato, verifica che l’ID del modello corrisponda esattamente a quello di BroadNet. I modelli a pagamento richiedono una ricarica; il credito di $5 copre Gemma 4 VL 26B e i due modelli Transcribe.
  • final_output vuoto. Il ragionamento conta in max_tokens. Se imposti ModelSettings(max_tokens=...), alzalo. Perché le risposte arrivano vuote.
  • 429. Una chiave a consumo consente 30 richieste al minuto e 4 contemporanee. Ogni giro di chiamata a uno strumento è una nuova richiesta. Vedi errori e nuovi tentativi.
  • Agenti paralleli su un piano. Una sessione del piano illimitato esegue una richiesta alla volta. Gli agenti avviati insieme con asyncio.gather richiedono una sessione ciascuno, altrimenti finiscono in coda. Vedi agenti in parallelo a tariffa fissa.

Domande frequenti

Perché l’Agents SDK mi restituisce errori 404 con una base URL personalizzata?

L’SDK usa per impostazione predefinita la Responses API, mentre BroadNet serve chat completions. Usa OpenAIChatCompletionsModel, oppure chiama set_default_openai_api("chat_completions") se configuri il client tramite variabili d’ambiente.

Perché l’Agents SDK segnala errori sul tracing?

Il tracing carica i dati su OpenAI e richiede una chiave di platform.openai.com. La documentazione dell’SDK consiglia set_tracing_disabled() se non ne hai una, oppure un altro processore di tracing.

Posso configurare l’Agents SDK solo con le variabili d’ambiente?

Sì. Imposta OPENAI_BASE_URL su https://inference.broadnet.ai/v1 e OPENAI_API_KEY con la tua chiave BroadNet, poi chiama set_default_openai_api("chat_completions") e set_tracing_disabled(True). OPENAI_DEFAULT_MODEL imposta il modello per gli agenti che non ne indicano uno.

Quante sessioni del piano servono per un’esecuzione multi-agente?

Una per ogni richiesta eseguita contemporaneamente. Gli handoff eseguono un agente dopo l’altro, quindi basta una sessione. Gli agenti eseguiti in parallelo con asyncio.gather richiedono una sessione ciascuno.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity