Grok

Обновление образов

Готовые образы агентов обновляются каждое утро и содержат актуальную версию CLI. Чтобы использовать фиксированную версию образа, закрепите версию шаблона.

Grok Build — агент xAI для работы с файлами, командами и внешними инструментами. Готовый шаблон grok содержит официальный CLI. Приложение запускает его через API команд AgentBox и получает ответ или файл результата.

Подключение

Установите SDK AgentBox и задайте AGENTBOX_API_KEY.

Ключ xAI берётся из XAI_API_KEY и передаётся только процессу агента. В примерах выбрана модель grok-4.3. Доступные модели можно посмотреть командой grok models внутри песочницы с переданным ключом.

Для доступа к модели можно использовать HTTPS-прокси AgentBox https://sandbox-proxy.agentbox.ru:65181.

В примерах HTTPS_PROXY, HTTP_PROXY и NO_PROXY передаются процессу агента. Эти настройки могут влиять и на другие запросы агента и его дочерних процессов. Соединения с localhost и 127.0.0.1 остаются прямыми.

Подготовьте сводку по доставкам

Пример передаёт выгрузку доставок и просит Grok записать задержанные заказы с известными причинами в exceptions.md. Затем приложение читает файл через SDK.

mjs

import { Sandbox } from "@abox-dev/sdk";

const apiKey = process.env.XAI_API_KEY;
if (!apiKey) throw new Error("XAI_API_KEY is required");
const proxy =
  process.env.SANDBOX_PROXY_URL ?? "https://sandbox-proxy.agentbox.ru:65181";
const sandbox = await Sandbox.create("grok", { timeoutMs: 600_000 });
try {
  await sandbox.files.makeDir("/home/user/work");
  await sandbox.files.write(
    "/home/user/work/shipments.csv",
    `order,customer,status,note
1042,Acme,delayed,Awaiting warehouse pickup
1043,Northwind,delivered,Delivered on September 18
1044,Contoso,delayed,Address confirmation required
`,
  );
  await sandbox.files.write(
    "/home/user/work/task.txt",
    "Read shipments.csv and write exceptions.md for the logistics team: delayed orders and their known reasons.",
  );
  const result = await sandbox.commands.run(
    "grok --always-approve --sandbox off --model grok-4.3 --prompt-file task.txt",
    {
      cwd: "/home/user/work",
      timeoutMs: 300_000,
      envs: {
        XAI_API_KEY: apiKey,
        HTTPS_PROXY: proxy,
        HTTP_PROXY: proxy,
        NO_PROXY: "localhost,127.0.0.1",
      },
      onStderr: (chunk) => process.stderr.write(chunk),
    },
  );
  console.log(result.stdout);
  console.log(
    "exceptions.md\n" +
      (await sandbox.files.read("/home/user/work/exceptions.md")),
  );
} finally {
  await sandbox.kill();
}

import os
import sys
from agentbox import Sandbox

api_key = os.environ["XAI_API_KEY"]
proxy = os.getenv("SANDBOX_PROXY_URL", "https://sandbox-proxy.agentbox.ru:65181")
sandbox = Sandbox.create("grok", timeout=600)
try:
    sandbox.files.make_dir("/home/user/work")
    sandbox.files.write(
        "/home/user/work/shipments.csv",
        """order,customer,status,note
1042,Acme,delayed,Awaiting warehouse pickup
1043,Northwind,delivered,Delivered on September 18
1044,Contoso,delayed,Address confirmation required
""",
    )
    sandbox.files.write(
        "/home/user/work/task.txt",
        "Read shipments.csv and write exceptions.md for the logistics team: delayed orders and their known reasons.",
    )
    result = sandbox.commands.run(
        "grok --always-approve --sandbox off --model grok-4.3 --prompt-file task.txt",
        cwd="/home/user/work",
        timeout=300,
        envs={
            "XAI_API_KEY": api_key,
            "HTTPS_PROXY": proxy,
            "HTTP_PROXY": proxy,
            "NO_PROXY": "localhost,127.0.0.1",
        },
        on_stderr=lambda chunk: print(chunk, end="", file=sys.stderr),
    )
    print(result.stdout)
    print("exceptions.md\n" + sandbox.files.read("/home/user/work/exceptions.md"))
finally:
    sandbox.kill()

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/abox-dev/sdk/packages/go-sdk"
)

