API Grok 4.6: dalla prima chiamata a un agente con strumenti

Come si configura l’API Grok 4.6 in Python?

Per iniziare, ti serviranno una chiave API di SpaceXAI e l’installazione di xai-sdk.

Ottenere una chiave API da console.x.ai

Per creare una chiave API di Grok 4.6, navighiamo alla pagina di creazione delle chiavi API della console SpaceX AI. Quindi clicchiamo sul pulsante Create API Key in alto a destra.

Il modulo di creazione della chiave API è semplice. Diamo alla chiave un nome per riconoscere a quale progetto appartiene. Consiglio inoltre di impostare sempre una data di scadenza per le chiavi API come rete di sicurezza nel caso vengano compromesse.

Una volta generata la chiave, la copiamo e la incolliamo in un file chiamato .env che creiamo nella stessa cartella in cui scriveremo gli script Python. In questo modo è facile caricare la chiave nello script senza inserirla nel file di codice, evitando di esporla accidentalmente quando condividiamo o carichiamo il codice nel cloud.

Il file .env dovrebbe contenere quanto segue:

XAI_API_KEY=replace_with_the_api_key

Installare xai-sdk e caricare la chiave API SpaceXAI

Per connetterci a SpaceXAI con la chiave API, usiamo il pacchetto xai-sdk. È buona pratica creare un ambiente separato per ogni progetto per evitare conflitti tra pacchetti Python di progetti diversi. Per farlo, useremo Anaconda con il seguente comando:

conda create -yn grok-46 python=3.10
``` 
This creates an environment named grok-46 that we can activate using:
```bash
conda activate grok-46

Una volta attivo, possiamo installare i pacchetti che vogliamo. Per ora, iniziamo con:

• xai-sdk: Il pacchetto ufficiale SpaceXAI usato per effettuare richieste alla loro API.

• python-dotenv: Un pacchetto di utilità che semplifica il caricamento della chiave API dal file .env.

Per installarli, usiamo il comando:

pip install xai-sdk python-dotenv

Ecco come possiamo caricare la chiave API e creare un Client SpaceXAI in Python:

from dotenv import load_dotenv
from xai_sdk import Client

load_dotenv()

client = Client()

Nota che questo codice non effettua ancora alcuna richiesta. Vediamo come farlo tra poco.

Acquistare crediti per l’API SpaceXAI

Per usare l’API Grok 4.6, dobbiamo anche acquistare crediti sulla loro piattaforma API. Senza crediti, le richieste verranno rifiutate. Per farlo, vai su Credits in fondo alla sidebar, clicca su Add credits e aggiungi l’importo desiderato.

Quanto costa Grok 4.6 via API?

Le richieste a Grok 4.6 sono fatturate per token. Il prezzo base è 2 $ per milione di token in input e 6 $ per milione di token in output.

È importante notare che Grok 4.6 è un modello di ragionamento. Il ragionamento avviene come auto-dialogo e consuma token, fatturati come token di output. Più avanti vedremo come controllare la quantità di ragionamento che il modello esegue per una data richiesta.

I token in cache costano molto meno, solo 0,5 $ per milione di token.

Come vedremo, Grok ha tre strumenti integrati fatturati separatamente dai token: ricerca web, ricerca su X ed esecuzione di codice. Tutti sono prezzati a 5,00 $ per 1.000 chiamate.

Per i contesti lunghi, va notato che tutti i token nei prompt che superano la soglia dei 200K sono fatturati al doppio della tariffa.

Come effettuare la tua prima chiamata API a Grok 4.6?

Partiamo dal codice precedente per usare il client SpaceXAI e inviare una richiesta a Grok 4.6.

Per inviare una richiesta a Grok 4.6, inizializziamo una sessione di chat verso grok-4.6 con client.chat.create() e aggiungiamo il nostro prompt alla cronologia della conversazione usando chat.append(user()).

Infine, chiamando chat.sample() inviamo la conversazione al modello per generare una risposta, che visualizziamo stampando response.content.

