API de Grok 4.6: de la primera llamada a un agente con herramientas

¿Cómo configuras la API de Grok 4.6 en Python?

Para empezar, necesitarás una clave de la API de SpaceXAI e instalar xai-sdk.

Obtener una clave API en console.x.ai

Para crear una clave de la API de Grok 4.6, vamos a la página de creación de claves API de la consola de SpaceXAI. Después, hacemos clic en el botón Create API Key en la esquina superior derecha.

El formulario de creación de claves es sencillo. Le ponemos un nombre a la clave para identificar a qué proyecto pertenece. También te recomiendo fijar siempre una fecha de caducidad como salvaguarda por si se viera comprometida.

Una vez generada la clave, la copiamos y la pegamos en un archivo llamado .env que creamos en la misma carpeta en la que escribiremos nuestros scripts de Python. Así podremos cargar la clave en el script sin incluirla en el propio código, evitando exponerla por accidente al compartir o subir el código a la nube.

El archivo .env debe contener lo siguiente:

XAI_API_KEY=replace_with_the_api_key

Instalar xai-sdk y cargar la clave de la API de SpaceXAI

Para conectar con SpaceXAI usando la clave, utilizamos el paquete xai-sdk. Es buena práctica crear un entorno separado por proyecto para evitar conflictos entre paquetes de Python de otros proyectos que tengamos. Para ello, usaremos Anaconda con el siguiente 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

Con el entorno activo, ya podemos instalar los paquetes que queramos. Por ahora, empecemos con:

• xai-sdk: el paquete oficial de SpaceXAI para hacer peticiones a su API.

• python-dotenv: un paquete que facilita cargar la clave API desde el archivo .env.

Para instalarlos, usamos el comando:

pip install xai-sdk python-dotenv

Así es como cargamos la clave API y creamos un cliente de SpaceXAI en Python:

from dotenv import load_dotenv
from xai_sdk import Client

load_dotenv()

client = Client()

Fíjate en que este código aún no hace ninguna petición. A continuación veremos cómo hacerlo.

Comprar créditos de la API de SpaceXAI

Para usar la API de Grok 4.6, también hay que comprar créditos en su plataforma. Sin créditos, las peticiones serán rechazadas. Para ello, ve a Credits al final de la barra lateral, haz clic en Add credits y añade el importe que prefieras.

¿Cuánto cuesta usar Grok 4.6 vía API?

Las solicitudes a Grok 4.6 se facturan por token. El precio base es de 2 $ por millón de tokens de entrada y 6 $ por millón de tokens de salida.

Es importante tener en cuenta que Grok 4.6 es un modelo de razonamiento. El razonamiento se hace como un diálogo interno y también consume tokens, que se facturan como tokens de salida. Más adelante veremos cómo controlar la cantidad de razonamiento que el modelo realiza para una solicitud.

Los tokens en caché son mucho más baratos: solo 0,5 $ por millón de tokens.

Como veremos, Grok tiene tres herramientas integradas que se facturan aparte de los tokens: búsqueda web, búsqueda en X y ejecución de código. Todas cuestan 5,00 $ por cada 1.000 llamadas.

Para contextos largos, conviene recordar que todos los tokens en prompts que superen el umbral de 200K se facturan al doble.

¿Cómo hacer tu primera llamada a la API de Grok 4.6?

Vamos a partir del código anterior para usar el cliente de SpaceXAI y enviar una petición a Grok 4.6.

Para enviar una petición a Grok 4.6, iniciamos una sesión de chat dirigida a grok-4.6 con client.chat.create() y añadimos nuestro prompt al historial con chat.append(user()).

Por último, al llamar a chat.sample() enviamos la conversación al modelo para que genere una respuesta, que mostramos imprimiendo 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 así, recibimos la respuesta de golpe, por lo que hay que esperar a que termine de generarla por completo para ver algo. Podemos obtener una respuesta palabra a palabra usando streaming. 

Streaming de respuestas

