API Grok 4.6 : de votre premier appel à un agent outillé

Comment configurer l’API Grok 4.6 en Python ?

Pour démarrer, vous avez besoin d’une clé API SpaceXAI et d’installer le xai-sdk.

Obtenir une clé API depuis console.x.ai

Pour créer une clé API Grok 4.6, rendez-vous sur la page de création de clé API de la console SpaceX AI. Cliquez ensuite sur le bouton Create API Key en haut à droite.

Le formulaire de création est simple. Donnez un nom à la clé pour savoir à quel projet elle appartient. Je recommande aussi de toujours définir une date d’expiration par précaution en cas de compromission.

Une fois la clé générée, copiez-la et collez-la dans un fichier nommé .env que vous créez dans le même dossier que vos scripts Python. Ainsi, il est facile de charger la clé dans le script sans l’intégrer au code source, ce qui éviterait de l’exposer par mégarde lors d’un partage ou d’un dépôt dans le cloud.

Le fichier .env doit contenir :

XAI_API_KEY=replace_with_the_api_key

Installer xai-sdk et charger la clé API SpaceXAI

Pour se connecter à SpaceXAI avec la clé, nous utilisons le paquet xai-sdk. Bonne pratique : créer un environnement séparé par projet pour éviter les conflits entre paquets Python. Nous allons utiliser Anaconda avec la commande suivante :

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

Une fois actif, nous pouvons installer les paquets souhaités. Pour commencer :

• xai-sdk : le paquet officiel SpaceXAI pour interagir avec leur API.

• python-dotenv : un utilitaire pour charger facilement la clé API depuis le fichier .env.

Pour les installer, exécutez :

pip install xai-sdk python-dotenv

Voici comment charger la clé API et créer un client SpaceXAI en Python :

from dotenv import load_dotenv
from xai_sdk import Client

load_dotenv()

client = Client()

Notez que ce code n’envoie pas encore de requête. Nous allons voir comment faire dans la suite.

Acheter des crédits API SpaceXAI

Pour utiliser l’API Grok 4.6, vous devez aussi acheter des crédits sur leur plateforme. Sans crédits, les requêtes sont refusées. Pour cela, rendez-vous dans Credits en bas de la barre latérale, cliquez sur Add credits et ajoutez le montant souhaité.

Quel est le coût de Grok 4.6 via l’API ?

Les requêtes vers Grok 4.6 sont facturées au token. Le tarif de base est de 2 $ par million de tokens en entrée et 6 $ par million de tokens en sortie.

Important : Grok 4.6 est un modèle de raisonnement. Le raisonnement s’effectue sous forme de dialogue interne et consomme aussi des tokens, facturés comme tokens de sortie. Nous verrons plus loin comment contrôler la quantité de raisonnement effectuée pour une requête donnée.

Les tokens mis en cache coûtent beaucoup moins cher : 0,5 $ par million.

Comme nous le verrons, Grok dispose de trois outils intégrés facturés séparément des tokens : la recherche web, la recherche X et l’exécution de code. Tous sont à 5,00 $ pour 1 000 appels.

Pour les longs contextes, notez que tous les tokens d’invites dépassant le seuil de 200 K sont facturés au double.

Comment effectuer votre premier appel API Grok 4.6 ?

Appuyons-nous sur le code précédent pour utiliser le client SpaceXAI et envoyer une requête à Grok 4.6.

Pour envoyer une requête, on initie une session de chat ciblant grok-4.6 avec client.chat.create() et on ajoute notre prompt à l’historique via chat.append(user()).

Enfin, un appel à chat.sample() envoie la conversation au modèle pour générer une réponse, que nous affichons en imprimant 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)

Utilisé ainsi, Grok renvoie la réponse d’un seul bloc : il faut attendre la fin de la génération complète pour voir quelque chose. Pour un retour mot à mot, utilisez le streaming.

Streaming des réponses

