API-ul Grok 4.6: de la primul apel la un agent care folosește unelte

Cum configurezi API-ul Grok 4.6 în Python?

Pentru a începe, ai nevoie de o cheie de API SpaceXAI și să instalezi xai-sdk.

Obținerea unei chei de API din console.x.ai

Pentru a crea o cheie de API Grok 4.6, navigăm la pagina de creare a cheii de API din consola SpaceX AI. Apoi, dăm click pe butonul Create API Key din colțul din dreapta sus.

Formularul de creare a cheii de API este simplu. Dăm cheii un nume pentru a recunoaște proiectul căruia îi aparține. Îți recomand, de asemenea, să setezi mereu o dată de expirare pentru cheile de API, ca măsură de siguranță în cazul în care sunt compromise.

După ce cheia este generată, o copiem și o lipim într-un fișier numit .env pe care îl creăm în același folder în care vom scrie scripturile Python. Astfel, putem încărca ușor cheia în script fără să fie prezentă în fișierul de cod, ceea ce ne-ar putea duce ușor la expunerea accidentală a cheii când partajăm sau încărcăm codul în cloud.

Fișierul .env ar trebui să conțină următoarele:

XAI_API_KEY=replace_with_the_api_key

Instalarea xai-sdk și încărcarea cheii de API SpaceXAI

Pentru a te conecta la SpaceXAI cu cheia de API, folosim pachetul xai-sdk. Este o bună practică să creezi un mediu separat pentru fiecare proiect, pentru a preveni conflictele între pachetele Python din proiecte diferite. Pentru asta, vom folosi Anaconda cu următoarea comandă:

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

Odată activat, putem instala pachetele dorite. Pentru început, să instalăm:

• xai-sdk: Pachetul oficial SpaceXAI folosit pentru a face cereri către API-ul lor.

• python-dotenv: Un pachet utilitar care ușurează încărcarea cheii de API din fișierul .env.

Pentru a le instala, folosim comanda:

pip install xai-sdk python-dotenv

Iată cum putem încărca cheia de API și crea un Client SpaceXAI în Python:

from dotenv import load_dotenv
from xai_sdk import Client

load_dotenv()

client = Client()

Reține că acest cod nu face încă o cerere. Învățăm cum să facem asta în continuare.

Achiziția de credite pentru SpaceXAI API

Pentru a folosi API-ul Grok 4.6, trebuie să cumperi și credite pe platforma lor de API. Fără acestea, cererile API vor fi respinse. Pentru a face asta, mergi la Credits în partea de jos a barei laterale, apasă pe Add credits și adaugă suma dorită.

Cât de scump este Grok 4.6 prin API?

Cererile către Grok 4.6 sunt taxate per token. Prețul de bază este 2 USD per milion de tokeni de input și 6 USD per milion de tokeni de output.

Este important de reținut că Grok 4.6 este un model de raționare. Raționamentul se desfășoară ca un autodialog și consumă, de asemenea, tokeni, care sunt taxați ca tokeni de output. Vom învăța mai târziu cum să controlăm cantitatea de raționament pe care o face modelul pentru o anumită cerere.

Tokenii din cache sunt mult mai ieftini, costând doar 0,5 USD per milion de tokeni.

După cum vom vedea, Grok are trei unelte integrate care sunt taxate separat de tokeni: căutare web, căutare X și execuție de cod. Toate costă 5,00 USD per 1.000 de apeluri.

Pentru contexte lungi, merită menționat că toți tokenii din prompturi care depășesc pragul de 200K sunt taxați la dublu.

Cum faci primul apel API către Grok 4.6?

Să construim pe baza codului anterior pentru a folosi clientul SpaceXAI pentru a trimite o cerere către Grok 4.6.

Pentru a trimite o cerere către Grok 4.6, inițializăm o sesiune de chat care țintește grok-4.6 cu client.chat.create() și adăugăm promptul nostru la istoricul conversației folosind chat.append(user()).

În final, apelul chat.sample() trimite conversația către model pentru a genera un răspuns, pe care îl afișăm prin printarea 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)

Folosind Grok în acest fel, primim răspunsul dintr-o dată, așa că trebuie să așteptăm până când Grok termină de generat întregul răspuns înainte de a primi ceva. Putem obține un răspuns cuvânt cu cuvânt folosind streaming. 

Streamingul răspunsului

