Grok 4.6 API: van eerste call tot een agent met tools

Hoe stel je de Grok 4.6 API in met Python?

Om te beginnen heb je een SpaceXAI API-sleutel nodig en moet je de xai-sdk installeren.

Een API-sleutel halen bij console.x.ai

Om een Grok 4.6 API-sleutel te maken, gaan we naar de SpaceX AI-consolepagina voor API-sleutels. Vervolgens klikken we rechtsboven op de knop Create API Key.

Het formulier voor het aanmaken van een API-sleutel is eenvoudig. We geven de sleutel een naam zodat we herkennen bij welk project hij hoort. Ik raad ook aan om altijd een vervaldatum in te stellen als vangnet voor het geval de sleutel wordt gecompromitteerd.

Zodra de sleutel is gegenereerd, kopiëren we hem en plakken we hem in een bestand met de naam .env dat we aanmaken in dezelfde map als waar we onze Python-scripts zullen schrijven. Zo kunnen we de sleutel eenvoudig in ons script laden zonder dat hij in de code zelf staat, wat er al snel toe kan leiden dat we hem per ongeluk blootstellen bij het delen of uploaden van de code naar de cloud.

Het .env-bestand moet de volgende inhoud hebben:

XAI_API_KEY=replace_with_the_api_key

xai-sdk installeren en SpaceXAI API-sleutel laden

Om met de API-sleutel verbinding te maken met SpaceXAI gebruiken we het pakket xai-sdk. Het is goede praktijk om voor elk project een aparte omgeving te maken, zodat Python-pakketten niet in conflict komen met die uit andere projecten die we mogelijk hebben. Dat doen we met Anaconda via het volgende commando:

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

Zodra die actief is, kunnen we de gewenste pakketten installeren. Voor nu beginnen we met:

• xai-sdk: Het officiële SpaceXAI-pakket om verzoeken naar hun API te sturen.

• python-dotenv: Een hulppakket dat het makkelijk maakt de API-sleutel uit het .env-bestand te laden.

Om ze te installeren gebruiken we het commando:

pip install xai-sdk python-dotenv

Zo kunnen we de API-sleutel laden en een SpaceXAI Client in Python aanmaken:

from dotenv import load_dotenv
from xai_sdk import Client

load_dotenv()

client = Client()

Let op: deze code doet nog geen verzoek. Dat leren we zo.

SpaceXAI API-credits kopen

Om de Grok 4.6 API te gebruiken, moeten we ook credits kopen op hun API-platform. Zonder deze worden API-verzoeken geweigerd. Ga hiervoor naar Credits onderaan de zijbalk, klik op Add credits en voeg je gewenste bedrag toe.

Hoe duur is Grok 4.6 via de API?

Verzoeken aan Grok 4.6 worden per token gefactureerd. De basisprijs is $2 per miljoen inputtokens en $6 per miljoen outputtokens.

Belangrijk om te weten: Grok 4.6 is een redeneermodel. Het redeneren gebeurt als een interne zelfdialoog en verbruikt ook tokens, die als outputtokens worden gefactureerd. Later leren we hoe je de hoeveelheid redenering die het model voor een bepaald verzoek uitvoert kunt regelen.

Gecachte tokens zijn veel goedkoper: slechts $0,5 per miljoen tokens.

Zoals we zullen zien, heeft Grok drie ingebouwde tools die los van de tokens worden gefactureerd: websearch, X-search en code-executie. Al deze kosten $5,00 per 1.000 calls.

Voor lange contexten is het goed om te weten dat alle tokens in prompts die de drempel van 200K overschrijden tegen het dubbele tarief worden gefactureerd.

Hoe maak je je eerste Grok 4.6 API-call?

Laten we voortbouwen op de vorige code om met de SpaceXAI-client een verzoek naar Grok 4.6 te sturen.

Om een verzoek naar Grok 4.6 te sturen, initialiseren we een chatsessie gericht op grok-4.6 met client.chat.create() en voegen we onze prompt toe aan de gespreksgeschiedenis met chat.append(user()).

Tot slot stuurt een aanroep van chat.sample() het gesprek naar het model om een antwoord te genereren, dat we tonen door response.content te printen.

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)

Als je Grok op deze manier gebruikt, krijg je het antwoord in één keer, dus je moet wachten tot Grok klaar is met het genereren van het volledige antwoord voordat je iets ziet. Met streaming kun je woord voor woord een reactie krijgen. 

