Grok 4.6 API: od pierwszego wywołania do agenta korzystającego z narzędzi

Jak skonfigurować Grok 4.6 API w Pythonie?

Na start potrzebujesz klucza SpaceXAI API i instalacji xai-sdk.

Uzyskanie klucza API z console.x.ai

Aby utworzyć klucz API Grok 4.6, przechodzimy do strony tworzenia kluczy API w konsoli SpaceX AI. Następnie klikamy przycisk Create API Key w prawym górnym rogu.

Formularz tworzenia klucza API jest prosty. Nadajemy kluczowi nazwę, by wiedzieć, do którego projektu należy. Polecam też zawsze ustawiać datę wygaśnięcia kluczy API jako zabezpieczenie na wypadek kompromitacji.

Po wygenerowaniu klucza kopiujemy go i wklejamy do pliku o nazwie .env, który tworzymy w tym samym folderze, w którym będziemy pisać skrypty Pythona. Dzięki temu łatwo wczytamy klucz w skrypcie bez trzymania go w kodzie, co mogłoby skutkować przypadkowym ujawnieniem przy udostępnianiu lub wysyłaniu kodu do chmury.

Plik .env powinien zawierać następującą treść:

XAI_API_KEY=replace_with_the_api_key

Instalacja xai-sdk i wczytanie klucza SpaceXAI API

Aby połączyć się ze SpaceXAI przy użyciu klucza API, korzystamy z pakietu xai-sdk. Dobrą praktyką jest tworzenie oddzielnego środowiska dla każdego projektu, by uniknąć konfliktów między pakietami Pythona. Zrobimy to w Anacondzie poleceniem:

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

Po aktywowaniu możemy zainstalować potrzebne pakiety. Na początek:

• xai-sdk: Oficjalny pakiet SpaceXAI do wykonywania zapytań do ich API.

• python-dotenv: Pakiet ułatwiający wczytanie klucza API z pliku .env.

Instalujemy je poleceniem:

pip install xai-sdk python-dotenv

Oto jak wczytać klucz API i utworzyć klienta SpaceXAI w Pythonie:

from dotenv import load_dotenv
from xai_sdk import Client

load_dotenv()

client = Client()

Zauważ, że ten kod jeszcze nie wysyła zapytania. Za chwilę zobaczysz, jak to zrobić.

Zakup kredytów SpaceXAI API

Aby korzystać z Grok 4.6 API, musimy też kupić kredyty na ich platformie API. Bez tego zapytania będą odrzucane. Przejdź do Credits na dole paska bocznego, kliknij Add credits i dodaj preferowaną kwotę.

Ile kosztuje Grok 4.6 przez API?

Zapytania do Grok 4.6 są rozliczane per token. Bazowe ceny to 2 USD za milion tokenów wejściowych i 6 USD za milion tokenów wyjściowych.

Warto pamiętać, że Grok 4.6 to model rozumujący. Rozumowanie odbywa się w formie wewnętrznego dialogu i również zużywa tokeny, które są rozliczane jako tokeny wyjściowe. Później zobaczysz, jak kontrolować ilość rozumowania wykonywanego dla danego żądania.

Tokeny z cache są znacznie tańsze — kosztują tylko 0,5 USD za milion.

Jak zobaczysz, Grok ma trzy wbudowane narzędzia, rozliczane osobno względem tokenów: wyszukiwanie w sieci, wyszukiwanie w X i wykonanie kodu. Wszystkie kosztują 5,00 USD za 1 000 wywołań.

Przy długim kontekście pamiętaj, że wszystkie tokeny w promptach przekraczających próg 200K są rozliczane w podwójnej stawce.

Jak wykonać pierwsze wywołanie Grok 4.6 API?

Nawiążemy do poprzedniego kodu i użyjemy klienta SpaceXAI, by wysłać zapytanie do Grok 4.6.

Aby wysłać zapytanie, inicjujemy sesję czatu z celem grok-4.6 przez client.chat.create() i dodajemy nasz prompt do historii rozmowy przy użyciu chat.append(user()).

Na końcu wywołanie chat.sample() wysyła rozmowę do modelu w celu wygenerowania odpowiedzi, którą wyświetlamy przez 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)

Używając Groka w ten sposób, dostajesz odpowiedź „hurtem”, więc musisz poczekać, aż Grok wygeneruje całość. Możesz otrzymywać odpowiedź słowo po słowie, używając strumieniowania. 

