Grok 4.6 API: от первого запроса до агента с инструментами

Как настроить Grok 4.6 API в Python?

Для начала вам понадобится ключ API SpaceXAI и установка xai-sdk.

Получение ключа API на console.x.ai

Чтобы создать ключ API Grok 4.6, перейдите на страницу создания ключа API в консоли SpaceX AI. Затем нажмите кнопку Create API Key в правом верхнем углу.

Форма создания ключа проста. Дайте ключу имя, чтобы понимать, к какому проекту он относится. Я также рекомендую всегда задавать срок действия ключа как защитную меру на случай компрометации.

После генерации ключа скопируйте его и вставьте в файл .env, который создайте в той же папке, где будете писать Python‑скрипты. Так ключ легко загружать в скрипт, не храня его прямо в коде, что помогло бы случайно не раскрыть ключ при обмене или загрузке кода в облако.

Файл .env должен содержать следующее:

XAI_API_KEY=replace_with_the_api_key

Установка xai-sdk и загрузка ключа SpaceXAI API

Чтобы подключиться к SpaceXAI с ключом API, используем пакет xai-sdk. Хорошая практика — создавать отдельную среду для каждого проекта, чтобы пакеты Python не конфликтовали с зависимостями других проектов. Для этого воспользуемся Anaconda со следующей командой:

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

После активации можно установить нужные пакеты. Пока начнём с:

• xai-sdk: официальный пакет SpaceXAI для запросов к их API.

• python-dotenv: утилита для удобной загрузки ключа API из файла .env.

Установим их командой:

pip install xai-sdk python-dotenv

Вот как загрузить ключ API и создать клиент SpaceXAI в Python:

from dotenv import load_dotenv
from xai_sdk import Client

load_dotenv()

client = Client()

Обратите внимание, этот код пока не делает запрос. Как это делать — дальше.

Покупка кредитов SpaceXAI API

Чтобы пользоваться Grok 4.6 API, нужно купить кредиты на их платформе API. Без этого запросы будут отклоняться. Перейдите в раздел Credits внизу боковой панели, нажмите Add credits и пополните на желаемую сумму.

Сколько стоит Grok 4.6 через API?

Запросы к Grok 4.6 тарифицируются по токенам. Базовые цены — $2 за миллион входных токенов и $6 за миллион выходных токенов.

Важно учитывать, что Grok 4.6 — модель рассуждений. Рассуждение ведётся как внутренний само‑диалог и тоже потребляет токены, которые тарифицируются как выходные. Позже мы узнаем, как управлять объёмом рассуждений для конкретного запроса.

Кэшированные токены значительно дешевле — всего $0.5 за миллион.

Как мы увидим, у Grok есть три встроенных инструмента, которые тарифицируются отдельно от токенов: поиск в вебе, поиск в X и выполнение кода. Все они стоят $5.00 за 1 000 вызовов.

Для длинных контекстов важно помнить: все токены в промптах, превышающих порог 200K, тарифицируются по двойной ставке.

Как сделать первый вызов Grok 4.6 API?

Продолжим предыдущий код и используем клиент SpaceXAI, чтобы отправить запрос к Grok 4.6.

Чтобы отправить запрос к Grok 4.6, инициализируем чат‑сессию для grok-4.6 через client.chat.create() и добавим наш промпт в историю диалога с помощью chat.append(user()).

Наконец, вызов chat.sample() отправляет диалог в модель для генерации ответа, который мы выводим через 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)

При таком использовании Grok возвращает ответ целиком: придётся дождаться завершения генерации всего текста. Получить ответ по словам можно с помощью стриминга. 

Стриминг ответа

Вместо ожидания полного ответа через chat.sample() можно использовать chat.stream(), чтобы получать вывод модели в реальном времени.

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

Этот код итерируется по потоку, выдающему инкрементальные объекты‑чанки, и печатает каждую новую часть текста (chunk.content) по мере поступления, создавая отзывчивый опыт потоковой передачи токен за токеном.

Запуская этот код, мы заметим, что модели всё равно требуется время, чтобы начать вывод токенов. Причина в том, что Grok 4.6 — модель рассуждений. По умолчанию перед тем, как выдать первое видимое слово финального ответа, модель проходит внутреннюю фазу рассуждений «chain-of-thought».

Мы можем обновить код выше, чтобы также показывать процесс рассуждения модели, вот так:

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

Поток Grok 4.6 в этом случае возвращает два типа токенов:

• Внутренние токены цепочки рассуждений модели
• Финальный ответ

Скрипт различает их, сначала проверяя chunk.reasoning_content, чтобы стримить пошаговое мышление Grok, а затем печатает chunk.content, когда начинается финальный ответ.

Как задать уровень рассуждений в Grok 4.6?