Response-streaming

In plaats van te wachten op het complete antwoord met chat.sample(), kunnen we chat.stream() gebruiken om de output van het model in realtime te ontvangen.

# … 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()

Deze code itereert over de stream, geeft incrementele chunk-objecten terug en print elk nieuw stukje tekst (chunk.content) naar de console zodra het binnenkomt, waardoor een responsieve token-voor-token streamingervaring ontstaat.

Bij het uitvoeren van deze code merk je dat het model nog steeds even de tijd neemt voordat het tokens gaat produceren. De reden is dat Grok 4.6 een redeneermodel is. Standaard doorloopt het model, voordat het het eerste zichtbare woord van het uiteindelijke antwoord genereert, een interne fase van "chain-of-thought"-redenering.

We kunnen de bovenstaande code aanpassen om ook het redeneerproces van het model weer te geven, zoals hier:

# … 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()

De Grok 4.6-stream die op dit fragment volgt, levert twee soorten tokens:

• De interne chain-of-thought-tokens van het model
• Het uiteindelijke antwoord

Dit script maakt onderscheid tussen beide door chunk.reasoning_content te controleren om eerst Groks stapsgewijze denkproces te streamen en vervolgens chunk.content te printen zodra het uiteindelijke antwoord begint.

Hoe stel je de redeneerinspanning in Grok 4.6 in?

Zoals we hierboven zagen, vertrouwt Grok 4.6, net als andere frontier-AI-modellen, op een verborgen denkstapketen. Voordat het ook maar één woord van het uiteindelijke antwoord produceert, genereert het duizenden redeneertokens om oplossingen te verkennen, logica te dubbelchecken en eigen fouten te corrigeren.

Met de parameter reasoning_effort kunnen we bepalen hoeveel inspanning het model in dit redeneerproces stopt. Omdat we ook betalen voor de redeneertokens, niet alleen voor het uiteindelijke antwoord, is dit een belangrijke parameter om te beheren als we de kosten willen verlagen.

Grok 3 mini liet ontwikkelaars reasoning_effort al afstellen, maar Grok 4 haalde die controle weg. De redenering stond altijd aan en kon niet worden aangepast. SpaceXAI introduceerde de controle opnieuw in de Grok 4.x-lijn (4.3 en 4.5), en Grok 4.6 ondersteunt het ook, met low, medium, high (de standaard) en xhigh.

Om de redeneerinspanning in te stellen, gebruiken we de parameter reasoning_effort bij het initialiseren van de chat met client.chat.create(). De waarde is een string met de gewenste inspanning. De standaardwaarde is "high". Hier is een voorbeeld om het in te stellen op "low":

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

Low versus high bij dezelfde prompt vergelijken

Ik heb veel taken geprobeerd met zowel low als high reasoning, zoals een klein spel bouwen, een script maken om payroll-data met meerdere slecht geformatteerde valutaformaten te analyseren en logische puzzels oplossen.

In al deze gevallen kon het model vergelijkbare oplossingen geven met zowel low als high reasoning.

Om verschil te maken, hebben we een taak nodig waarbij stoppen halverwege de redenering faalt. Dus koos ik een puzzel met veel oplossingen. Dit is de prompt die ik gebruikte:

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.

Op beide redeneerniveaus vond Grok 4.6 correcte oplossingen. Maar als hij op low stond, was het redeneerbudget op voordat het de taak kon afronden. Daarom gaf het een onvolledige oplossing. Met een hoog redeneerniveau vond Grok 4.6 alle 264 oplossingen.

Ter vergelijking: met low reasoning gebruikte het 16.422 redeneertokens, terwijl het er 56.455 gebruikte met high reasoning.

Wanneer is xhigh de extra tokens waard?

Als de high-instelling complexe logische puzzels en data-parsingscripts succesvol brute-forcet, waarom zou iemand dan betalen voor het enorme tokenverbruik van xhigh?

Ik denk dat xhigh voor 99% van de dagelijkse programmeer- en datasciencetaken overkill is die simpelweg je API-budget opslokt.

Toch wordt xhigh onmisbaar wanneer je het model niet meer vraagt om als code-assistent te werken, maar als autonome agent. Je betaalt er in feite voor dat het model zijn eigen werk agressief beoordeelt, doodlopende wegen inslaat en zijn logica herschrijft voordat het je het uiteindelijke resultaat laat zien.