În loc să așteptăm răspunsul complet cu chat.sample(), putem folosi chat.stream() pentru a primi outputul modelului în timp real.

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

Acest cod iterează peste stream, returnând incremental obiecte de tip „chunk” și tipărind fiecare nou fragment de text (chunk.content) în consolă imediat ce sosește, creând o experiență de streaming receptivă, token cu token.

Când rulăm acest cod, observăm că tot îi ia modelului ceva timp până începe să producă tokeni. Motivul este că Grok 4.6 este un model de raționare. Implicit, înainte de a genera primul cuvânt vizibil al răspunsului final, modelul trece printr-o fază internă de raționare „chain-of-thought”.

Putem actualiza codul de mai sus pentru a afișa și procesul de raționare al modelului, astfel:

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

Streamul Grok 4.6 după acest snippet livrează două tipuri de tokeni:

• Tokenii interni ai lanțului de gândire al modelului
• Răspunsul final

Acest script le diferențiază verificând chunk.reasoning_content pentru a difuza mai întâi procesul pas cu pas al gândirii lui Grok, apoi tipărind chunk.content odată ce începe răspunsul final.

Cum setezi efortul de raționare în Grok 4.6?

După cum am văzut mai sus, la fel ca alte modele frontieră, Grok 4.6 se bazează pe un lanț de gândire ascuns. Înainte să afișeze un singur cuvânt din răspunsul final, generează mii de tokeni de raționare pentru a explora soluții, a-și verifica logica și a-și corecta greșelile.

Parametrul reasoning_effort ne permite să controlăm cât efort depune modelul în acest proces de raționare. Pentru că plătim și pentru tokenii de raționare, nu doar pentru răspunsul final, acesta este un parametru important de gestionat dacă vrem să reducem costurile.

Grok 3 mini le permitea deja dezvoltatorilor să regleze reasoning_effort, dar Grok 4 a eliminat acel control. Raționarea era mereu activă și nu putea fi ajustată. SpaceXAI a reintrodus controlul pe linia Grok 4.x (4.3 și 4.5), iar Grok 4.6 îl acceptă și el, cu low, medium, high (implicit) și xhigh.

Pentru a seta efortul de raționare, folosim parametrul reasoning_effort când inițializăm chatul cu client.chat.create(). Valoarea este un string cu nivelul dorit. Valoarea implicită este "high". Iată un exemplu în care îl setăm la "low":

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

Comparând low vs high pe același prompt

Am încercat multe sarcini folosind atât raționare low, cât și high, precum construirea unui joc mic, crearea unui script pentru analizarea datelor de salarii cu multiple formate de monedă prost formate și rezolvarea de puzzle-uri logice.

În toate aceste cazuri, modelul a putut oferi soluții similare atât cu raționare low, cât și high.

Pentru a vedea o diferență, avem nevoie de o sarcină în care oprirea la mijlocul raționării duce la eșec. Așa că am ales un puzzle cu multe soluții. Iată promptul pe care l-am folosit:

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.

La ambele niveluri de raționare, Grok 4.6 a găsit soluții corecte. Totuși, când a fost setat pe low, bugetul de raționare s-a epuizat înainte să poată finaliza sarcina. Prin urmare, a răspuns cu o soluție incompletă. Cu un nivel ridicat de raționare, Grok 4.6 a găsit toate cele 264 de soluții.

Pentru comparație, cu raționare low, a folosit 16.422 tokeni de raționare, în timp ce cu high a folosit 56.455.

Când merită xhigh numărul suplimentar de tokeni?

Dacă setarea high poate rezolva prin forță brută puzzle-uri logice complexe și scripturi de parsare a datelor, de ce ar plăti cineva pentru consumul masiv de tokeni al xhigh?

Cred că pentru 99% dintre sarcinile zilnice de programare și data science, xhigh este excesiv și îți va consuma doar bugetul de API.

Totuși, xhigh devine indispensabil când treci de la a cere modelului să acționeze ca un asistent de programare la a-l cere să acționeze ca un agent autonom. Practic, plătești pentru ca modelul să își revizuiască agresiv munca, să ajungă în impasuri și să își rescrie logica înainte să îți arate vreodată outputul final.

Sfatul meu ar fi să începi cu low și să îl crești doar dacă modelul eșuează sistematic într-o sarcină. E adevărat că în unele cazuri asta înseamnă că vom plăti de mai multe ori pentru aceeași problemă, dar de cele mai multe ori vom obține o soluție bună plătind doar o fracțiune din cost.