func run() (err error) {
	apiKey := os.Getenv("XAI_API_KEY")
	if apiKey == "" {
		return errors.New("XAI_API_KEY is required")
	}
	proxy := os.Getenv("SANDBOX_PROXY_URL")
	if proxy == "" {
		proxy = "https://sandbox-proxy.agentbox.ru:65181"
	}
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
	defer cancel()
	client, err := agentbox.NewClient()
	if err != nil {
		return err
	}
	sandbox, err := client.Sandboxes.Create(ctx, &agentbox.CreateSandboxOptions{Template: "grok", Timeout: 10 * time.Minute})
	if err != nil {
		return err
	}
	defer func() {
		cleanupCtx, stop := context.WithTimeout(context.Background(), 30*time.Second)
		defer stop()
		_, cleanupErr := sandbox.Kill(cleanupCtx)
		err = errors.Join(err, cleanupErr)
	}()
	if _, err := sandbox.Files.MakeDir(ctx, "/home/user/work"); err != nil {
		return err
	}
	if _, err := sandbox.Files.WriteText(ctx, "/home/user/work/shipments.csv", `order,customer,status,note
1042,Acme,delayed,Awaiting warehouse pickup
1043,Northwind,delivered,Delivered on September 18
1044,Contoso,delayed,Address confirmation required
`, nil); err != nil {
		return err
	}
	if _, err := sandbox.Files.WriteText(ctx, "/home/user/work/task.txt", "Read shipments.csv and write exceptions.md for the logistics team: delayed orders and their known reasons.", nil); err != nil {
		return err
	}
	result, err := sandbox.Commands.Run(ctx, "sh", &agentbox.CommandOptions{
		Args: []string{"-lc", "grok --always-approve --sandbox off --model grok-4.3 --prompt-file task.txt"},
		Cwd:  "/home/user/work",
		Env: map[string]string{
			"XAI_API_KEY": apiKey,
			"HTTPS_PROXY": proxy,
			"HTTP_PROXY":  proxy,
			"NO_PROXY":    "localhost,127.0.0.1",
		},
		OnStderr: func(chunk []byte) { fmt.Fprint(os.Stderr, string(chunk)) },
	})
	if err != nil {
		return err
	}
	fmt.Println(string(result.Stdout))
	report, err := sandbox.Files.ReadText(ctx, "/home/user/work/exceptions.md", "")
	if err != nil {
		return err
	}
	fmt.Println("exceptions.md\n" + report)
	return nil
}

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

--prompt-file task.txt задаёт один вызов без интерактивного интерфейса. --always-approve разрешает выполнение инструментов без подтверждений. --sandbox off отключает дополнительную изоляцию самого Grok. Границы окружения обеспечивает песочница AgentBox.

Пример читает результат до удаления песочницы. finally освобождает её и при ошибке. В Go для очистки используется отдельный контекст.

События и продолжение сессии

С --output-format streaming-json Grok выдаёт JSON-объекты, разделённые переводами строк. Пример выводит текст ответа и названия инструментов, ждёт завершения и продолжает ту же сессию с уточнённым статусом доставки.

mjs

import { Sandbox } from "@abox-dev/sdk";

const apiKey = process.env.XAI_API_KEY;
if (!apiKey) throw new Error("XAI_API_KEY is required");
const proxy =
  process.env.SANDBOX_PROXY_URL ?? "https://sandbox-proxy.agentbox.ru:65181";
const sandbox = await Sandbox.create("grok", { timeoutMs: 600_000 });
try {
  await sandbox.files.makeDir("/home/user/work");
  await sandbox.files.write(
    "/home/user/work/shipments.csv",
    `order,customer,status,note
1042,Acme,delayed,Awaiting warehouse pickup
1043,Northwind,delivered,Delivered on September 18
1044,Contoso,delayed,Address confirmation required
`,
  );
  async function execute(prompt, sessionId) {
    await sandbox.files.write("/home/user/work/task.txt", prompt);
    let pending = "",
      nextSessionId,
      terminal,
      failure;
    function event(message) {
      if (message.type === "text") process.stdout.write(message.data);
      if (message.type === "tool_call") console.log("Tool:", message.title);
      if (message.type === "end") {
        terminal = message.stopReason;
        nextSessionId = message.sessionId;
      }
      if (message.type === "error") failure = new Error(message.message);
    }
    function onStdout(chunk) {
      pending += chunk;
      let newline;
      while ((newline = pending.indexOf("\n")) !== -1) {
        const line = pending.slice(0, newline);
        pending = pending.slice(newline + 1);
        if (line.trim()) event(JSON.parse(line));
      }
    }
    await sandbox.commands.run(
      "grok --always-approve --sandbox off --model grok-4.3 --prompt-file task.txt --output-format streaming-json" +
        (sessionId ? ' --resume "$AGENT_SESSION_ID"' : ""),
      {
        cwd: "/home/user/work",
        timeoutMs: 300_000,
        envs: {
          XAI_API_KEY: apiKey,
          HTTPS_PROXY: proxy,
          HTTP_PROXY: proxy,
          NO_PROXY: "localhost,127.0.0.1",
          AGENT_SESSION_ID: sessionId ?? "",
        },
        onStdout,
        onStderr: (chunk) => process.stderr.write(chunk),
      },
    );
    if (pending.trim()) event(JSON.parse(pending));
    if (failure) throw failure;
    if (terminal !== "end_turn")
      throw new Error("Agent did not finish normally: " + terminal);
    if (!nextSessionId) throw new Error("Agent did not return a session ID");
    console.log("\nSession:", nextSessionId);
    return nextSessionId;
  }
  const sessionId = await execute(
    "Read shipments.csv and write exceptions.md for the logistics team: delayed orders and their known reasons.",
  );
  await execute(
    "The warehouse confirmed that order 1042 was picked up. Update exceptions.md and keep the other order details.",
    sessionId,
  );
  console.log(
    "exceptions.md\n" +
      (await sandbox.files.read("/home/user/work/exceptions.md")),
  );
} finally {
  await sandbox.kill();
}