Au lieu d’attendre la réponse complète avec chat.sample(), vous pouvez utiliser chat.stream() pour recevoir la sortie du modèle en temps réel.

# … Même code qu’avant

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

Ce code itère sur le flux, renvoyant des fragments incrémentaux et affichant chaque nouveau morceau de texte (chunk.content) dès son arrivée, pour une expérience fluide token par token.

À l’exécution, on constate qu’il faut tout de même un peu de temps avant l’apparition des premiers tokens. La raison : Grok 4.6 est un modèle de raisonnement. Par défaut, avant de produire le premier mot visible de la réponse finale, le modèle passe par une phase interne de raisonnement en « chaîne de pensée ».

Nous pouvons adapter le code ci‑dessus pour afficher aussi le raisonnement du modèle :

# … Même code qu’avant

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

Le flux Grok 4.6 qui suit ce snippet délivre deux types de tokens :

• Les tokens internes de chaîne de pensée du modèle
• La réponse finale

Ce script distingue les deux en vérifiant chunk.reasoning_content pour diffuser d’abord la réflexion pas à pas de Grok, puis il imprime chunk.content lorsque la réponse finale commence.

Comment régler l’effort de raisonnement dans Grok 4.6 ?

Comme vu plus haut, à l’instar d’autres modèles de pointe, Grok 4.6 s’appuie sur une chaîne de pensée cachée. Avant de produire un seul mot de sa réponse finale, il génère des milliers de tokens de raisonnement pour explorer des pistes, vérifier la logique et corriger ses erreurs.

Le paramètre reasoning_effort nous permet de contrôler l’effort alloué à ce processus. Comme ces tokens de raisonnement sont aussi facturés, pas seulement la réponse finale, c’est un paramètre clé pour maîtriser les coûts.

Grok 3 mini permettait déjà d’ajuster reasoning_effort, mais Grok 4 avait retiré ce contrôle : le raisonnement était toujours actif et non ajustable. SpaceXAI l’a réintroduit sur la gamme Grok 4.x (4.3 et 4.5), et Grok 4.6 le prend aussi en charge, avec low, medium, high (par défaut) et xhigh.

Pour régler l’effort de raisonnement, utilisez le paramètre reasoning_effort lors de l’initialisation du chat avec client.chat.create(). La valeur est une chaîne correspondant au niveau souhaité. La valeur par défaut est "high". Voici un exemple pour le définir sur "low" :

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

Comparer low vs high sur le même prompt

J’ai essayé de nombreuses tâches avec les niveaux low et high : créer un petit jeu, générer un script d’analyse de paie avec des formats monétaires mal formés, et résoudre des casse-têtes logiques.

Dans tous ces cas, le modèle a su proposer des solutions similaires avec l’un ou l’autre niveau.

Pour vraiment voir une différence, il faut une tâche où s’arrêter au milieu du raisonnement fait échouer le résultat. Je me suis donc tourné vers une énigme à multiples solutions. Voici le prompt utilisé :

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.

Aux deux niveaux, Grok 4.6 a trouvé des solutions correctes. Cependant, en low, son budget de raisonnement s’est épuisé avant la fin, ce qui a produit une réponse incomplète. Avec high, Grok 4.6 a trouvé les 264 solutions.

À titre de comparaison, en low il a utilisé 16 422 tokens de raisonnement, contre 56 455 en high.

Quand xhigh vaut-il les tokens supplémentaires ?

Si le niveau high peut passer en force sur des énigmes logiques complexes et des scripts de parsing de données, pourquoi payer la consommation massive de xhigh ?

À mon avis, pour 99 % des tâches quotidiennes de programmation et de data science, xhigh est excessif et ne fera que grignoter votre budget API.

En revanche, xhigh devient indispensable lorsqu’on demande au modèle d’agir en agent autonome plutôt qu’en assistant de code. Vous payez en somme pour qu’il relise agressivement son travail, explore des impasses et réécrive sa logique avant même d’afficher le résultat.