En lugar de esperar a la respuesta completa con chat.sample(), podemos usar chat.stream() para recibir la salida del modelo en tiempo real.

# … Mismo código que antes

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

Este código itera sobre el stream, devolviendo objetos incrementales y mostrando cada nuevo fragmento de texto (chunk.content) en la consola tan pronto como llega, creando una experiencia de streaming token a token.

Al ejecutar este código, vemos que el modelo tarda un poco en empezar a producir tokens. La razón es que Grok 4.6 es un modelo de razonamiento. Por defecto, antes de generar la primera palabra visible de la respuesta final, el modelo pasa por una fase interna de razonamiento con "chain of thought".

Podemos actualizar el código anterior para mostrar también el proceso de razonamiento del modelo, así:

# … Mismo código que antes

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

El stream de Grok 4.6 tras este fragmento entrega dos tipos de tokens:

• Los tokens internos de chain of thought del modelo
• La respuesta final

Este script distingue entre ambos comprobando chunk.reasoning_content para emitir primero el pensamiento paso a paso de Grok y, después, imprimir chunk.content cuando empieza la respuesta final.

¿Cómo ajustar el esfuerzo de razonamiento en Grok 4.6?

Como vimos, al igual que otros modelos de vanguardia, Grok 4.6 se apoya en una cadena de pensamiento oculta. Antes de escribir una sola palabra de su respuesta final, genera miles de tokens de razonamiento para explorar soluciones, comprobar la lógica y corregirse.

El parámetro reasoning_effort nos permite controlar cuánto esfuerzo dedica el modelo a ese proceso. Como también pagamos por los tokens de razonamiento, no solo por la respuesta final, es un parámetro clave para gestionar costes.

Grok 3 mini ya permitía ajustar reasoning_effort, pero Grok 4 eliminó ese control: el razonamiento estaba siempre activo y no se podía ajustar. SpaceXAI lo reintrodujo en la línea Grok 4.x (4.3 y 4.5), y Grok 4.6 también lo soporta, con low, medium, high (por defecto) y xhigh.

Para fijar el esfuerzo de razonamiento, usamos el parámetro reasoning_effort al inicializar el chat con client.chat.create(). El valor es una cadena con el nivel deseado. El valor por defecto es "high". Aquí tienes un ejemplo para ponerlo en "low":

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

Comparar low vs high con el mismo prompt

He probado muchas tareas con low y high, como crear un minijuego, hacer un script para analizar nóminas con varios formatos de moneda mal formateados y resolver rompecabezas lógicos.

En todos estos casos, el modelo fue capaz de dar soluciones similares tanto con razonamiento bajo como alto.

Para ver diferencias, necesitamos una tarea en la que cortar el razonamiento a medias fracase. Así que recurrí a un puzzle con muchas soluciones. Este fue el prompt:

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.

En ambos niveles, Grok 4.6 encontró soluciones correctas. Sin embargo, con low, su presupuesto de razonamiento se agotó antes de completar la tarea y respondió con una solución incompleta. Con razonamiento alto, Grok 4.6 encontró las 264 soluciones.

A modo de comparación, con low usó 16.422 tokens de razonamiento, mientras que con high usó 56.455.

¿Cuándo compensa xhigh a pesar del mayor consumo de tokens?

Si la configuración alta puede resolver por fuerza bruta rompecabezas lógicos complejos y scripts de análisis de datos, ¿por qué pagar el consumo masivo de tokens de xhigh?

Creo que para el 99% de las tareas diarias de programación y data science, xhigh es excesivo y solo consumirá tu presupuesto.

Sin embargo, xhigh se vuelve imprescindible cuando pasas de pedirle al modelo que actúe como asistente de código a pedirle que actúe como agente autónomo. Básicamente, estás pagando para que el modelo revise agresivamente su propio trabajo, se tope con callejones sin salida y reescriba su lógica antes de enseñarte el resultado final.

