API Grok 4.6: do primeiro call a um agente que usa ferramentas

Como configurar a API do Grok 4.6 em Python?

Para começar, você vai precisar de uma chave da API da SpaceXAI e instalar o xai-sdk.

Obtendo uma chave de API no console.x.ai

Para criar uma chave da API do Grok 4.6, acesse a página de criação de chaves da SpaceX AI console. Depois, clique no botão Create API Key no canto superior direito.

O formulário de criação é simples. Dê um nome à chave para identificar a qual projeto ela pertence. Também recomendo sempre definir uma data de expiração como proteção caso a chave seja comprometida.

Quando a chave for gerada, copie e cole em um arquivo chamado .env que você vai criar na mesma pasta onde ficará seu script Python. Assim fica fácil carregar a chave no script sem deixá-la no arquivo de código — o que facilitaria o vazamento ao compartilhar ou enviar o código para a nuvem.

O arquivo .env deve ter o seguinte conteúdo:

XAI_API_KEY=replace_with_the_api_key

Instalando xai-sdk e carregando a chave da SpaceXAI

Para conectar à SpaceXAI com a chave, usamos o pacote xai-sdk. É uma boa prática criar um ambiente separado para cada projeto e evitar conflitos de dependências com outros projetos. Vamos usar o Anaconda com o 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

Com o ambiente ativo, instalamos os pacotes desejados. Por ora, vamos começar com:

• xai-sdk: pacote oficial da SpaceXAI para fazer chamadas à API.

• python-dotenv: utilitário que facilita carregar a chave do arquivo .env.

Para instalar, use:

pip install xai-sdk python-dotenv

Veja como carregar a chave e criar um Client da SpaceXAI em Python:

from dotenv import load_dotenv
from xai_sdk import Client

load_dotenv()

client = Client()

Note que esse código ainda não faz uma requisição. Vamos ver isso a seguir.

Comprando créditos da API SpaceXAI

Para usar a API do Grok 4.6, você também precisa comprar créditos na plataforma. Sem créditos, as requisições serão rejeitadas. Para isso, vá até Credits no fim da barra lateral, clique em Add credits e adicione o valor desejado.

Quanto custa usar o Grok 4.6 via API?

As requisições ao Grok 4.6 são cobradas por token. O preço base é de US$ 2 por milhão de tokens de entrada e US$ 6 por milhão de tokens de saída.

É importante notar que o Grok 4.6 é um modelo de raciocínio. O raciocínio é feito como um "autodiálogo" e também consome tokens, cobrados como tokens de saída. Vamos ver adiante como controlar a quantidade de raciocínio que o modelo realiza em cada requisição.

Tokens em cache são muito mais baratos, custando apenas US$ 0,50 por milhão de tokens.

Como veremos, o Grok tem três ferramentas nativas que são cobradas separadamente dos tokens: busca na web, busca no X e execução de código. Todas custam US$ 5,00 por 1.000 chamadas.

Para contextos longos, vale notar que todos os tokens em prompts que excedem 200K são cobrados ao dobro da taxa.

Como fazer sua primeira chamada à API do Grok 4.6?

Vamos aproveitar o código anterior para usar o cliente da SpaceXAI e enviar uma requisição ao Grok 4.6.

Para enviar a requisição, iniciamos uma sessão de chat apontando para grok-4.6 com client.chat.create() e adicionamos nosso prompt ao histórico com chat.append(user()).

Por fim, chamando chat.sample() enviamos a conversa para o modelo gerar uma resposta, que exibimos com 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 o Grok assim, recebemos a resposta de uma vez só, então precisamos esperar o modelo terminar para ver algo. Podemos ter uma resposta palavra por palavra usando streaming.

Streaming de respostas

Em vez de esperar a resposta completa com chat.sample(), podemos usar chat.stream() para receber a saída do modelo em tempo real.

# … Mesmo código de 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()

Esse código itera sobre o stream, entregando blocos incrementais e imprimindo cada novo trecho (chunk.content) no console assim que chega, criando uma experiência de streaming token a token.

Ao executar, você vai notar que o modelo ainda leva um tempo para começar a produzir tokens. Isso acontece porque o Grok 4.6 é um modelo de raciocínio. Por padrão, antes de gerar a primeira palavra visível da resposta final, o modelo passa por uma fase interna de raciocínio em "chain-of-thought".

Podemos ajustar o código acima para também exibir o processo de raciocínio do modelo, assim:

# … Mesmo código de 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()

O stream do Grok 4.6 após esse trecho entrega dois tipos de tokens:

• Os tokens internos de chain-of-thought do modelo
• A resposta final

O script diferencia os dois verificando chunk.reasoning_content para transmitir primeiro o passo a passo do raciocínio e, depois, imprimindo chunk.content quando a resposta final começa.

Como definir o esforço de raciocínio no Grok 4.6?