Strumieniowanie odpowiedzi

Zamiast czekać na kompletną odpowiedź przez chat.sample(), możesz użyć chat.stream(), by odbierać wynik modelu w czasie rzeczywistym.

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

Ten kod iteruje po strumieniu, zwracając przyrostowe fragmenty i wypisując każdy nowy kawałek tekstu (chunk.content) do konsoli natychmiast po nadejściu, tworząc responsywne strumieniowanie token po tokenie.

Uruchamiając ten kod, zauważysz, że model potrzebuje trochę czasu, zanim zacznie generować tokeny. Powód: Grok 4.6 to model rozumujący. Domyślnie, zanim wyprodukuje pierwsze widoczne słowo finalnej odpowiedzi, przechodzi przez wewnętrzną fazę rozumowania „chain-of-thought”.

Możemy zaktualizować powyższy kod, by pokazać także proces rozumowania modelu, w ten sposób:

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

Strumień Grok 4.6 po tym fragmencie dostarcza dwa typy tokenów:

• Wewnętrzne tokeny łańcucha rozumowania modelu
• Finalną odpowiedź

Skrypt rozróżnia je, sprawdzając chunk.reasoning_content, by najpierw strumieniować krok po kroku tok myślenia Groka, a następnie wypisywać chunk.content, gdy zaczyna się finalna odpowiedź.

Jak ustawić wysiłek rozumowania w Grok 4.6?

Jak widzieliśmy, podobnie jak inne modele czołowe, Grok 4.6 opiera się na ukrytym łańcuchu myśli. Zanim wyemituje choćby jedno słowo finalnej odpowiedzi, generuje tysiące tokenów rozumowania, by eksplorować rozwiązania, sprawdzać logikę i korygować własne błędy.

Parametr reasoning_effort pozwala kontrolować, ile wysiłku model w to wkłada. Ponieważ płacimy również za tokeny rozumowania, a nie tylko finalną odpowiedź, to ważny parametr do zarządzania kosztami.

Grok 3 mini pozwalał już stroić reasoning_effort, a Grok 4 ten kontroler usunął. Rozumowanie było zawsze włączone i niepodlegające regulacji. SpaceXAI przywróciło kontrolę w linii Grok 4.x (4.3 i 4.5), a Grok 4.6 też ją wspiera, z opcjami low, medium, high (domyślna) i xhigh.

Aby ustawić wysiłek rozumowania, użyj parametru reasoning_effort przy inicjalizacji czatu przez client.chat.create(). Wartość to string z wybranym poziomem. Wartość domyślna to "high". Oto przykład ustawienia na "low":

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

Porównanie low vs high na tym samym promcie

Przetestowałem wiele zadań z low i high, takich jak budowa małej gry, tworzenie skryptu do analizy listy płac z wieloma źle sformatowanymi walutami czy rozwiązywanie łamigłówek logicznych.

We wszystkich tych przypadkach model potrafił zaproponować podobne rozwiązania zarówno przy niskim, jak i wysokim rozumowaniu.

Aby zobaczyć różnicę, potrzebujemy zadania, w którym zatrzymanie się w połowie rozumowania kończy się porażką. Sięgnąłem więc po zagadkę z wieloma rozwiązaniami. Oto użyty 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.

Na obu poziomach rozumowania Grok 4.6 znalazł poprawne rozwiązania. Jednak przy low skończył mu się budżet rozumowania, zanim ukończył zadanie, więc zwrócił niepełny wynik. Przy wysokim poziomie Grok 4.6 znalazł wszystkie 264 rozwiązania.

Dla porównania: przy low zużył 16 422 tokeny rozumowania, a przy high 56 455.

Kiedy xhigh jest wart dodatkowych tokenów?

Skoro ustawienie high potrafi siłowo rozwiązać złożone łamigłówki logiczne i skrypty parsujące dane, po co płacić za ogromny apetyt na tokeny przy xhigh?

Uważam, że dla 99% codziennych zadań programistycznych i data science xhigh to przerost formy, który tylko przepali budżet API.

Jednak xhigh staje się niezbędny, gdy prosisz model, by działał nie jako asystent kodowania, lecz jako autonomiczny agent. De facto płacisz za to, by model agresywnie recenzował własną pracę, wchodził w ślepe uliczki i przepisywał logikę, zanim pokaże ci finalny wynik.