Mi consejo es empezar con low y subirlo solo si el modelo falla sistemáticamente en una tarea. Es cierto que en algunos casos pagarás varias veces por el mismo problema, pero la mayoría de las veces obtendrás una buena solución pagando solo una fracción del coste.

¿Cómo envías imágenes a la API de Grok 4.6?

Grok 4.6 es multimodal y, por tanto, puede manejar imágenes. 

Enviar una imagen por URL

La forma más sencilla de pasar una imagen al modelo es mediante una URL. Podemos proporcionarla como segundo argumento del mensaje del usuario:

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

Enviar una imagen subiéndola como archivo

A menudo queremos usar imágenes locales en vez de URLs. Esto se puede hacer cargando la imagen como una cadena base64. La función encode_image() puede hacerlo por nosotros:

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 vez codificada, se la pasamos al modelo de la misma manera:

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

A pesar de admitir entrada de imagen, Grok 4.6 solo produce texto. Si quieres saber más sobre la generación de imágenes en SpaceXAI, te recomiendo leer nuestro tutorial de la Grok Imagine API.

¿Cómo habilito herramientas con agentes de Grok 4.6?

Grok 4.6 da acceso a tres herramientas útiles del lado del servidor y permite crear herramientas personalizadas.

Llamar a herramientas del servidor (búsqueda web, búsqueda en X, ejecución de código)

Grok 4.6 viene con tres herramientas de servidor:

• Búsqueda web: permite al agente hacer búsquedas para fundamentar la respuesta.
• Búsqueda en X: consulta datos en tiempo real de la plataforma X.
• Ejecución de código: ejecuta código en un sandbox para ayudar a responder la consulta.

Estas herramientas se ejecutan en los servidores de SpaceXAI, y cada llamada se factura independientemente de los tokens.

Para habilitarlas, debemos importarlas y proporcionarlas al instanciar el 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()],
)

Al hacer streaming de las respuestas, podemos saber si el agente usa una herramienta comprobando la marca chunk.tool_calls.

Aquí tienes un fragmento para procesar la respuesta en streaming y mostrar cuándo el agente usa una herramienta:

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)

Puedes ver un script completo con herramientas de servidor en el repositorio de GitHub que lo acompaña.

Implementar herramientas locales personalizadas

Además de las herramientas anteriores, también podemos equipar nuestro agente con Grok 4.6 con herramientas personalizadas. Veamos cómo implementar herramientas que permitan al agente leer y escribir archivos locales.

Para implementar una herramienta personalizada, necesitamos dos cosas:

1. Una especificación de la herramienta usando el objeto oficial tool() del SDK de SpaceXAI.

2. Una implementación en Python de la herramienta, es decir, el código que queremos ejecutar cuando se invoque.

Una especificación de herramienta consta de:

• El nombre de la función de Python a llamar.
• Una descripción que explica qué hace la herramienta. Es crucial porque determina cuándo el agente la invoca.
• La especificación de parámetros de la función.

Abajo tienes una función con la que implementar una herramienta que lee archivos locales:

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

Por seguridad, implementamos la herramienta para que siempre pida permiso al usuario antes de leer un archivo. Esto evita proporcionar datos privados al agente por accidente.

Esta es la especificación de la herramienta para esa función:

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

El código para escribir en un archivo es similar y se encuentra en el archivo tools.py del repositorio.

¿Cómo ejecutar un bucle de agente con herramientas en Grok 4.6?

En esta sección, juntamos todo lo aprendido para construir un bucle agentico con Grok 4.6 donde podamos conversar con un agente capaz de realizar trabajo real actuando sobre archivos locales y fundamentando respuestas con datos en línea mediante búsquedas.

El agente funcionará como muestra el diagrama siguiente. El usuario envía un prompt, el agente responde usando herramientas si hace falta. Después, la respuesta vuelve al usuario, que puede seguir interactuando con el agente. 

