Combinare strumenti server e client
In questa pagina
Due categorie di strumenti sulla stessa piattaforma
Le API di Grok distinguono due tipi di strumenti fondamentalmente diversi in base alla loro esecuzione. Comprendere questa distinzione è essenziale per progettare architetture robuste.
Strumenti integrati (lato server)
xAI esegue automaticamente questi strumenti sui propri server. Non devi gestire nulla: nessuna esecuzione locale, nessun inoltro dei risultati. Il modello li chiama e riceve i risultati direttamente.
| Strumento | Identificativo | Descrizione |
|---|---|---|
| Web Search | web_search | Ricerca web in tempo reale |
| X Search | x_search | Ricerca su X/Twitter |
| Code Interpreter | code_interpreter | Esecuzione Python in sandbox |
| Collections Search | collections_search | Ricerca nei documenti caricati |
| Remote MCP | mcp | Connessione a server MCP esterni |
Funzioni personalizzate (lato client)
Queste sono le tue funzioni, definite tramite function calling. Il modello restituisce un tool_call, il tuo codice esegue la funzione e tu invii indietro il risultato. Questo è il meccanismo che hai appreso nelle lezioni precedenti.
Combinare entrambi in una singola richiesta
La potenza delle API di Grok risiede nella capacità di mescolare strumenti server e client in un’unica richiesta:
tools = [
# Strumento server — eseguito automaticamente da xAI
{"type": "web_search"},
# Strumento client — eseguito dal tuo codice
{
"type": "function",
"function": {
"name": "save_to_database",
"description": "Salva le informazioni nel database",
"parameters": {
"type": "object",
"properties": {
"key": {"type": "string"},
"value": {"type": "string"}
},
"required": ["key", "value"]
}
}
}
]
Quando il modello riceve questa richiesta, può:
- Usare
web_searchper trovare informazioni (esecuzione automatica lato server) - Chiamare
save_to_databaseper salvare il risultato (ritorno al client)
Il flusso ibrido
Il comportamento varia in base al tipo di strumento:
- Strumento server: il modello chiama lo strumento, xAI lo esegue, il risultato viene integrato automaticamente e il modello prosegue
- Strumento client: il modello restituisce il
tool_callal client, l’esecuzione si interrompe e riprende quando invii il risultato
Quando il modello utilizza entrambi i tipi nella stessa richiesta, gli strumenti server vengono eseguiti per primi (senza il tuo intervento). Successivamente, se il modello ha bisogno anche di uno strumento client, ti restituisce il tool_call con i risultati degli strumenti server già integrati nel suo contesto.
Esempi pratici
Ricerca web + logica di business
# L'utente chiede: "Trova il prezzo del Bitcoin e salvalo"
# Il modello:
# 1. Chiama web_search per trovare il prezzo (lato server, automatico)
# 2. Chiama save_price(symbol="BTC", price=68432) (lato client)
Ricerca su X + notifica
# "Avvisami sui tweet riguardanti il nostro prodotto da ieri"
# Il modello:
# 1. Chiama x_search per trovare i tweet (lato server)
# 2. Chiama send_notification(count=12, summary="...") (lato client)
Code Interpreter + archiviazione
# "Calcola la media di questi dati e salva il risultato"
# Il modello:
# 1. Chiama code_interpreter per il calcolo (lato server)
# 2. Chiama save_result(key="avg", value="42.5") (lato client)
Fatturazione degli strumenti server
Gli strumenti integrati vengono fatturati in due modi:
- Token: consumo standard (input + output)
- Invocazioni: costo fisso per ogni chiamata allo strumento
Il modello può chiamare più strumenti server per una singola richiesta: i costi si sommano. Tienilo a mente quando abiliti web_search: il modello potrebbe eseguire più ricerche per affinare i suoi risultati.
Punti chiave
- Due tipi di strumenti: server (automatici) e client (function calling)
- Gli strumenti server (
web_search,x_search,code_interpreter) vengono eseguiti senza il tuo intervento - Puoi mescolare entrambi i tipi in un’unica richiesta
- Gli strumenti server vengono eseguiti per primi, poi il modello può chiamare le tue funzioni
- Ogni invocazione di uno strumento server è a pagamento (token + costo per chiamata)
- Le citazioni vengono generate automaticamente per i dati provenienti dagli strumenti server