Mijn advies: begin met low en verhoog het alleen als het model systematisch faalt bij een taak. Het is waar dat we in sommige gevallen meerdere keren voor hetzelfde probleem betalen, maar meestal komen we weg met een goede oplossing tegen een fractie van de kosten.

Hoe stuur je afbeeldingen naar de Grok 4.6 API?

Grok 4.6 is multimodaal en kan dus met beelddata overweg. 

Een afbeelding via URL sturen

De eenvoudigste manier om een afbeelding aan het model te geven is via een URL. We kunnen die als tweede argument aan het user-bericht meegeven:

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()

Een afbeelding via bestandsupload sturen

Vaak willen we lokale afbeeldingen gebruiken in plaats van URL’s. Dat kan door de afbeelding als een base64-string te laden. De functie encode_image() kan dat voor ons doen:

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}"

Zodra de afbeelding is gecodeerd, geven we hem op dezelfde manier aan het model door:

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

Ondanks dat het afbeeldingsinput ondersteunt, geeft Grok 4.6 alleen tekst terug. Wil je meer weten over beeldgeneratie met SpaceXAI, lees dan onze tutorial over de Grok Imagine API.

Hoe schakel ik tools in bij Grok 4.6-agents?

Grok 4.6 biedt toegang tot drie handige server-side tools en de mogelijkheid om custom tools te maken.

Server-side tools aanroepen (websearch, X-search, code-executie)

Grok 4.6 wordt geleverd met drie servertools:

• Websearch: Laat de agent een webzoekopdracht uitvoeren om het antwoord te onderbouwen.
• X-search: Vraagt realtime platformdata op van X.
• Code-executie: Voert code uit in een sandbox om de vraag te beantwoorden.

Deze tools draaien op de servers van SpaceXAI en elke toolcall wordt los van de tokens gefactureerd.

Om deze in te schakelen importeren we ze en geven we ze mee bij het instantiëren van de chat met 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()],
)

Bij het streamen van de responses kunnen we zien of de agent een tool gebruikt door de vlag chunk.tool_calls te controleren.

Hier is een snippet om de streamingresponse te verwerken op een manier die de gebruiker laat zien wanneer de agent een tool gebruikt:

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)

Een volledig voorbeelden script met servertools vind je in mijn bijbehorende GitHub-repo.

Custom lokale tools implementeren

Bovenop de bovenstaande servertools kunnen we onze Grok 4.6-agent ook uitrusten met custom tools. Laten we bekijken hoe we tools implementeren waarmee de agent lokale bestanden kan lezen en schrijven.

Om een custom tool te implementeren hebben we twee dingen nodig:

1. Een toolspecificatie met het officiële tool()-object uit de SpaceXAI SDK.

2. Een Python-implementatie van de tool, met andere woorden, de code die we willen uitvoeren wanneer de tool wordt aangeroepen.

Een toolspecificatie bestaat uit:

• De naam van de aan te roepen Python-functie.
• Een beschrijving die uitlegt wat de tool doet. Dit is cruciaal omdat het bepaalt wanneer de agent de tool aanroept.
• De parameterspecificatie van de functie.

Hieronder staat een functie die we kunnen gebruiken om een tool te implementeren die lokale bestanden leest:

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}"

Om veiligheidsredenen hebben we de tool zo geïmplementeerd dat hij altijd toestemming aan de gebruiker vraagt voordat een bestand wordt gelezen. Dit voorkomt dat we per ongeluk privégegevens aan de agent verstrekken.

Hier is de toolspecificatie voor deze functie:

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"],
    },
)

De code om naar een bestand te schrijven is vergelijkbaar en is te vinden in het bestand tools.py in de repository.

Hoe voer je een agentloop met tools uit met Grok 4.6?

In deze sectie brengen we alles samen wat we geleerd hebben om een Grok 4.6-agentische loop te bouwen waarmee we met een agent kunnen praten die echt werk kan verrichten door op lokale bestanden te handelen en antwoorden te onderbouwen met onlinedata via search.

De agent werkt zoals in het onderstaande diagram. De gebruiker stuurt een prompt, vervolgens antwoordt de agent en gebruikt indien nodig tools. Daarna wordt het antwoord teruggestuurd naar de gebruiker en kan de gebruiker blijven interageren met de agent. 

De agent houdt de hele conversatie bij met behulp van de functie chat.append() om gebruikersprompts, responses en toolresultaten toe te voegen. Een toolresultaat moet worden omhuld in een instantie van tool_result().