El agente lleva la cuenta de toda la conversación usando chat.append() para añadir prompts del usuario, respuestas y resultados de herramientas. Un resultado de herramienta debe envolverse en una instancia de tool_result().

Aquí tienes la implementación completa del 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")

Probar el agente de Grok 4.6 con un análisis de cartera de acciones

Para probar el agente, creé un archivo CSV de ejemplo con una cartera de acciones. Es bastante simple y lista los valores, mostrando en particular la fecha y el precio de compra. 

La idea es pedirle al agente que:

1. Cargue el archivo CSV.
2. Haga una búsqueda web para obtener los precios actuales de cada valor.
3. Actualice el CSV añadiendo una nueva columna con los precios actuales.
4. Le pidamos crear un informe de la cartera con las últimas novedades de nuestros sectores.

Abajo tienes una captura de la interacción con el agente para los pasos del 1 al 3.

Observamos que utilizó búsqueda web, ejecución de código y las herramientas personalizadas que creamos para leer y escribir archivos locales. Al final, actualizó el CSV añadiendo una columna con los precios actuales.

Como el agente funciona en bucle, podemos continuar la conversación. En la siguiente interacción, le pedí que buscara noticias sobre esos valores, analizara la diversidad de la cartera y creara un informe en markdown.

Si te pica la curiosidad sobre el informe que generó, está en el repositorio de GitHub.

Probar el agente en una tarea real como analizar una cartera de acciones muestra de lo que es capaz Grok 4.6. Al buscar en la web, ejecutar código y usar herramientas locales por sí mismo, el modelo resuelve con facilidad peticiones complejas.

Caché de prompts y el “precipicio” de los 200k

Al implementar un agente multi-turno, debemos asegurarnos de que la conversación se cachea para que el modelo no tenga que reprocesar todo el historial en cada interacción. No hacerlo puede disparar los costes.

El caché funciona de forma automática, pero las entradas se almacenan por servidor y, por defecto, las peticiones pueden enrutarse a servidores distintos y perder la caché. Para maximizar aciertos, proporcionamos un identificador de conversación estable para que todas las peticiones de una conversación vayan al mismo servidor. Cómo pasarlo depende de la API:

• xai-sdk (gRPC): x-grok-conv-id, como metadata gRPC al inicializar el cliente

• OpenAI Responses API: prompt_cache_key, en el cuerpo de la petición

El siguiente fragmento muestra cómo hacerlo:

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]

Una consideración importante es que la penalización económica se vuelve especialmente severa en conversaciones extensas. Cuando la longitud total del prompt alcanza o supera los 200k tokens, la API aplica un multiplicador de 2x y factura toda la petición al doble de la tarifa estándar.

Para evitar que los bucles multi-turno superen ese umbral de 200k, es muy recomendable implementar compactación de contexto. Se consigue resumiendo periódicamente los turnos antiguos o deslizando la ventana de contexto. Así seguirás beneficiándote de aciertos de caché baratos en tus instrucciones principales y evitarás las fuertes penalizaciones de una ventana de contexto que crece sin fin.

Conclusión

En este tutorial, aprendimos a usar la API de SpaceXAI con Python para interactuar con Grok 4.6. Vimos lo básico para enviar prompts de texto e imagen y cómo manejar la salida para que el usuario sepa en qué está trabajando el modelo. 

Al aprender a proporcionar herramientas al modelo, pudimos juntar todo y crear un agente de IA capaz de usar Grok 4.6 para resolver tareas reales como analizar una cartera bursátil. Por último, vimos que ejecutar tareas con contextos largos puede ser carísimo, sobre todo si no usamos caché.

Como ejercicio para afianzar lo aprendido, te sugiero implementar caché en el agente y actualizar la salida para mostrar también los tokens de razonamiento. 

Si quieres profundizar en la creación de agentes de IA con APIs, te recomiendo nuestro curso Working with the OpenAI API. El mejor lugar para ir a fondo en agentes de IA es el itinerario de aprendizaje AI Agent Fundamentals.