Implementazione con l'SDK xAI
In questa pagina
L’SDK nativo xAI
L’SDK xAI è il modo più diretto per utilizzare la modalità multi-agente e l’unico che espone parametri come agent_count, non disponibili negli SDK di terze parti. Se inizi senza vincoli legati a un ecosistema specifico, parti da qui: avrai accesso all’intero set di impostazioni.
Configurazione di base
Inizializzare il client si riduce a tre importazioni e alla lettura della tua chiave API dalle variabili d’ambiente:
import os
from xai_sdk import Client
from xai_sdk.chat import user
client = Client(api_key=os.getenv("XAI_API_KEY"))
La variabile d’ambiente XAI_API_KEY deve contenere la tua chiave API xAI. Non inserire mai la chiave direttamente nel codice: finirebbe nel repository Git, quindi nella sua cronologia, da cui è difficile rimuoverla.
Richiesta con 4 agenti (modalità veloce)
Per una ricerca rapida e mirata, passi agent_count=4 quando crei la chat:
chat = client.chat.create(
model="grok-4.20-multi-agent-0309",
agent_count=4
)
chat.append(user("Confronta nel dettaglio TCP e UDP"))
for response, chunk in chat.stream():
if chunk.content:
print(chunk.content, end="", flush=True)
Nota che consumi la risposta tramite chat.stream(). Questo è il metodo consigliato: senza di esso, il tuo programma si blocca senza dare segni di vita per tutta la durata della ricerca, e nulla ti indica se la richiesta è ancora in esecuzione o se è andata in crash.
Richiesta con 16 agenti (modalità approfondita)
Passare alla modalità approfondita richiede solo di cambiare un valore, ma la richiesta che associ deve essere all’altezza della squadra che stai schierando:
chat = client.chat.create(
model="grok-4.20-multi-agent-0309",
agent_count=16
)
chat.append(user(
"Forniscimi uno stato dell'arte completo sulle architetture RAG nel 2026, "
"confrontando approcci ibridi, prestazioni e costi"
))
for response, chunk in chat.stream():
if chunk.content:
print(chunk.content, end="", flush=True)
Aggiunta di strumenti integrati
Aggiungi gli strumenti con una semplice lista; l’SDK fornisce i costruttori corrispondenti:
from xai_sdk.tools import web_search, x_search
chat = client.chat.create(
model="grok-4.20-multi-agent-0309",
agent_count=4,
tools=[web_search(), x_search()],
include=["verbose_streaming"],
)
chat.append(user("Quali sono gli ultimi annunci di xAI questa settimana?"))
for response, chunk in chat.stream():
if chunk.content:
print(chunk.content, end="", flush=True)
Il parametro include=["verbose_streaming"] modifica ciò che ricevi: le chiamate agli strumenti appaiono in tempo reale mentre gli agenti lavorano, permettendoti di sapere su cosa si concentra la ricerca corrente.
Contenuto cifrato per conversazioni multi-turno
Se prevedi di porre diverse domande di seguito sullo stesso argomento, attiva il contenuto cifrato quando crei la chat:
chat = client.chat.create(
model="grok-4.20-multi-agent-0309",
agent_count=4,
use_encrypted_content=True,
)
Il modello mantiene così lo stato dei sotto-agenti tra un turno e l’altro, rendendo gli scambi prolungati molto più coerenti.
Gestione degli errori
Poiché l’API è in beta, una richiesta può fallire senza che sia colpa tua. Incapsula la chiamata e prevedi una via di fuga:
try:
chat = client.chat.create(
model="grok-4.20-multi-agent-0309",
agent_count=4
)
chat.append(user("La mia domanda"))
for response, chunk in chat.stream():
if chunk.content:
print(chunk.content, end="", flush=True)
except Exception as e:
print(f"Errore multi-agente: {e}")
# Ripiega su un modello standard se necessario
Il commento sull’ultima riga aspetta di essere sostituito con codice reale. In produzione, questo blocco deve effettivamente ripiegare su un modello standard, altrimenti la tua funzionalità smette di funzionare alla prima indisponibilità del servizio multi-agente.
Punti chiave
- L’SDK xAI espone
agent_countper controllare direttamente il numero di agenti - Usa sempre lo streaming per il multi-agente (
.stream()) verbose_streamingrivela le chiamate agli strumenti in tempo realeuse_encrypted_content=Trueper le conversazioni multi-turno- Prevedi sempre la gestione degli errori (API in beta)