Como vimos, assim como outros modelos de fronteira, o Grok 4.6 depende de uma chain-of-thought oculta. Antes de mostrar uma única palavra da resposta final, ele pode gerar milhares de tokens de raciocínio para explorar soluções, checar a lógica e corrigir erros.

O parâmetro reasoning_effort permite controlar quanto esforço o modelo dedica a esse processo. Como também pagamos pelos tokens de raciocínio, não só pela resposta final, esse parâmetro é essencial para gerenciar custos.

O Grok 3 mini já permitia ajustar o reasoning_effort, mas o Grok 4 removeu esse controle. O raciocínio ficava sempre ativado e não podia ser ajustado. A SpaceXAI voltou a oferecer o controle na linha 4.x (4.3 e 4.5), e o Grok 4.6 também suporta com os níveis low, medium, high (padrão) e xhigh.

Para definir o esforço, usamos o parâmetro reasoning_effort ao inicializar o chat com client.chat.create(). O valor é uma string com o nível desejado. O padrão é "high". Veja como definir para "low":

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

Comparando low vs high com o mesmo prompt

Testei várias tarefas usando low e high, como criar um joguinho, montar um script para analisar dados de folha de pagamento com vários formatos de moeda bagunçados e resolver puzzles lógicos.

Em todos esses casos, o modelo conseguiu entregar soluções semelhantes com raciocínio baixo ou alto.

Para fazer diferença, precisamos de uma tarefa em que parar no meio do raciocínio cause falha. Por isso, escolhi um puzzle com muitas soluções. Eis o prompt que usei:

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.

Em ambos os níveis, o Grok 4.6 encontrou soluções corretas. Porém, com low, o orçamento de raciocínio acabou antes de concluir a tarefa, resultando em resposta incompleta. Com high, o Grok 4.6 encontrou todas as 264 soluções.

Para comparar: com low, ele usou 16.422 tokens de raciocínio; com high, usou 56.455.

Quando vale a pena usar xhigh, mesmo gastando mais tokens?

Se o nível high já consegue fazer força bruta em puzzles lógicos complexos e scripts de parsing de dados, por que alguém pagaria pelo consumo massivo de tokens do xhigh?

Acredito que, para 99% das tarefas do dia a dia em programação e ciência de dados, xhigh é exagero e só vai queimar seu orçamento.

Porém, xhigh se torna indispensável quando você deixa de pedir que o modelo atue como assistente de código e passa a exigir que ele funcione como um agente autônomo. Essencialmente, você está pagando para o modelo revisar agressivamente o próprio trabalho, seguir becos sem saída e reescrever a lógica antes de mostrar a saída final.

Meu conselho é começar com low e só aumentar se o modelo falhar sistematicamente na tarefa. É verdade que, em alguns casos, você vai pagar várias vezes pela mesma questão, mas na maioria das vezes vai obter uma boa solução pagando só uma fração do custo.

Como enviar imagens para a API do Grok 4.6?

O Grok 4.6 é multimodal e, portanto, consegue processar imagens.

Enviando uma imagem por URL

A forma mais simples é usar uma URL. Podemos passá-la como segundo argumento da mensagem do usuário:

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

Enviando uma imagem por upload de arquivo

Muitas vezes, queremos usar imagens locais, não URLs. Dá para fazer isso carregando a imagem como string base64. A função encode_image() faz isso pra gente:

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

Depois de codificada, passamos a imagem ao modelo da mesma forma:

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

Apesar de aceitar imagens como entrada, o Grok 4.6 só gera texto. Se quiser saber mais sobre geração de imagens na SpaceXAI, recomendo ler nosso tutorial da Grok Imagine API.

Como habilitar ferramentas com agentes Grok 4.6?

O Grok 4.6 dá acesso a três ferramentas server-side úteis e permite criar ferramentas personalizadas.

Chamando ferramentas server-side (busca na web, busca no X, execução de código)

O Grok 4.6 vem com três ferramentas no servidor:

• Web search: permite ao agente fazer buscas e embasar a resposta.
• X search: consulta dados em tempo real da plataforma X.
• Code execution: executa código em um sandbox para ajudar a responder.

Essas ferramentas rodam nos servidores da SpaceXAI, e cada chamada é cobrada independentemente dos tokens.

Para habilitá-las, importe e passe ao instanciar o chat com 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()],
)

Ao transmitir respostas por streaming, dá para saber se o agente está usando uma ferramenta verificando a flag chunk.tool_calls.

Aqui vai um trecho para processar o streaming de forma a mostrar ao usuário quando o agente usa uma ferramenta:

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)

Um script completo com ferramentas server-side está no repositório GitHub de apoio.

Implementando ferramentas locais personalizadas

Além das ferramentas server-side, também podemos equipar nosso agente Grok 4.6 com ferramentas personalizadas. Vamos ver como implementar ferramentas para o agente ler e escrever arquivos locais.

Para criar uma ferramenta personalizada, precisamos de duas coisas:

1. Uma especificação da ferramenta usando o objeto oficial tool() do SDK da SpaceXAI.

2. Uma implementação em Python — o código que será executado quando a ferramenta for chamada.