Mon conseil : commencez en low et n’augmentez que si le modèle échoue systématiquement. Certes, cela peut amener à payer plusieurs fois pour le même problème, mais le plus souvent, vous obtiendrez une bonne solution pour une fraction du coût.

Comment envoyer des images à l’API Grok 4.6 ?

Grok 4.6 est multimodal et peut donc traiter des images.

Envoyer une image via URL

La façon la plus simple de fournir une image au modèle est d’utiliser une URL. On peut la passer en second argument du message utilisateur :

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

Envoyer une image via un fichier local

Souvent, nous voulons utiliser des images locales plutôt que des URLs. Il suffit alors de charger l’image en base64. La fonction encode_image() s’en charge :

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

Une fois l’image encodée, on la fournit au modèle de la même manière :

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

Malgré la prise en charge des images en entrée, Grok 4.6 ne produit que du texte. Pour en savoir plus sur la génération d’images avec SpaceXAI, consultez notre tutoriel sur l’API Grok Imagine.

Comment activer les outils avec des agents Grok 4.6 ?

Grok 4.6 donne accès à trois outils côté serveur et permet de créer des outils personnalisés.

Appeler les outils côté serveur (recherche web, recherche X, exécution de code)

Grok 4.6 est livré avec trois outils serveur :

• Web search : permet à l’agent d’effectuer une recherche web pour étayer sa réponse.
• X search : interroge des données en temps réel de la plateforme X.
• Code execution : exécute du code dans un bac à sable pour aider à répondre.

Ces outils s’exécutent sur les serveurs de SpaceXAI, et chaque appel est facturé indépendamment des tokens.

Pour les activer, il faut les importer et les passer lors de l’instanciation du chat avec 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()],
)

En streaming, on peut savoir si l’agent utilise un outil en vérifiant l’indicateur chunk.tool_calls.

Voici un extrait montrant comment traiter le flux pour indiquer à l’utilisateur quand l’agent appelle un outil :

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 script complet avec outils serveur est disponible dans le dépôt GitHub associé.

Implémenter des outils locaux personnalisés

En plus des outils côté serveur, nous pouvons doter notre agent Grok 4.6 d’outils personnalisés. Voyons comment lui permettre de lire et écrire des fichiers locaux.

Pour implémenter un outil personnalisé, il faut deux éléments :

1. Une spécification d’outil avec l’objet officiel tool() du SDK SpaceXAI.

2. Une implémentation Python de l’outil, autrement dit le code exécuté lors de l’appel.

Une spécification d’outil comprend :

• Le nom de la fonction Python à appeler.
• Une description qui explique ce que fait l’outil. Crucial pour que l’agent sache quand l’invoquer.
• La spécification des paramètres de la fonction.

Ci‑dessous, une fonction pour implémenter un outil qui lit des fichiers locaux :

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

Par sécurité, nous demandons systématiquement l’autorisation de l’utilisateur avant de lire un fichier. Cela évite de fournir des données privées à l’agent par inadvertance.

Voici la spécification d’outil associée à cette fonction :

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

Le code d’écriture dans un fichier est similaire et disponible dans le fichier tools.py du référentiel.

Comment exécuter une boucle d’agent avec outils sous Grok 4.6 ?

Dans cette section, nous combinons tout ce que nous avons vu pour construire une boucle agentique Grok 4.6 : dialoguer avec un agent qui peut réellement agir sur des fichiers locaux tout en ancrant ses réponses avec des données en ligne via la recherche.

Le fonctionnement est illustré ci‑dessous. L’utilisateur envoie un prompt, l’agent répond en utilisant des outils si nécessaire. La réponse est renvoyée à l’utilisateur, qui peut poursuivre l’échange.

L’agent garde l’historique complet via chat.append() pour ajouter prompts, réponses et résultats d’outils. Un résultat d’outil doit être enveloppé dans une instance de tool_result().

Voici l’implémentation complète de l’agent :

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