from dotenv import load_dotenv
from xai_sdk import Client
from xai_sdk.chat import user

load_dotenv()

client = Client()

chat = client.chat.create(model="grok-4.6")
chat.append(user("Explain how the Transformer attention mechanism works using a simple analogy."))

response = chat.sample()
print(response.content)

Usando Grok in questo modo, otteniamo la risposta tutta insieme, quindi dobbiamo aspettare che Grok termini di generare l’intera risposta prima di vedere qualcosa. Possiamo ricevere una replica parola per parola tramite streaming. 

Streaming della risposta

Invece di attendere la risposta completa con chat.sample(), possiamo usare chat.stream() per ricevere l’output del modello in tempo reale.

# … Same code as before

chat.append(user("Explain how the Transformer attention mechanism works using a simple analogy."))

for response, chunk in chat.stream():
    print(chunk.content, end="", flush=True)

print()

Questo codice itera sullo stream, producendo oggetti chunk incrementali e stampando ogni nuovo pezzo di testo (chunk.content) sulla console non appena arriva, creando un’esperienza di streaming reattiva token-per-token.

Eseguendo questo codice, notiamo che il modello impiega comunque un po’ a iniziare a produrre token. Il motivo è che Grok 4.6 è un modello di ragionamento. Per impostazione predefinita, prima di generare la prima parola visibile della risposta finale, il modello passa attraverso una fase interna di ragionamento in "catena di pensiero".

Possiamo aggiornare il codice precedente per visualizzare anche il processo di ragionamento del modello, così:

# … Same code as before

chat.append(user("Explain how the Transformer attention mechanism works using a simple analogy."))

print("--- Reasoning ---")
is_first_content = True

for response, chunk in chat.stream():
    if chunk.reasoning_content:
        print(chunk.reasoning_content, end="", flush=True)
    if chunk.content:
        if is_first_content:
            print("\n\n--- Response ---")
            is_first_content = False
        print(chunk.content, end="", flush=True)

print()

Lo stream di Grok 4.6 che segue questo snippet fornisce due tipi di token:

• I token interni della catena di pensiero del modello
• La risposta finale

Questo script distingue tra i due verificando chunk.reasoning_content per streammare per primo il processo di pensiero passo dopo passo di Grok, e poi stampando chunk.content quando inizia la risposta finale.

Come puoi impostare lo sforzo di ragionamento in Grok 4.6?

Come abbiamo visto sopra, come altri modelli frontier, Grok 4.6 si basa su una catena di pensiero nascosta. Prima di emettere una singola parola della risposta finale, genera migliaia di token di ragionamento per esplorare soluzioni, ricontrollare la logica e correggere i propri errori.

Il parametro reasoning_effort ci consente di controllare quanto impegno il modello dedica a questo processo di ragionamento. Poiché paghiamo anche per i token di ragionamento, non solo per la risposta finale, è un parametro importante da gestire se vogliamo ridurre i costi.

Grok 3 mini permetteva già di regolare reasoning_effort, ma Grok 4 aveva rimosso quel controllo. Il suo ragionamento era sempre attivo e non poteva essere regolato. SpaceXAI ha reintrodotto il controllo nella linea Grok 4.x (4.3 e 4.5), e Grok 4.6 lo supporta anch’esso, con low, medium, high (predefinito) e xhigh.

Per impostare lo sforzo di ragionamento, usiamo il parametro reasoning_effort quando inizializziamo la chat con client.chat.create(). Il valore è una stringa con il livello desiderato. Il valore predefinito è "high". Ecco un esempio per impostarlo su "low":

chat = client.chat.create(
    model="grok-4.6",
    reasoning_effort="low"
)

Confronto tra low e high sullo stesso prompt

Ho provato molti task usando sia il ragionamento low sia high, ad esempio costruire un piccolo gioco, creare uno script per analizzare dati payroll con molte valute formattate male e risolvere enigmi logici.