Как мы видели выше, как и другие передовые модели ИИ, Grok 4.6 опирается на скрытую цепочку рассуждений. Прежде чем выдать хотя бы одно слово финального ответа, модель генерирует тысячи токенов рассуждений, чтобы исследовать решения, перепроверить логику и исправить собственные ошибки.

Параметр reasoning_effort позволяет управлять тем, сколько усилий модель тратит на этот процесс. Поскольку мы оплачиваем и токены рассуждений, а не только финальный ответ, это важный параметр для контроля затрат.

Grok 3 mini уже позволяла настраивать reasoning_effort, но Grok 4 эту возможность убрала: рассуждения были всегда включены и не настраивались. SpaceXAI вернула контроль в линейке Grok 4.x (4.3 и 4.5), и Grok 4.6 тоже его поддерживает — уровни low, medium, high (по умолчанию) и xhigh.

Чтобы задать уровень рассуждений, используем параметр reasoning_effort при инициализации чата через client.chat.create(). Значение — строка с нужным уровнем. По умолчанию — "high". Пример установки на "low":

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

Сравнение low и high на одном промпте

Я пробовал множество задач с уровнями low и high: от создания маленькой игры и скрипта для анализа зарплат с множеством плохо отформатированных валют до логических головоломок.

Во всех случаях модель смогла дать схожие решения и при низком, и при высоком уровне рассуждений.

Чтобы проявилась разница, нужна задача, где остановка посреди рассуждений приводит к провалу. Поэтому я взял головоломку с множеством решений. Вот использованный промпт:

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.

На обоих уровнях рассуждений Grok 4.6 находил корректные решения. Однако при low бюджет рассуждений закончился до завершения задачи, поэтому ответ оказался неполным. При высоком уровне Grok 4.6 нашёл все 264 решения.

Для сравнения: при low было израсходовано 16 422 токена рассуждений, при high — 56 455.

Когда xhigh оправдан при дополнительных токенах?

Если настройка high способна «в лоб» решать сложные логические задачи и парсинг данных, зачем кому-то платить за огромный расход токенов у xhigh?

Считаю, что для 99% повседневных задач программирования и Data Science xhigh — избыточен и только ускорит расход бюджета API.

Однако xhigh становится незаменим, когда вы просите модель работать не как помощник по коду, а как автономный агент. По сути, вы платите за то, чтобы модель агрессивно проверяла свою работу, заходила в тупики и переписывала логику до того, как покажет финальный вывод.

Мой совет — начинать с low и повышать уровень только если модель систематически не справляется. Да, иногда это значит, что мы заплатим несколько раз за одну проблему, но чаще всего удаётся получить хорошее решение за малую долю стоимости.

Как отправлять изображения в Grok 4.6 API?

Grok 4.6 — мультимодальная модель и умеет работать с изображениями. 

Отправка изображения по URL

Проще всего передать изображение через URL. Его можно указать вторым аргументом в сообщении пользователя:

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

Отправка изображения через загрузку файла

Часто удобнее использовать локальные изображения, а не URL. Это можно сделать, закодировав изображение в base64. Функция encode_image() сделает это за нас:

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

После кодирования изображения передаём его модели тем же способом:

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

Несмотря на поддержку изображений на входе, Grok 4.6 выдаёт только текст. Если хотите узнать больше о генерации изображений SpaceXAI, рекомендую наш туториал по Grok Imagine API.

Как включить инструменты у агентов Grok 4.6?

Grok 4.6 предоставляет доступ к трём полезным серверным инструментам и позволяет создавать собственные.

Вызов серверных инструментов (поиск в вебе, поиск в X, выполнение кода)

В комплекте с Grok 4.6 идут три серверных инструмента:

• Web search: позволяет агенту делать веб‑поиск для обоснования ответа.
• X search: запрашивает данные платформы X в реальном времени.
• Code execution: выполняет код в песочнице, чтобы помочь с ответом.

Эти инструменты работают на серверах SpaceXAI, и каждый вызов тарифицируется отдельно от токенов.

Чтобы их включить, импортируйте и передайте при создании чата через 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()],
)

При потоковой передаче ответа можно понять, использует ли агент инструмент, проверяя флаг chunk.tool_calls.

Ниже — пример обработки стрима так, чтобы показывать пользователю, когда агент использует инструмент:

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)

Полный пример скрипта с серверными инструментами — в сопроводительном репозитории на GitHub.

Реализация собственных локальных инструментов

Помимо серверных, мы можем оснастить агента Grok 4.6 кастомными инструментами. Посмотрим, как реализовать инструменты для чтения и записи локальных файлов.

Чтобы реализовать собственный инструмент, нужны две вещи:

1. Спецификация инструмента с использованием официального объекта tool() из SpaceXAI SDK.