Moja rada: zacznij od low i podnoś poziom tylko wtedy, gdy model systematycznie zawodzi przy danym zadaniu. To prawda, że czasem zapłacisz kilka razy za ten sam problem, ale najczęściej uzyskasz dobre rozwiązanie za ułamek kosztu.

Jak wysyłać obrazy do Grok 4.6 API?

Grok 4.6 jest multimodalny, więc potrafi przetwarzać obrazy. 

Wysyłanie obrazu przez URL

Najprościej przekazać obraz jako URL. Możemy podać go jako drugi argument wiadomości użytkownika:

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

Wysyłanie obrazu przez upload pliku

Często chcemy użyć obrazów lokalnych zamiast URL-i. Można to zrobić, ładując obraz jako string w base64. Funkcja encode_image() zrobi to za nas:

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

Po zakodowaniu obrazu przekazujemy go do modelu w ten sam sposób:

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

Mimo wsparcia dla wejść obrazowych, Grok 4.6 zwraca tylko tekst. Jeśli chcesz dowiedzieć się więcej o generowaniu obrazów w SpaceXAI, polecam nasz poradnik Grok Imagine API.

Jak włączyć narzędzia u agentów Grok 4.6?

Grok 4.6 udostępnia trzy przydatne narzędzia po stronie serwera i pozwala tworzyć własne narzędzia.

Wywołania narzędzi serwerowych (wyszukiwanie w sieci, wyszukiwanie w X, wykonanie kodu)

Grok 4.6 ma trzy narzędzia serwerowe:

• Wyszukiwanie w sieci: Pozwala agentowi przeprowadzić wyszukiwanie w sieci, by ugruntować odpowiedź.
• Wyszukiwanie w X: Odpytuje dane w czasie rzeczywistym z platformy X.
• Wykonanie kodu: Uruchamia kod w piaskownicy, by pomóc odpowiedzieć na zapytanie.

Te narzędzia działają na serwerach SpaceXAI, a każde wywołanie jest rozliczane niezależnie od tokenów.

Aby je włączyć, importujemy je i przekazujemy przy tworzeniu czatu przez 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()],
)

Przy strumieniowaniu odpowiedzi możemy sprawdzić, czy agent używa narzędzia, patrząc na flagę chunk.tool_calls.

Oto fragment pokazujący, jak przetwarzać strumień tak, by pokazać użytkownikowi, kiedy agent korzysta z narzędzia:

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)

Pełny przykład skryptu z narzędziami serwerowymi znajdziesz w towarzyszącym repozytorium na GitHubie.

Implementacja własnych narzędzi lokalnych

Oprócz powyższych narzędzi serwerowych możemy też wyposażyć naszego agenta Grok 4.6 we własne narzędzia. Zobaczmy, jak zaimplementować narzędzia pozwalające agentowi czytać i pisać pliki lokalnie.

Do implementacji własnego narzędzia potrzebujemy dwóch rzeczy:

1. Specyfikacji narzędzia przy użyciu oficjalnego obiektu tool() z SDK SpaceXAI.

2. Implementacji w Pythonie, czyli kodu wykonywanego przy wywołaniu narzędzia.

Specyfikacja narzędzia obejmuje:

• Nazwę funkcji Pythona do wywołania.
• Opis wyjaśniający działanie narzędzia. To kluczowe, bo determinuje, kiedy agent je wywoła.
• Specyfikację parametrów funkcji.

Poniżej funkcja implementująca narzędzie do czytania lokalnych plików:

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

Ze względów bezpieczeństwa narzędzie zawsze prosi użytkownika o zgodę przed odczytem pliku. Zapobiega to przypadkowemu przekazaniu agentowi prywatnych danych.

Oto specyfikacja narzędzia dla tej funkcji:

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

Kod zapisu do pliku jest podobny i znajdziesz go w pliku tools.py w repozytorium.

Jak uruchomić pętlę agenta korzystającego z narzędzi w Grok 4.6?

W tej sekcji łączymy wszystko w całość i budujemy agentowy loop Grok 4.6, w którym rozmawiasz z agentem zdolnym wykonywać realną pracę na lokalnych plikach, jednocześnie ugruntowując odpowiedzi danymi z wyszukiwania online.

Agent działa jak na poniższym diagramie. Użytkownik wysyła prompt, następnie agent odpowiada, używając narzędzi w razie potrzeby. Potem odpowiedź wraca do użytkownika i można kontynuować interakcję z agentem. 

Agent śledzi całą rozmowę, używając funkcji chat.append() do dopinania promptów użytkownika, odpowiedzi i wyników narzędzi. Wynik narzędzia musi być opakowany instancją tool_result().