Tester l’agent Grok 4.6 pour analyser un portefeuille d’actions

Pour tester l’agent, j’ai créé un fichier CSV de portefeuille d’actions exemple. Le fichier est simple : il liste des titres, avec notamment la date d’achat et le prix d’acquisition.

L’idée est de demander à l’agent de :

1. Charger le fichier CSV.
2. Faire une recherche web pour obtenir les cours actuels de chaque action.
3. Mettre à jour le CSV en ajoutant une nouvelle colonne avec les cours actuels.
4. Demander la création d’un rapport sur le portefeuille indiquant les dernières tendances de nos secteurs.

Ci‑dessous, une capture de l’échange avec l’agent pour les étapes 1 à 3.

On observe qu’il a utilisé la recherche web, l’exécution de code et nos outils personnalisés pour lire/écrire des fichiers locaux. Au final, il a mis à jour le CSV en ajoutant une colonne avec les cours actuels.

Comme l’agent tourne en boucle, nous pouvons poursuivre la conversation. À l’échange suivant, je lui ai demandé de rechercher des actualités liées à ces actions, d’analyser la diversification du portefeuille et de créer un rapport en Markdown.

Si le rapport vous intéresse, il est disponible dans le dépôt GitHub.

Tester l’agent sur une tâche réelle comme l’analyse d’un portefeuille met en lumière les capacités de Grok 4.6. En combinant recherches web, exécution de code et outils locaux en autonomie, le modèle gère sans effort des demandes complexes.

Cache des invites et falaise tarifaire à 200 k

Pour un agent multi‑tours, assurez‑vous que la conversation est mise en cache afin que le modèle n’ait pas à retraiter tout l’historique à chaque interaction. Ne pas le faire peut coûter très cher.

Le cache se fait automatiquement, mais les entrées sont stockées par serveur et, par défaut, les requêtes peuvent être routées vers différents serveurs et rater le cache. Pour maximiser les hits, fournissez un identifiant de conversation stable afin que toutes les requêtes d’un même échange arrivent sur le même serveur. La manière de le passer dépend de l’API :

• xai-sdk (gRPC) : x-grok-conv-id, passé en métadonnées gRPC à l’initialisation du client

• OpenAI Responses API : prompt_cache_key, défini dans le corps de la requête

L’exemple suivant montre comment faire :

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]

Point d’attention important : la pénalité financière devient particulièrement lourde pour des conversations étendues. Une fois que la longueur totale de votre invite atteint ou dépasse 200 k tokens, l’API applique un multiplicateur ×2 et facture l’intégralité de la requête au double du tarif standard.

Pour éviter que les boucles multi‑tours ne dépassent ce seuil de 200 k, il est fortement recommandé de compacter le contexte : résumer périodiquement les anciens tours de conversation ou faire glisser la fenêtre de contexte. Cette stratégie vous permet de continuer à bénéficier d’un cache peu coûteux sur vos instructions clés tout en évitant les lourdes pénalités d’un contexte qui grossit indéfiniment.

Conclusion

Dans ce tutoriel, nous avons vu comment utiliser l’API SpaceXAI avec Python pour interagir avec Grok 4.6. Nous avons appris à envoyer des prompts texte et image, et à gérer la sortie pour informer l’utilisateur de ce que fait le modèle.

En fournissant des outils au modèle d’IA, nous avons pu assembler le tout et construire un agent capable d’utiliser Grok 4.6 pour résoudre des tâches concrètes comme l’analyse d’un portefeuille boursier. Enfin, nous avons vu que les tâches à long contexte peuvent coûter très cher, surtout sans mise en cache.

Pour mettre en pratique, je vous suggère d’implémenter le cache dans l’agent et d’afficher également les tokens de raisonnement.

Si vous souhaitez approfondir la création d’agents IA via des API, je vous recommande notre cours Working with the OpenAI API. Pour aller plus loin sur les agents IA, consultez le parcours de compétences AI Agent Fundamentals.