Cum trimiți imagini către API-ul Grok 4.6?

Grok 4.6 este multimodal și, ca atare, poate gestiona date de tip imagine. 

Trimiterea unei imagini prin URL

Cel mai simplu mod de a furniza o imagine modelului este printr-un URL. O putem oferi ca al doilea argument al mesajului utilizatorului:

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

Trimiterea unei imagini prin încărcarea unui fișier

Adesea, vrem să folosim imagini locale, nu URL-uri. Acest lucru se poate face încărcând imaginea ca string base64. Funcția encode_image() poate face asta pentru noi:

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

După ce imaginea este encodată, o furnizăm modelului în același mod:

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

Deși acceptă input de tip imagine, Grok 4.6 produce doar text ca output. Dacă vrei să afli mai multe despre generarea de imagini cu SpaceXAI, îți recomand să citești tutorialul nostru despre Grok Imagine API.

Cum activez uneltele pentru agenții Grok 4.6?

Grok 4.6 oferă acces la trei unelte utile pe server și posibilitatea de a crea unelte personalizate.

Apelarea uneltelor pe server (căutare web, căutare X, execuție de cod)

Grok 4.6 vine echipat cu trei unelte pe server:

• Căutare web: Permite agentului să efectueze o căutare web pentru a ancora răspunsul în informații.
• Căutare X: Interoghează date în timp real de pe platforma X.
• Execuție de cod: Rulează cod într-un sandbox pentru a ajuta la răspuns.

Aceste unelte rulează pe serverele SpaceXAI, iar fiecare apel de unealtă este taxat independent de tokeni.

Pentru a le activa, trebuie să le importăm și să le furnizăm când instanțiem chatul cu 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()],
)

Când facem streaming al răspunsurilor, putem ști dacă agentul folosește o unealtă verificând flagul chunk.tool_calls.

Iată un snippet despre cum să procesezi răspunsul în streaming într-un mod care îi arată utilizatorului când agentul folosește o unealtă:

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 exemplu complet de script cu unelte pe server poate fi găsit în repo-ul meu de pe GitHub.

Implementarea de unelte locale personalizate

Pe lângă uneltele de server de mai sus, putem echipa agentul nostru Grok 4.6 și cu unelte personalizate. Să vedem cum putem implementa unelte care îi permit agentului să citească și să scrie fișiere locale.

Pentru a implementa o unealtă personalizată, avem nevoie de două lucruri:

1. O specificație de unealtă folosind obiectul oficial tool() din SDK-ul SpaceXAI.

2. O implementare Python a uneltei, adică codul pe care vrem să îl executăm când unealta este apelată.

O specificație de unealtă constă în:

• Numele funcției Python de apelat.
• O descriere care explică ce face unealta. Acest lucru este esențial pentru că determină când agentul apelează unealta.
• Specificația parametrilor funcției.

Mai jos este o funcție pe care o putem folosi pentru a implementa o unealtă care citește fișiere locale:

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

Din motive de siguranță, am implementat unealta astfel încât să ceară mereu permisiunea utilizatorului înainte de a citi un fișier. Aceasta previne furnizarea accidentală de date private agentului.

Iată specificația uneltei pentru această funcție:

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

Codul pentru scrierea într-un fișier este similar și poate fi găsit în fișierul tools.py din repository.

Cum rulezi un loop de agent care folosește unelte cu Grok 4.6?

În această secțiune, punem cap la cap tot ce am învățat pentru a construi un loop agentic Grok 4.6 în care putem vorbi cu un agent capabil să efectueze muncă reală acționând asupra fișierelor locale, ancorând în același timp răspunsurile cu date online prin căutare.

Agentul va funcționa așa cum se arată în diagrama de mai jos. Utilizatorul trimite un prompt, apoi agentul răspunde folosind unelte dacă este necesar. Apoi răspunsul este trimis înapoi utilizatorului, iar utilizatorul poate continua să interacționeze cu agentul. 

Agentul ține evidența întregii conversații folosind funcția chat.append() pentru a adăuga prompturile utilizatorului, răspunsurile și rezultatele uneltelor. Un rezultat de unealtă trebuie încapsulat într-o instanță tool_result().

Iată implementarea completă a agentului:

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

Testarea agentului Grok 4.6 pentru a efectua o analiză a portofoliului de acțiuni