Hier is de volledige agentimplementatie:

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")

De Grok 4.6-agent testen voor een analyse van een aandelenportefeuille

Om de agent te testen heb ik een voorbeeld-CSV-bestand met een aandelenportefeuille gemaakt. Het bestand is vrij eenvoudig en bevat aandelen, met onder meer de aankoopdatum en aankoopprijs. 

Het idee is om de agent te vragen om:

1. Het CSV-bestand te laden.
2. Een websearch te doen om de huidige prijzen van elk van de aandelen op te halen.
3. De CSV bij te werken door een nieuwe kolom met de huidige prijzen toe te voegen.
4. De agent te vragen een rapport over onze portefeuille te maken met de laatste ontwikkelingen in onze sectoren.

Hieronder staat een screenshot van de interactie met de agent voor de stappen 1 tot en met 3.

We zien dat het websearch, code-executie en de custom tools die we hebben gemaakt gebruikte om lokale bestanden te lezen en schrijven. Uiteindelijk werkte het het CSV-bestand bij door een nieuwe kolom met de huidige aandelenprijzen toe te voegen.

Omdat de agent in een loop draait, kunnen we het gesprek voortzetten. In de volgende interactie vroeg ik om nieuws over deze aandelen op te zoeken, de portefeuillediversiteit te analyseren en een markdown-rapport te maken.

Ben je benieuwd naar het rapport dat het maakte? Dat staat in de GitHub-repository.

Het testen van de agent op een realistische taak zoals het analyseren van een aandelenportefeuille laat echt zien wat Grok 4.6 kan. Door zelfstandig websearches te doen, code uit te voeren en lokale tools te gebruiken, handelt het model moeiteloos complexe verzoeken af.

Promptcaching en de 200k-prijsval

Bij het implementeren van een agent met meerdere beurten moeten we zorgen dat het gesprek wordt gecachet, zodat het model niet de hele geschiedenis bij elke interactie hoeft te herverwerken. Dit niet doen kan enorme kosten veroorzaken.

Cachen gebeurt automatisch, maar cache-items worden per server opgeslagen en standaard kunnen verzoeken naar verschillende servers worden gerouteerd en de cache missen. Om cache-hits te maximaliseren, geven we een stabiele conversatie-ID mee zodat alle verzoeken in een gesprek dezelfde server bereiken. Hoe je die doorgeeft, hangt af van de API:

• xai-sdk (gRPC): x-grok-conv-id, meegegeven als gRPC-metadata bij het initialiseren van de client

• OpenAI Responses API: prompt_cache_key, ingesteld in de request body

Onderstaand fragment laat zien hoe je dat doet:

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]

Een belangrijke overweging is dat de financiële straf bijzonder zwaar wordt bij lange gesprekken. Zodra je totale promptlengte 200k tokens bereikt of overschrijdt, past de API een 2×-multiplier toe en wordt het volledige verzoek tegen het dubbele standaardtarief gefactureerd.

Om te voorkomen dat multi-turn-loops voorbij deze 200k-drempel gaan, is het sterk aan te raden contextcompactie te implementeren. Dit doe je door oudere gespreksbeurten periodiek samen te vatten of het contextwindow te verschuiven. Met deze strategie blijf je profiteren van goedkope cache-hits op je kerninstructies, terwijl je de zware financiële sancties van een eindeloos groeiend contextwindow vermijdt.

Conclusie

In deze tutorial leerden we hoe je de SpaceXAI API met Python gebruikt om met Grok 4.6 te communiceren. We leerden de basis van het versturen van tekst- en afbeeldingsprompts en hoe je de output afhandelt om de gebruiker te laten zien waar het model mee bezig is. 

Door te leren hoe je tools aan het AI-model toevoegt, konden we dit alles samenbrengen en een AI-agent bouwen die Grok 4.6 kan gebruiken om realistische taken op te lossen, zoals het analyseren van een aandelenportefeuille. Tot slot leerden we dat taken met lange contexten ontzettend duur kunnen zijn, zeker als we geen caching gebruiken.

Als oefening om te testen wat je hier geleerd hebt, stel ik voor dat je caching in de agent implementeert en de output bijwerkt om ook de redeneertokens te tonen. 

Als je je kennis over het bouwen van AI-agents met API’s wilt verdiepen, raad ik onze cursus Werken met de OpenAI API aan. De beste plek om de diepte in te gaan over AI-agents is de AI Agent Fundamentals skill track.