Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Compatibilità con l'SDK OpenAI

Lezione 6 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Utilizzo del multi-agent tramite l’SDK OpenAI
  2. Configurazione del client
  3. Controllo del numero di agenti con reasoning.effort
  4. La mappatura effort → agenti
  5. Chat Completions non è supportato
  6. Streaming con l’SDK OpenAI
  7. Vantaggi e limiti di questo approccio
  8. Punti chiave

Utilizzo del multi-agent tramite l’SDK OpenAI

Molti team hanno già costruito il proprio livello di chiamate attorno all’SDK OpenAI, con i suoi wrapper, test e convenzioni di logging. Buone notizie: accedere alla modalità multi-agent di Grok non ti obbliga a riscrivere tutto. xAI espone un’API compatibile con il formato Responses di OpenAI, quindi puoi mantenere il client OpenAI e puntarlo semplicemente all’API di xAI.

Configurazione del client

Ti servono solo due impostazioni: l’URL base di xAI e la tua chiave API xAI.

from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

Da questo momento, utilizzi l’API Responses come al solito, specificando grok-4.20-multi-agent-0309 come modello. Il resto del tuo codice di chiamata rimane invariato.

Controllo del numero di agenti con reasoning.effort

È qui che avviene la traduzione tra i due mondi. Mentre l’SDK xAI espone un agent_count esplicito, l’SDK OpenAI offre solo reasoning.effort: non richiedi quindi un numero di agenti, ma un livello di sforzo che xAI converte in un numero di agenti.

# 4 agenti (basso sforzo)
response = client.responses.create(
    model="grok-4.20-multi-agent-0309",
    reasoning={"effort": "low"},
    input=[{"role": "user", "content": "What are the latest open source models from 2026?"}],
)
print(response.output_text)
# 16 agenti (alto sforzo)
response = client.responses.create(
    model="grok-4.20-multi-agent-0309",
    reasoning={"effort": "high"},
    input=[{"role": "user", "content": "Compare the EU and US AI strategies in 2026"}],
)
print(response.output_text)

La mappatura effort → agenti

Il campo accetta quattro valori, ma produce solo due dimensioni del team: "low" e "medium" utilizzano 4 agenti, mentre "high" e "xhigh" ne utilizzano 16.

Questo dettaglio merita molta attenzione. Passare da low a medium, o da high a xhigh, non cambia il numero di agenti: questi livelli intermedi possono influenzare altri aspetti del comportamento del modello, ma all’interno di ciascuna coppia il team rimane lo stesso. Immagina un’interfaccia in cui offri all’utente quattro livelli di profondità di ricerca: ne percepirebbe solo due, e i tuoi due pulsanti extra confonderebbero soltanto la sua scelta.

Chat Completions non è supportato

Ecco il vincolo che fa inciampare la maggior parte degli sviluppatori al primo tentativo: Chat Completions non è supportato per il multi-agent. Devi usare l’API Responses, ovvero client.responses.create, e non client.chat.completions.create.

# NON FUNZIONA
response = client.chat.completions.create(
    model="grok-4.20-multi-agent-0309",
    messages=[{"role": "user", "content": "..."}],
)

Questa chiamata restituisce un errore. Se il tuo codice esistente si basa interamente su Chat Completions – come accade in molti codebase esistenti – il cambiamento non è solo una sostituzione del nome del modello: devi migrare la chiamata verso un formato di input e output diverso. Valuta bene questo sforzo prima di promettere l’integrazione.

Streaming con l’SDK OpenAI

Lo streaming è comunque disponibile, sempre tramite l’API Responses:

stream = client.responses.create(
    model="grok-4.20-multi-agent-0309",
    reasoning={"effort": "low"},
    input=[{"role": "user", "content": "Summarize this week's tech announcements"}],
    stream=True,
)

for event in stream:
    if hasattr(event, 'delta') and event.delta:
        print(event.delta, end="", flush=True)

Il test hasattr(event, 'delta') vale la pena mantenerlo così com’è: lo stream di eventi dell’API Responses contiene più del solo testo, e leggere ciecamente event.delta su ogni evento solleverebbe un’eccezione.

Vantaggi e limiti di questo approccio

Il vantaggio principale di questa strada è il risparmio di tempo: non installi un altro SDK, i tuoi sviluppatori ottengono una sintassi familiare e passare dai modelli xAI a quelli OpenAI nello stesso codebase diventa banale. Per un team che vuole valutare la modalità multi-agent senza impegnarsi in un progetto completo, è il percorso più breve.

I limiti derivano tutti dalla stessa causa: stai passando attraverso un livello di compatibilità, quindi perdi ciò che è specifico di xAI. Non ottieni agent_count (sostituito dal controllo indiretto tramite reasoning.effort), verbose_streaming, né use_encrypted_content. Inoltre, la mappatura effort → agenti proviene da un’API beta e potrebbe cambiare: se il tuo prodotto dipende specificamente dal numero di agenti utilizzati, l’SDK nativo rimane la scelta più prudente.

Punti chiave

  • L’SDK OpenAI funziona con il multi-agent tramite base_url="https://api.x.ai/v1"
  • Controlli il numero di agenti tramite reasoning.effort (low/medium = 4, high/xhigh = 16)
  • Chat Completions NON è supportato: usa solo l’API Responses
  • Alcuni parametri esclusivi dell’SDK xAI (agent_count, verbose_streaming) non sono disponibili