import json
import os
import sys
from agentbox import Sandbox

api_key = os.environ["XAI_API_KEY"]
proxy = os.getenv("SANDBOX_PROXY_URL", "https://sandbox-proxy.agentbox.ru:65181")
sandbox = Sandbox.create("grok", timeout=600)
try:
    sandbox.files.make_dir("/home/user/work")
    sandbox.files.write(
        "/home/user/work/shipments.csv",
        """order,customer,status,note
1042,Acme,delayed,Awaiting warehouse pickup
1043,Northwind,delivered,Delivered on September 18
1044,Contoso,delayed,Address confirmation required
""",
    )

    def execute(prompt, session_id=None):
        sandbox.files.write("/home/user/work/task.txt", prompt)
        pending = ""
        next_session_id = None
        terminal = None
        failure = None

        def event(message):
            nonlocal next_session_id, terminal, failure
            if message.get("type") == "text":
                print(message["data"], end="", flush=True)
            if message.get("type") == "tool_call":
                print("Tool:", message["title"])
            if message.get("type") == "end":
                terminal = message.get("stopReason")
                next_session_id = message.get("sessionId")
            if message.get("type") == "error":
                failure = message.get("message") or str(message)

        def on_stdout(chunk):
            nonlocal pending
            pending += chunk
            while "\n" in pending:
                line, pending = pending.split("\n", 1)
                if line.strip():
                    event(json.loads(line))

        sandbox.commands.run(
            "grok --always-approve --sandbox off --model grok-4.3 --prompt-file task.txt --output-format streaming-json"
            + (' --resume "$AGENT_SESSION_ID"' if session_id else ""),
            cwd="/home/user/work",
            timeout=300,
            envs={
                "XAI_API_KEY": api_key,
                "HTTPS_PROXY": proxy,
                "HTTP_PROXY": proxy,
                "NO_PROXY": "localhost,127.0.0.1",
                "AGENT_SESSION_ID": session_id or "",
            },
            on_stdout=on_stdout,
            on_stderr=lambda chunk: print(chunk, end="", file=sys.stderr),
        )
        if pending.strip():
            event(json.loads(pending))
        if failure:
            raise RuntimeError(failure)
        if terminal != "end_turn":
            raise RuntimeError(f"Agent did not finish normally: {terminal}")
        if not next_session_id:
            raise RuntimeError("Agent did not return a session ID")
        print("\nSession:", next_session_id)
        return next_session_id

    session_id = execute(
        "Read shipments.csv and write exceptions.md for the logistics team: delayed orders and their known reasons."
    )
    execute(
        "The warehouse confirmed that order 1042 was picked up. Update exceptions.md and keep the other order details.",
        session_id,
    )
    print("exceptions.md\n" + sandbox.files.read("/home/user/work/exceptions.md"))
finally:
    sandbox.kill()

package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"log"
	"os"
	"strings"
	"time"

	"github.com/abox-dev/sdk/packages/go-sdk"
)