2. Python‑реализация инструмента — код, который нужно выполнить при вызове инструмента.

Спецификация инструмента включает:

• Имя Python‑функции для вызова.
• Описание, объясняющее, что делает инструмент. Это критично, так как определяет, когда агент его вызовет.
• Спецификацию параметров функции.

Ниже — функция для инструмента чтения локальных файлов:

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

Из соображений безопасности инструмент всегда запрашивает разрешение пользователя перед чтением файла. Это предотвращает случайную передачу приватных данных агенту.

Вот спецификация инструмента для этой функции:

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

Код для записи в файл аналогичен и доступен в файле tools.py из репозитория.

Как запустить агентный цикл с инструментами в Grok 4.6?

В этом разделе объединим всё, что узнали, и построим агентный цикл Grok 4.6, где мы общаемся с агентом, способным выполнять реальную работу с локальными файлами и обосновывать ответы данными из онлайна через поиск.

Агент работает, как на схеме ниже. Пользователь отправляет запрос, агент отвечает, при необходимости используя инструменты. Затем ответ возвращается пользователю, и пользователь может продолжить взаимодействие с агентом. 

Агент ведёт всю историю разговора, используя chat.append() для добавления пользовательских промптов, ответов и результатов инструментов. Результат инструмента должен быть обёрнут в экземпляр tool_result().

Полная реализация агента:

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

Тестирование агента Grok 4.6 на анализе фондового портфеля

Для теста я создал пример CSV с портфелем акций. Файл простой: перечисляет бумаги, в частности дату покупки и цену входа. 

Задумка — попросить агента:

1. Загрузить CSV.
2. Сделать веб‑поиск, чтобы получить текущие цены по каждой акции.
3. Обновить CSV, добавив новый столбец с текущими ценами.
4. Попросить агента составить отчёт по портфелю с последними новостями по нашим секторам.

Ниже — скриншот взаимодействия с агентом для шагов 1–3.

Видно, что он использовал веб‑поиск, выполнение кода и созданные нами инструменты для чтения и записи локальных файлов. В итоге он обновил CSV, добавив столбец с текущими ценами.

Так как агент работает в цикле, мы можем продолжать диалог. В следующем запросе я попросил найти новости по этим акциям, проанализировать диверсификацию портфеля и создать отчёт в Markdown.

Если интересно, какой отчёт получился, он есть в репозитории на GitHub.

Тест на реальной задаче, как анализ портфеля акций, хорошо показывает возможности Grok 4.6. Используя веб‑поиск, выполнение кода и локальные инструменты, модель уверенно справляется со сложными запросами.

Кэширование промптов и ценовой обрыв на 200k

Реализуя многошагового агента, стоит убедиться, что разговор кэшируется, чтобы модель не перерабатывала всю историю при каждом шаге. Иначе стоимость может резко вырасти.

Кэширование включено автоматически, но записи кэша хранятся по серверам, и по умолчанию запросы могут маршрутизироваться на разные сервера и промахиваться по кэшу. Чтобы максимизировать попадания, задайте стабильный идентификатор диалога, чтобы все запросы этой беседы приходили на один и тот же сервер. Как его передавать — зависит от API:

• xai-sdk (gRPC): x-grok-conv-id, передаётся как метаданные gRPC при инициализации клиента

• OpenAI Responses API: prompt_cache_key, указывается в теле запроса

Пример ниже показывает, как это сделать:

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]

Важно учитывать, что финансовые потери особенно велики при длинных беседах. Как только общий размер промпта достигает или превышает 200k токенов, API применяет множитель 2× и тарифицирует весь запрос по двойной ставке.

Чтобы не переходить порог 200k в многошаговых циклах, настоятельно рекомендуется сжимать контекст: периодически суммировать старые реплики или скользить окном контекста. Это позволит продолжать получать дешёвые попадания в кэш по базовым инструкциям и избегать серьёзных переплат из‑за бесконечно растущего окна контекста.

Итоги

В этом туториале мы научились использовать SpaceXAI API в Python для взаимодействия с Grok 4.6. Разобрали основы отправки текстовых и графических промптов и обработку вывода так, чтобы пользователь видел, над чем работает модель. 

Освоив подключение инструментов к модели ИИ, мы объединили всё и построили ИИ‑агента, способного с помощью Grok 4.6 решать прикладные задачи, например анализировать портфель на фондовом рынке. Наконец, мы узнали, что задачи с длинным контекстом могут быть крайне дорогими, особенно без кэширования.

В качестве упражнения попробуйте реализовать кэширование в агенте и дополнительно отображать токены рассуждений. 

Если вы хотите углубить знания по созданию AI‑агентов через API, рекомендуем наш курс Working with the OpenAI API. Лучшее место для глубокого погружения в AI‑агентов — трек AI Agent Fundamentals.