Strumenti server e chiamata di funzioni
In questa pagina
Corso aggiornato il 2 novembre 2026 sulla base della documentazione xAI: lo sconto batch è del 20% sui modelli di testo idonei (non del 50%), gli esempi seguono l’API REST e l’SDK ufficiale
xai-sdk(client.batch.*; l’API Batch di xAI non utilizza il formato OpenAI, l’SDK OpenAI non si applica) e l’API Responses ha la priorità rispetto a Chat Completions, un endpoint legacy presso xAI. Fonti: Batch API · Riferimento REST · Prezzi Batch.
Arricchire i batch con gli strumenti
Le richieste batch non si limitano al testo grezzo. Anche gli strumenti server e la chiamata di funzioni funzionano in modalità asincrona, con una distinzione fondamentale: i primi vengono eseguiti durante l’elaborazione da parte di xAI, mentre i secondi restituiscono il controllo a te.
Strumenti lato server
Gli strumenti server vengono eseguiti durante l’elaborazione del batch, esattamente come in tempo reale: Grok chiama lo strumento, riceve il risultato, lo integra nel suo ragionamento e il batch restituisce la risposta finale. Funzionano con l’API Responses.
Ricerca Web
{"custom_id": "news-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "What are the latest developments in quantum computing?"}], "tools": [{"type": "web_search"}]}}
In modalità batch, la ricerca web serve ad arricchire i dati: verificare informazioni, raccogliere fatti recenti, confrontare profili con fonti online.
Ricerca su X
Lo strumento x_search interroga i post su X, utile per tracciare il sentiment su un argomento o un brand:
{"custom_id": "x-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "What is the dominant sentiment on X regarding this product launch?"}], "tools": [{"type": "x_search"}]}}
Esecuzione di codice
Grok può scrivere ed eseguire codice Python in un ambiente isolato. Nell’API Responses, lo strumento si chiama code_interpreter (l’SDK xAI lo denomina code_execution):
{"custom_id": "calc-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Calculate the 3-point moving average for this data: [12, 15, 18, 14, 22, 19, 25, 28, 30, 27]"}], "tools": [{"type": "code_interpreter"}]}}
L’esecuzione del codice è rilevante per calcoli esatti, statistiche e trasformazioni di dati che il modello gestirebbe in modo meno affidabile basandosi sulla memoria.
Server MCP remoti
Lo strumento mcp connette Grok a un server MCP remoto, descritto nella richiesta stessa: non è necessaria alcuna configurazione preliminare dell’account. server_url e server_label sono obbligatori; allowed_tools limita gli strumenti esposti e authorization passa un token al server. Sono accettati solo i trasporti Streamable HTTP e SSE.
{"custom_id": "mcp-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "What does the xai-sdk-python repository do?"}], "tools": [{"type": "mcp", "server_label": "deepwiki", "server_url": "https://mcp.deepwiki.com/mcp"}]}}
Senza allowed_tools, tutte le definizioni degli strumenti del server vengono iniettate nel contesto del modello e fatturate come token di input su ogni richiesta batch: su 50.000 richieste, limitare l’elenco ripaga rapidamente.
Chiamata di funzioni lato client
La chiamata di funzioni è uno strumento lato client: Grok produce una chiamata di funzione strutturata, ma è il tuo codice a eseguirla. Nel batch, il modello restituisce queste chiamate nei suoi risultati, per un’elaborazione offline.
Definizioni delle funzioni
Nell’API Responses, dichiara la funzione in modo piatto, con name, description e parameters al livello superiore. tool_choice: "required" forza il modello a chiamare almeno uno strumento, il che è adatto all’estrazione:
{"custom_id": "extract-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Extract the contact: Jean Dupont, 01 23 45 67 89, [email protected]"}], "tools": [{"type": "function", "name": "save_contact", "description": "Saves a contact extracted from text", "parameters": {"type": "object", "properties": {"name": {"type": "string"}, "phone": {"type": "string"}, "email": {"type": "string"}}, "required": ["name"]}}], "tool_choice": "required"}}
Elaborazione dei risultati
Con l’SDK, leggi le chiamate di funzione in tool_calls di ogni risultato riuscito:
import json
for r in page.succeeded:
for call in r.response.tool_calls:
if call.function.name == "save_contact":
contact = json.loads(call.function.arguments)
save_to_database(r.batch_request_id, contact)
La chiamata di funzioni in batch è ideale per l’estrazione strutturata: definisci lo schema dei dati, Grok legge i documenti e produce le chiamate, quindi le elabori in blocco.
Combinare gli strumenti
Puoi combinare più strumenti server in una singola richiesta:
{"custom_id": "multi-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Find the Bitcoin closing price for the last seven days and calculate its change"}], "tools": [{"type": "web_search"}, {"type": "code_interpreter"}]}}
Grok utilizza gli strumenti nell’ordine che ritiene più rilevante: qui, ricerca web per ottenere i dati, poi esecuzione del codice per il calcolo.
Limitazioni degli strumenti nel batch
- Gli strumenti server estendono il tempo di elaborazione di ogni richiesta e, di conseguenza, del batch
- Le richieste con ricerca dipendono da ciò che le fonti pubblicano al momento dell’elaborazione, non al momento dell’invio
- La chiamata di funzioni effettua un solo round trip per richiesta: per continuare, invia una nuova richiesta batch contenente la conversazione e i risultati delle tue funzioni
- Le definizioni degli strumenti MCP non filtrate gonfiano ogni richiesta
Punti chiave
- Gli strumenti server (web, X, codice, MCP) vengono eseguiti da xAI durante l’elaborazione, tramite l’API Responses
- Descrivi un server MCP nella richiesta (
server_url,server_label), senza configurazione preliminare - La chiamata di funzioni restituisce chiamate strutturate che esegui lato client
- Uno scambio multi-turno richiede una nuova richiesta batch per ogni turno
- Limita gli strumenti esposti per evitare di pagare le loro definizioni su ogni richiesta