Uma especificação de ferramenta consiste em:

• Nome da função Python a ser chamada.
• Uma descrição que explica o que a ferramenta faz. Isso é crucial, pois determina quando o agente vai chamá-la.
• A especificação dos parâmetros da função.

Abaixo está uma função para implementar uma ferramenta que lê arquivos locais:

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 segurança, a ferramenta sempre pede permissão antes de ler um arquivo. Isso evita expor dados privados ao agente sem querer.

Veja a especificação da ferramenta para essa função:

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

O código para escrever em arquivo é similar e está no arquivo tools.py do repositório.

Como rodar um loop de agente que usa ferramentas com o Grok 4.6?

Nesta seção, vamos juntar tudo para construir um loop agentic com o Grok 4.6, no qual conversamos com um agente capaz de executar trabalho de verdade atuando em arquivos locais e embasando respostas com dados online via busca.

O agente funciona como no diagrama abaixo. O usuário envia um prompt, o agente responde usando ferramentas quando necessário. Em seguida, a resposta volta para o usuário, que pode seguir interagindo com o agente.

O agente acompanha toda a conversa usando chat.append() para anexar prompts, respostas e resultados de ferramentas. Um resultado de ferramenta deve ser embrulhado em uma instância de tool_result().

Aqui está a implementação completa do 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")

Testando o agente Grok 4.6 para analisar uma carteira de ações

Para testar o agente, criei um arquivo CSV de exemplo com uma carteira de ações. O arquivo é simples e lista os papéis, incluindo a data de compra e o preço pago.

A ideia é pedir para o agente:

1. Carregar o arquivo CSV.
2. Fazer uma busca na web para obter os preços atuais de cada papel.
3. Atualizar o CSV adicionando uma nova coluna com os preços atuais.
4. Pedir um relatório da carteira com os últimos destaques dos setores.

Abaixo está um screenshot da interação com o agente nos passos 1 a 3.

Percebemos que ele usou busca na web, execução de código e as ferramentas personalizadas para ler e escrever arquivos locais. No fim, atualizou o CSV com uma nova coluna contendo os preços atuais.

Como o agente roda em loop, podemos continuar a conversa. Na interação seguinte, pedi que buscasse notícias relacionadas a esses papéis, analisasse a diversidade da carteira e criasse um relatório em markdown.

Se tiver curiosidade de ver o relatório gerado, ele está no repositório do GitHub.

Testar o agente em uma tarefa do mundo real, como analisar uma carteira de ações, mostra bem do que o Grok 4.6 é capaz. Usando buscas na web, executando código e acionando ferramentas locais sozinho, o modelo lida com solicitações complexas com facilidade.

Cache de prompts e o "penhasco" de preço em 200k

Ao implementar um agente multi-turn, garanta que a conversa esteja em cache para o modelo não reprocessar todo o histórico a cada interação. Ignorar isso pode gerar custos altos.

O cache acontece automaticamente, mas as entradas são armazenadas por servidor e, por padrão, as requisições podem ser roteadas para servidores diferentes, perdendo o cache. Para maximizar acertos de cache, forneça um identificador estável da conversa para que todas as requisições cheguem ao mesmo servidor. Como passar isso depende da API:

• xai-sdk (gRPC): x-grok-conv-id, passado como metadata gRPC ao inicializar o client

• OpenAI Responses API: prompt_cache_key, definido no corpo da requisição

O trecho abaixo mostra como fazer:

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]

Uma consideração importante: a penalidade financeira fica especialmente severa em conversas extensas. Quando o total do seu prompt atinge ou supera 200k tokens, a API aplica um multiplicador de 2x, cobrando a requisição inteira ao dobro da taxa.

Para evitar que loops multi-turn ultrapassem esse limite de 200k, é altamente recomendável implementar compactação de contexto. Isso é feito resumindo periodicamente as interações mais antigas ou usando uma janela deslizante. Assim você continua aproveitando cache barato nas instruções centrais e evita as penalidades de uma janela de contexto que cresce sem fim.

Conclusão

Neste tutorial, vimos como usar a API da SpaceXAI com Python para interagir com o Grok 4.6. Aprendemos o básico para enviar prompts de texto e imagem e como lidar com a saída para deixar claro ao usuário no que o modelo está trabalhando.

Ao aprender a fornecer ferramentas ao modelo de IA, conseguimos juntar tudo e criar um agente capaz de usar o Grok 4.6 para resolver tarefas do mundo real, como analisar uma carteira de ações. Por fim, vimos que executar tarefas com contexto longo pode sair caríssimo, especialmente se não usarmos cache.

Como exercício, sugiro implementar cache no agente e atualizar a saída para exibir também os tokens de raciocínio.

Se você quiser aprofundar seus conhecimentos em construção de agentes de IA com APIs, recomendo nosso curso Working with the OpenAI API. Para se aprofundar de verdade em agentes de IA, confira a trilha de habilidades AI Agent Fundamentals.