Pentru a testa agentul, am creat un fișier CSV de exemplu pentru un portofoliu de acțiuni. Fișierul este destul de simplu și listează acțiuni, indicând în special data achiziției și prețul de cumpărare. 

Ideea este să îi cerem agentului să:

1. Încarce fișierul CSV.
2. Facă o căutare pe web pentru a obține prețurile curente ale fiecărei acțiuni.
3. Actualizeze CSV-ul adăugând o nouă coloană cu prețurile curente.
4. Să creeze un raport despre portofoliu care arată ultimele evoluții din sectoarele noastre.

Mai jos este o captură de ecran a interacțiunii cu Agentul pentru pașii 1 până la 3.

Observăm că a folosit căutarea web, execuția de cod și uneltele personalizate pe care le-am creat pentru a citi și a scrie fișiere locale. La final, a actualizat fișierul CSV adăugând o nouă coloană cu prețurile curente ale acțiunilor.

Deoarece agentul rulează într-un loop, putem continua conversația. În interacțiunea următoare, i-am cerut să caute știri legate de aceste acțiuni, să analizeze diversitatea portofoliului și să creeze un raport în markdown.

Dacă ești curios de raportul pe care l-a creat, îl găsești în repository-ul GitHub.

Testarea agentului pe o sarcină din lumea reală, precum analizarea unui portofoliu de acțiuni, arată cu adevărat ce poate face Grok 4.6. Folosind căutări pe web, rulând cod și apelând singur la unelte locale, modelul gestionează cu ușurință cereri complicate.

Caching-ul prompturilor și pragul de preț de 200k

Când implementăm un agent cu mai multe turnuri de conversație, ar trebui să ne asigurăm că discuția este pusă în cache, astfel încât modelul să nu fie nevoit să reprocesoze întregul istoric la fiecare interacțiune. Dacă nu facem asta, costurile pot deveni uriașe.

Caching-ul se întâmplă automat, dar intrările din cache sunt stocate per server, iar în mod implicit, cererile pot fi rutate către servere diferite și pot rata cache-ul. Pentru a maximiza hit-urile din cache, oferim un identificator stabil al conversației, astfel încât toate cererile dintr-o conversație să ajungă la același server. Modul în care îl transmiți depinde de API:

• xai-sdk (gRPC): x-grok-conv-id, transmis ca metadata gRPC când clientul este inițializat

• OpenAI Responses API: prompt_cache_key, setat în corpul cererii

Snippetul următor arată cum să faci acest lucru:

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]

O considerație importantă este că penalizarea financiară devine deosebit de severă pentru conversații extinse. Odată ce lungimea totală a promptului ajunge sau depășește 200k tokeni, API-ul aplică un multiplicator de 2x, taxând întreaga cerere la dublul tarifului standard.

Pentru a preveni ca buclele cu mai multe turnuri să treacă peste acest prag de 200k, este foarte recomandată implementarea compactării contextului. Acest lucru se face prin rezumarea periodică a tururilor mai vechi ale conversației sau prin glisarea ferestrei de context. Această strategie asigură că beneficiezi în continuare de hit-uri ieftine în cache pe instrucțiunile de bază, evitând în același timp penalitățile financiare severe ale unei ferestre de context care crește la nesfârșit.

Concluzie

În acest tutorial, am învățat cum să folosim SpaceXAI API cu Python pentru a interacționa cu Grok 4.6. Am învățat elementele de bază despre cum să trimitem prompturi text și imagine și cum să gestionăm outputul pentru a-i spune utilizatorului la ce lucrează modelul. 

Învățând cum să oferim unelte modelului AI, am putut apoi să punem toate acestea cap la cap și să construim un agent AI capabil să folosească Grok 4.6 pentru a rezolva sarcini din lumea reală, precum analizarea unui portofoliu de acțiuni. În final, am învățat că rularea sarcinilor cu context lung poate fi incredibil de costisitoare, mai ales dacă nu folosim caching.

Ca exercițiu pentru a testa ce ai învățat aici, îți sugerez să implementezi caching în agent și să actualizezi outputul pentru a afișa și tokenii de raționare. 

Dacă vrei să îți aprofundezi cunoștințele despre construirea de agenți AI cu API-uri, îți recomand cursul Working with the OpenAI API. Cel mai bun loc pentru a intra în profunzime despre agenții AI este parcursul de abilități AI Agent Fundamentals.