In tutti questi casi, il modello ha fornito soluzioni simili con ragionamento basso o alto.

Per fare la differenza, serve un task in cui fermarsi a metà ragionamento porta al fallimento. Sono quindi passato a un puzzle con molte soluzioni. Ecco il prompt che ho usato:

Solve the following alphametic puzzle, in which each letter represents a unique digit from 0 to 9. The leading digits cannot be zero.

GROK + DATA = CAMP

Provide a list of all solutions. For each solution, show a single line with the final addition to prove it works.

A entrambi i livelli di ragionamento, Grok 4.6 ha trovato soluzioni corrette. Tuttavia, impostato su low, il budget di ragionamento è terminato prima di completare il task. Di conseguenza ha risposto con una soluzione incompleta. Con un livello alto di ragionamento, Grok 4.6 ha trovato tutte le 264 soluzioni.

Per confronto, con ragionamento low ha usato 16.422 token di ragionamento, mentre con high ne ha usati 56.455.

Quando vale la pena usare xhigh nonostante i token extra?

Se l’impostazione high riesce a risolvere con forza bruta enigmi logici complessi e script di parsing dati, perché qualcuno dovrebbe pagare l’elevato consumo di token di xhigh?

Credo che per il 99% dei task quotidiani di programmazione e data science, xhigh sia eccessivo e ti brucerà semplicemente il budget API.

Tuttavia, xhigh diventa indispensabile quando passi dal chiedere al modello di agire come assistente di coding al chiedergli di agire come agente autonomo. In pratica, stai pagando perché il modello riveda aggressivamente il proprio lavoro, imbocchi vicoli ciechi e riscriva la sua logica prima di mostrarti l’output finale.

Il mio consiglio è di partire da low e aumentare solo se il modello fallisce sistematicamente su un task. È vero che in alcuni casi questo significa pagare più volte per lo stesso problema, ma il più delle volte otterremo una buona soluzione pagando solo una frazione del costo.

Come inviare immagini all’API Grok 4.6?

Grok 4.6 è multimodale e, in quanto tale, può gestire dati immagine. 

Inviare un’immagine tramite URL

Il modo più semplice per fornire un’immagine al modello è usare un URL. Possiamo passarlo come secondo argomento al messaggio dell’utente:

from dotenv import load_dotenv
from xai_sdk import Client
from xai_sdk.chat import image, user

load_dotenv()
client = Client()

chat = client.chat.create(model="grok-4.6")

image_url = "https://images.pexels.com/photos/25810993/pexels-photo-25810993.jpeg"

chat.append(
    user(
        "Describe what you see in this image in detail.",
        image(image_url=image_url),
    )
)

for response, chunk in chat.stream():
    print(chunk.content, end="", flush=True)

print()

Inviare un’immagine tramite upload di file

Spesso vogliamo usare immagini locali invece degli URL. Possiamo farlo caricando l’immagine come stringa base64. La funzione encode_image() può occuparsene:

import base64
import mimetypes