func run() (err error) {
	apiKey := os.Getenv("XAI_API_KEY")
	if apiKey == "" {
		return errors.New("XAI_API_KEY is required")
	}
	proxy := os.Getenv("SANDBOX_PROXY_URL")
	if proxy == "" {
		proxy = "https://sandbox-proxy.agentbox.ru:65181"
	}
	ctx, cancel := context.WithTimeout(context.Background(), 8*time.Minute)
	defer cancel()
	client, err := agentbox.NewClient()
	if err != nil {
		return err
	}
	sandbox, err := client.Sandboxes.Create(ctx, &agentbox.CreateSandboxOptions{Template: "grok", Timeout: 10 * time.Minute})
	if err != nil {
		return err
	}
	defer func() {
		cleanupCtx, stop := context.WithTimeout(context.Background(), 30*time.Second)
		defer stop()
		_, cleanupErr := sandbox.Kill(cleanupCtx)
		err = errors.Join(err, cleanupErr)
	}()
	if _, err := sandbox.Files.MakeDir(ctx, "/home/user/work"); err != nil {
		return err
	}
	if _, err := sandbox.Files.WriteText(ctx, "/home/user/work/shipments.csv", `order,customer,status,note
1042,Acme,delayed,Awaiting warehouse pickup
1043,Northwind,delivered,Delivered on September 18
1044,Contoso,delayed,Address confirmation required
`, nil); err != nil {
		return err
	}
	execute := func(prompt, sessionID string) (string, error) {
		if _, err := sandbox.Files.WriteText(ctx, "/home/user/work/task.txt", prompt, nil); err != nil {
			return "", err
		}
		var pending, nextSessionID string
		var streamErr error
		var terminal string
		event := func(line string) {
			if strings.TrimSpace(line) == "" || streamErr != nil {
				return
			}
			var message struct {
				Type       string          `json:"type"`
				Data       json.RawMessage `json:"data"`
				Title      string          `json:"title"`
				StopReason string          `json:"stopReason"`
				SessionID  string          `json:"sessionId"`
				Message    string          `json:"message"`
			}
			if err := json.Unmarshal([]byte(line), &message); err != nil {
				streamErr = err
				return
			}
			switch message.Type {
			case "text":
				var text string
				if err := json.Unmarshal(message.Data, &text); err != nil {
					streamErr = err
					return
				}
				fmt.Print(text)
			case "tool_call":
				fmt.Println("Tool:", message.Title)
			case "end":
				terminal = message.StopReason
				nextSessionID = message.SessionID
			case "error":
				streamErr = errors.New(message.Message)
			}
		}
		command := "grok --always-approve --sandbox off --model grok-4.3 --prompt-file task.txt --output-format streaming-json"
		if sessionID != "" {
			command += " --resume \"$AGENT_SESSION_ID\""
		}
		commandCtx, stop := context.WithTimeout(ctx, 5*time.Minute)
		defer stop()
		_, err := sandbox.Commands.Run(commandCtx, "sh", &agentbox.CommandOptions{
			Args: []string{"-lc", command},
			Cwd:  "/home/user/work",
			Env: map[string]string{
				"XAI_API_KEY":      apiKey,
				"HTTPS_PROXY":      proxy,
				"HTTP_PROXY":       proxy,
				"NO_PROXY":         "localhost,127.0.0.1",
				"AGENT_SESSION_ID": sessionID,
			},
			OnStdout: func(chunk []byte) {
				pending += string(chunk)
				for {
					line, rest, found := strings.Cut(pending, "\n")
					if !found {
						break
					}
					pending = rest
					event(line)
				}
			},
			OnStderr: func(chunk []byte) { fmt.Fprint(os.Stderr, string(chunk)) },
		})
		if err != nil {
			return "", err
		}
		event(pending)
		if streamErr != nil {
			return "", streamErr
		}
		if terminal != "end_turn" {
			return "", fmt.Errorf("agent did not finish normally: %s", terminal)
		}
		if nextSessionID == "" {
			return "", errors.New("agent did not return a session ID")
		}
		fmt.Println("\nSession:", nextSessionID)
		return nextSessionID, nil
	}
	sessionID, err := execute("Read shipments.csv and write exceptions.md for the logistics team: delayed orders and their known reasons.", "")
	if err != nil {
		return err
	}
	if _, err := execute("The warehouse confirmed that order 1042 was picked up. Update exceptions.md and keep the other order details.", sessionID); err != nil {
		return err
	}
	report, err := sandbox.Files.ReadText(ctx, "/home/user/work/exceptions.md", "")
	if err != nil {
		return err
	}
	fmt.Println("exceptions.md\n" + report)
	return nil
}

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

В событии text поле data содержит фрагмент ответа. tool_call сообщает о вызове инструмента. Событие end содержит sessionId и причину остановки stopReason. Пример принимает end_turn как нормальное завершение и передаёт полученный ID в --resume. --session-id предназначен для новой сессии с заданным UUID, а не для продолжения существующей.

История сессии и файлы находятся в песочнице. Для следующего вызова сохраните её вместе с ID сессии или поставьте на паузу. Полный протокол и параметры CLI описаны в справочнике Grok Build.

Grok ​

Подключение ​

Подготовьте сводку по доставкам ​

События и продолжение сессии ​

Grok

Подключение

Подготовьте сводку по доставкам

События и продолжение сессии