Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Combinare strumenti server e client

Lezione 8 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Due categorie di strumenti sulla stessa piattaforma
  2. Combinare entrambi in una singola richiesta
  3. Il flusso ibrido
  4. Esempi pratici
  5. Fatturazione degli strumenti server
  6. Punti chiave

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ò:

  1. Usare web_search per trovare informazioni (esecuzione automatica lato server)
  2. Chiamare save_to_database per 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_call al 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