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
- Installa l’SDK. Richiede Python 3.10 o successivo.
pip install openai-agents
export BROADNET_API_KEY='your-broadnet-key'
- 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())
- Eseguilo. L’agente dovrebbe chiamare
get_order_statuse rispondere in base al risultato.
Tre modi per collegare il provider
La documentazione dell’SDK elenca queste opzioni integrate:
- Per agente: passa
OpenAIChatCompletionsModelcomeAgent.model, come sopra. Usalo quando agenti diversi usano provider diversi. - Default globale:
set_default_openai_client(client)rende il tuo client quello predefinito. Abbinalo aset_default_openai_api("chat_completions"). - Per esecuzione: passa un
ModelProviderpersonalizzato inRunConfig(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
OpenAIChatCompletionsModeloset_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_outputvuoto. Il ragionamento conta inmax_tokens. Se impostiModelSettings(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.gatherrichiedono una sessione ciascuno, altrimenti finiscono in coda. Vedi agenti in parallelo a tariffa fissa.