def encode_image(image_path: str) -> str:
    mime_type, _ = mimetypes.guess_type(image_path)
    if not mime_type:
        mime_type = "image/jpeg"
    with open(image_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode("utf-8")
    return f"data:{mime_type};base64,{encoded_string}"

Una volta codificata l’immagine, la forniamo al modello nello stesso modo:

chat.append(
    user(
        "Describe what you see in this image in detail.",
        image(image_url=encode_image("image.png")),
    )
)

Pur supportando input immagine, Grok 4.6 produce solo testo in output. Se vuoi saperne di più sulla generazione di immagini con SpaceXAI, ti consiglio di leggere il nostro tutorial sull’API Grok Imagine.

Come abilito gli strumenti con gli agenti Grok 4.6?

Grok 4.6 fornisce accesso a tre utili strumenti lato server e offre la possibilità di creare strumenti personalizzati.

Chiamare strumenti lato server (ricerca web, ricerca su X, esecuzione di codice)

Grok 4.6 include tre strumenti server:

• Ricerca web: Consente all’agente di eseguire una ricerca sul web per fondare la risposta.
• Ricerca su X: Interroga dati in tempo reale dalla piattaforma X.
• Esecuzione di codice: Esegue codice in una sandbox per aiutare a rispondere alla query.

Questi strumenti girano sui server SpaceXAI e ogni chiamata è fatturata indipendentemente dai token.

Per abilitarli, dobbiamo importarli e fornirli quando istanziamo la chat con client.chat.create():

from xai_sdk.tools import code_execution, web_search, x_search
chat = client.chat.create(
    model="grok-4.6",
    tools=[web_search(), x_search(), code_execution()],
)

Durante lo streaming delle risposte, possiamo sapere se l’agente sta usando uno strumento controllando il flag chunk.tool_calls.

Ecco uno snippet su come processare la risposta in streaming in modo da mostrare all’utente quando l’agente utilizza uno strumento:

for response, chunk in chat.stream():
    for tool_call in chunk.tool_calls:
        print(f"\n--> Agent is calling tool: {tool_call.function.name}\n", flush=True)
    if chunk.content:
        print(chunk.content, end="", flush=True)

Un esempio di script completo con strumenti server è disponibile nel mio repository GitHub di accompagnamento.

Implementare strumenti locali personalizzati

Oltre agli strumenti server di cui sopra, possiamo dotare il nostro agente Grok 4.6 di strumenti personalizzati. Vediamo come implementare strumenti che consentano all’agente di leggere e scrivere file locali.

Per implementare uno strumento personalizzato, ci servono due cose:

1. Una specifica dello strumento usando l’oggetto ufficiale tool() dell’SDK SpaceXAI.

2. Un’implementazione Python dello strumento, ovvero il codice da eseguire quando lo strumento è chiamato.

Una specifica di strumento consiste in:

• Il nome della funzione Python da chiamare.
• Una descrizione che spiega cosa fa lo strumento. È cruciale perché determina quando l’agente chiamerà lo strumento.
• La specifica dei parametri della funzione.

Di seguito una funzione che possiamo usare per implementare uno strumento che legge file locali:

def execute_read_file(file_path: str) -> str:
    print(f"\n🔒 [Permission Request] Grok wants to read local file: '{file_path}'")
    confirm = input("Allow access? [y/N]: ").strip().lower()
    if confirm not in ("y", "yes"):
        print(f"❌ Denied access to '{file_path}'")
        return f"Permission denied by user. Access to file '{file_path}' was not granted."

    if not os.path.exists(file_path):
        return f"Error: File '{file_path}' does not exist."

    try:
        with open(file_path, "r", encoding="utf-8") as f:
            content = f.read()
        print(f"✅ Read {len(content)} characters from '{file_path}'\n")
        return content
    except Exception as e:
        return f"Error reading file '{file_path}': {e}"

Per motivi di sicurezza, abbiamo implementato lo strumento in modo che chieda sempre il permesso all’utente prima di leggere un file. Questo impedisce di fornire accidentalmente dati privati all’agente.

Ecco la specifica dello strumento per questa funzione:

from xai_sdk.chat import tool
read_file_tool = tool(
    name="read_local_file",
    description="Reads the text contents of a local file given its relative or absolute path. Use this whenever the user asks to inspect, summarize, or analyze a local file.",
    parameters={
        "type": "object",
        "properties": {
            "file_path": {
                "type": "string",
                "description": "The path to the local file to read.",
            }
        },
        "required": ["file_path"],
    },
)

Il codice per scrivere su un file è simile e si trova nel file tools.py del repository.

Come eseguire un agent loop con strumenti usando Grok 4.6?

In questa sezione mettiamo insieme tutto quello che abbiamo imparato per costruire un loop agentico Grok 4.6 con cui possiamo parlare a un agente capace di svolgere lavoro reale agendo su file locali e fondando le risposte con dati online tramite ricerca.

L’agente funzionerà come mostrato nel diagramma sotto. L’utente invia un prompt, quindi l’agente risponde utilizzando strumenti se necessario. Poi la risposta viene inviata all’utente, che può continuare a interagire con l’agente. 

L’agente tiene traccia dell’intera conversazione usando la funzione chat.append() per aggiungere prompt, risposte e risultati degli strumenti. Un risultato di strumento deve essere racchiuso in un’istanza di tool_result().

Ecco l’implementazione completa dell’agente:

import json
from dotenv import load_dotenv
from xai_sdk import Client
from xai_sdk.chat import tool_result, user
from xai_sdk.tools import code_execution, web_search, x_search
from tools import (
    execute_read_file,
    execute_write_file,
    read_file_tool,
    write_file_tool,
)

load_dotenv()

# 1. Initialize the chat client with both server-side and client-side tools
client = Client()
chat = client.chat.create(
    model="grok-4.6",
    tools=[web_search(), x_search(), code_execution(), read_file_tool, write_file_tool],
)

# 2. Interactive chat loop
while True:
    try:
        prompt = input("> ")
    except (EOFError, KeyboardInterrupt):
        print()
        break

    if not prompt.strip():
        continue
    if prompt.strip().lower() in ("exit", "quit"):
        break

    # Append the user prompt to the conversation
    chat.append(user(prompt))

    # Agent loop: keeps running until Grok finishes (no further client tool calls)
    print("How can I help you?\n")
    while True:
        response = None
        announced_tools = set()
        started_content = False

        for response, chunk in chat.stream():
            # Announce tool calls
            if chunk.tool_calls:
                for tc in chunk.tool_calls:
                    name = getattr(tc.function, "name", "")
                    tc_id = getattr(tc, "id", None) or name
                    if tc_id and tc_id not in announced_tools:
                        announced_tools.add(tc_id)
                        display_name = name or "tool"
                        print(f"\n⚙️  [Agent Tool] Calling: {display_name}...", flush=True)

            # Stream generated content
            if chunk.content:
                if not started_content:
                    print("\nGrok > ", end="", flush=True)
                    started_content = True
                print(chunk.content, end="", flush=True)

        if response:
            chat.append(response)

        # Check if Grok triggered client-side tools
        client_tool_executed = False
        if response and response.tool_calls:
            for tool_call in response.tool_calls:
                fn_name = tool_call.function.name
                if fn_name == "read_local_file":
                    client_tool_executed = True
                    try:
                        args = json.loads(tool_call.function.arguments)
                        file_path = args.get("file_path", "")
                    except Exception:
                        file_path = tool_call.function.arguments or ""
                    
                    result = execute_read_file(file_path)
                    chat.append(tool_result(result, tool_call_id=tool_call.id))

                elif fn_name == "write_local_file":
                    client_tool_executed = True
                    try:
                        args = json.loads(tool_call.function.arguments)
                        file_path = args.get("file_path", "")
                        content = args.get("content", "")
                    except Exception:
                        file_path = ""
                        content = ""
                    
                    result = execute_write_file(file_path, content)
                    chat.append(tool_result(result, tool_call_id=tool_call.id))

        # If Grok called a client-side tool, re-enter the loop so Grok processes the tool result
        if client_tool_executed:
            continue
        
        break

    print("\n")

Testare l’agente Grok 4.6 per eseguire un’analisi di portafoglio azionario

Per testare l’agente, ho creato un file CSV di esempio di portafoglio azionario. Il file è piuttosto semplice e elenca le azioni, mostrando in particolare la data di acquisto e il prezzo di acquisto. 

L’idea è chiedere all’agente di:

1. Caricare il file CSV.
2. Eseguire una ricerca web per ottenere i prezzi correnti di ciascuna azione.
3. Aggiornare il CSV aggiungendo una nuova colonna con i prezzi correnti.
4. Chiedere all’agente di creare un report sul nostro portafoglio che mostri gli ultimi sviluppi nei nostri settori.

Sotto trovi una schermata dell’interazione con l’agente per i passaggi da 1 a 3.

Osserviamo che ha usato ricerca web, esecuzione di codice e gli strumenti personalizzati che abbiamo creato per leggere e scrivere file locali. Alla fine, ha aggiornato il file CSV aggiungendo una nuova colonna con i prezzi correnti delle azioni.

Poiché l’agente gira in loop, possiamo continuare la conversazione. Nell’interazione successiva, gli ho chiesto di cercare notizie relative a queste azioni, analizzare la diversificazione del portafoglio e creare un report in markdown.

Se sei curioso di vedere il report creato, si trova nel repository GitHub.

Testare l’agente su un task reale come l’analisi di un portafoglio azionario mostra davvero cosa può fare Grok 4.6. Usando ricerche web, eseguendo codice e sfruttando strumenti locali in autonomia, il modello gestisce facilmente richieste complesse.

Prompt caching e la soglia di prezzo a 200k

Quando implementiamo un agente multi-turn, dovremmo assicurarci che la conversazione sia messa in cache in modo che il modello non debba rielaborare l’intera cronologia a ogni interazione. Non farlo può comportare costi elevatissimi.

Il caching avviene automaticamente, ma le voci di cache sono archiviate per server e, per impostazione predefinita, le richieste possono essere instradate su server diversi e perdere la cache. Per massimizzare gli hit di cache, forniamo un identificatore di conversazione stabile in modo che tutte le richieste di una conversazione raggiungano lo stesso server. Come passarlo dipende dall’API:

• xai-sdk (gRPC): x-grok-conv-id, passato come metadata gRPC quando il client è inizializzato

• OpenAI Responses API: prompt_cache_key, impostato nel body della richiesta

Il seguente snippet mostra come fare:

import uuid
from dotenv import load_dotenv
from xai_sdk import Client
from xai_sdk.chat import tool_result, user

load_dotenv()

# 1. Generate a unique ID for the conversation loop
conv_id = str(uuid.uuid4()) 

# 2. Pass the ID when initializing the Client
client = Client(
    metadata=(("x-grok-conv-id", conv_id),)
)

# ... [the rest of the code remains the same]

Un aspetto importante è che la penalità economica diventa particolarmente severa nelle conversazioni estese. Una volta che la lunghezza totale del prompt raggiunge o supera 200k token, l’API applica un moltiplicatore 2x, fatturando l’intera richiesta al doppio della tariffa standard.

Per evitare che i loop multi-turn superino questa soglia dei 200k, è altamente consigliato implementare la compattazione del contesto. Si fa riassumendo periodicamente i turni di conversazione più vecchi o facendo scorrere la finestra di contesto. Questa strategia ti consente di continuare a beneficiare di cache hit economici sulle istruzioni principali evitando gravi penalità economiche dovute a una finestra di contesto in crescita senza fine.

Conclusione

In questo tutorial abbiamo imparato a usare l’API SpaceXAI con Python per interagire con Grok 4.6. Abbiamo visto le basi su come inviare prompt testuali e di immagine e come gestire l’output per far sapere all’utente su cosa sta lavorando il modello. 

Imparando a fornire strumenti al modello di AI, abbiamo poi potuto mettere tutto insieme e costruire un agente AI in grado di usare Grok 4.6 per risolvere task reali come analizzare un portafoglio azionario. Infine, abbiamo visto che eseguire task a lungo contesto può essere incredibilmente costoso, soprattutto se non usiamo la cache.

Come esercizio per mettere alla prova ciò che hai imparato qui, ti suggerisco di implementare la cache nell’agente e aggiornare l’output per visualizzare anche i token di ragionamento. 

Se vuoi approfondire come costruire agenti AI con le API, ti consiglio il nostro corso Working with the OpenAI API. Il posto migliore per andare a fondo sugli agenti AI è lo skill track AI Agent Fundamentals.