Oto pełna implementacja agenta:

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

Testowanie agenta Grok 4.6 na analizie portfela akcji

Aby przetestować agenta, utworzyłem przykładowy plik CSV portfela akcji. Plik jest prosty i zawiera listę spółek, w tym datę zakupu i cenę zakupu. 

Chcemy poprosić agenta o:

1. Wczytanie pliku CSV.
2. Wyszukanie w sieci bieżących cen każdej ze spółek.
3. Zaktualizowanie CSV przez dodanie nowej kolumny z aktualnymi cenami.
4. Poproszenie o utworzenie raportu o naszym portfelu, który pokaże najnowsze wydarzenia w naszych sektorach.

Poniżej zrzut ekranu z interakcji z agentem dla kroków 1–3.

Widzimy, że użył wyszukiwania w sieci, wykonania kodu oraz naszych niestandardowych narzędzi do odczytu i zapisu lokalnych plików. Finalnie zaktualizował plik CSV, dodając nową kolumnę z bieżącymi cenami.

Ponieważ agent działa w pętli, możemy kontynuować rozmowę. W kolejnej interakcji poprosiłem go o sprawdzenie newsów związanych z tymi spółkami, analizę dywersyfikacji portfela i stworzenie raportu w Markdownie.

Jeśli ciekawi cię powstały raport, znajdziesz go w repozytorium na GitHubie.

Przetestowanie agenta na realnym zadaniu, jak analiza portfela akcji, świetnie pokazuje możliwości Grok 4.6. Dzięki wyszukiwaniu w sieci, uruchamianiu kodu i samodzielnemu sięganiu po lokalne narzędzia, model z łatwością radzi sobie ze złożonymi prośbami.

Cache promptów i próg cenowy 200k

Tworząc agenta wieloturnowego, powinniśmy zadbać o cache’owanie rozmowy, by model nie musiał przetwarzać całej historii przy każdej interakcji. Brak cache może generować ogromne koszty.

Cache działa automatycznie, ale wpisy są trzymane per serwer i domyślnie żądania mogą trafiać na różne serwery, omijając cache. Aby zmaksymalizować trafienia do cache, podaj stabilny identyfikator rozmowy, by wszystkie żądania w rozmowie trafiły na ten sam serwer. Sposób przekazania zależy od API:

• xai-sdk (gRPC): x-grok-conv-id, przekazywany jako metadane gRPC przy inicjalizacji klienta

• OpenAI Responses API: prompt_cache_key, ustawiany w treści żądania

Poniższy fragment pokazuje, jak to zrobić:

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]

Ważna uwaga: kara finansowa staje się szczególnie dotkliwa przy długich rozmowach. Gdy całkowita długość promptu osiągnie lub przekroczy 200k tokenów, API stosuje mnożnik 2×, rozliczając całe żądanie w podwójnej stawce.

Aby zapobiec przekraczaniu progu 200k w pętlach wieloturnowych, zaleca się kompaktowanie kontekstu. Polega ono na okresowym streszczaniu starszych tur lub przesuwaniu okna kontekstu. Dzięki temu nadal korzystasz z tanich trafień cache dla kluczowych instrukcji, unikając wysokich kosztów nieustannie rosnącego okna kontekstu.

Podsumowanie

W tym tutorialu nauczyłeś się korzystać z SpaceXAI API w Pythonie, by pracować z Grok 4.6. Poznałeś podstawy wysyłania promptów tekstowych i obrazów oraz obsługi wyjścia tak, by użytkownik wiedział, nad czym pracuje model. 

Ucząc się, jak dostarczać modelowi narzędzia, mogliśmy połączyć to wszystko i zbudować agenta AI zdolnego użyć Grok 4.6 do rozwiązywania realnych zadań, jak analiza portfela akcji. Na koniec dowiedzieliśmy się, że zadania z długim kontekstem mogą być bardzo kosztowne, zwłaszcza bez użycia cache.

Jako ćwiczenie tego, czego się nauczyłeś, zaimplementuj cache u agenta i zaktualizuj wyjście tak, by wyświetlało też tokeny rozumowania. 

Jeśli chcesz pogłębić wiedzę o budowaniu agentów AI z użyciem API, polecamy nasz kurs Working with the OpenAI API. Najlepszym miejscem na zgłębienie agentów AI jest ścieżka AI Agent Fundamentals.