# Выполнение кода и песочница

Когда ассистент выполняет shell-команду, ячейку Python или сборку — это происходит внутри управляемой песочницы, а не на хосте, который обслуживает API. Эта страница описывает, **где** идёт выполнение (бэкенды), **насколько оно изолировано** и **какие инструменты** использует агент — с параметрами и форматом ответа.

**Бэкенд выбирает платформа**
Бэкенд исполнения выбирается платформой при развёртывании, а не в запросе к API. Вы пишете одни и те же вызовы инструментов независимо от бэкенда; уровень изоляции — это операционная гарантия, а не параметр.

## Бэкенды исполнения

Активный бэкенд задаётся настройкой `SANDBOX_BACKEND` (список фолбэков через запятую; первый элемент — основной). Все бэкенды предоставляют одинаковый набор инструментов — различаются только изоляция и персистентность.

| Бэкенд | Что это | Изоляция | Когда |
| --- | --- | --- | --- |
| `e2b` | Управляемая облачная песочница (по умолчанию) | Полная VM-изоляция, ФС на сессию | По умолчанию для облачных запусков |
| `firecracker` | microVM Firecracker | Аппаратная виртуализация, UFFD-память, пул сети | Максимальная изоляция, быстрый старт |
| `superserve` | Рантайм managed agents-SDK | Контейнер провайдера | Управляемое масштабирование |
| `blaxel` | Рантайм managed agents-SDK | Контейнер провайдера | Управляемое масштабирование |
| `local` | Этот хост | Bind-jail воркспейса + git staging jail | Доверенный self-host / разработка |

## Изоляция и контейнмент

Контейнерные и microVM-бэкенды работают под профилем контейнмента, а не как голый shell:

- **Файловая тюрьма** — доступ к файлам ограничен воркспейсом сессии; выход за пределы корня отклоняется до любого I/O.
- **Egress-прокси** — исходящая сеть идёт через контролируемый egress, а не через сырую сеть хоста.
- **ФС на сессию** — у каждой сессии свой воркспейс; установленные пакеты и смена `cwd` сохраняются между вызовами в рамках сессии.
- **Уровень microVM** — на `firecracker` нагрузка идёт в аппаратно-виртуализированной microVM с собственным ядром, изолированной от хоста и других сессий.

**local — это не песочница**
`SANDBOX_BACKEND=local` работает на хосте только с bind-jail воркспейса и git staging jail. Используйте для доверенного self-host или разработки — никогда для недоверенного ввода.

## Инструменты

### `sandbox_bash` — shell / Python

Разовое выполнение команды в песочнице. Возвращает захваченные потоки и файлы, записанные в воркспейс.

<ParamTable
    rows={[
        { name: "command", type: "string", required: true, description: "Shell-команда для выполнения." },
        { name: "description", type: "string", description: "Короткая метка того, что делает команда, напр. 'Установка зависимостей'." },
        { name: "timeout_seconds", type: "int (1–3600)", description: "Таймаут команды. По умолчанию 60с; повышайте для долгих установок, сборок, экспортов." },
        { name: "cwd", type: "string", description: "Рабочая директория (напр. /workspace). По умолчанию: домашняя в песочнице." },
    ]}
/>

Возвращает:

| Поле | Значение |
| --- | --- |
| `stdout` / `stderr` | Захваченные потоки вывода. |
| `exit_code` | Код выхода процесса. |
| `truncated` | `true`, если вывод обрезан по лимиту размера. |
| `files` / `file_count` | Файлы, созданные командой в воркспейсе. |
| `local_paths` | Карта файлов воркспейса в извлекаемые пути. |

### `repl_execute` — постоянный Python REPL

Jupyter-подобная сессия Python, сохраняющая состояние между вызовами, со встроенными хелперами (`peek`, `grep`, `chunk_indices`, `llm_query`, `FINAL`) для работы с большими данными без перезагрузки на каждом шаге.

### `exec_command` — интерактивный терминал (PTY)

Запускает команду в PTY-сессии. Завершившиеся команды сразу возвращают `stdout` + `exit_code`; долгоживущие процессы (серверы, REPL, watcher'ы) остаются живыми и возвращают `session_id`, в который вы пишете через `write_stdin`.

<ParamTable
    rows={[
        { name: "command", type: "string", required: true, description: "Команда для запуска в PTY." },
        { name: "rows", type: "int (1–1000)", description: "Строки PTY. По умолчанию 24." },
        { name: "cols", type: "int (1–1000)", description: "Колонки PTY. По умолчанию 80." },
        { name: "grace_seconds", type: "float", description: "Сколько ждать завершения быстрой команды до возврата живого session_id." },
    ]}
/>

Возвращает `session_id`, `pid`, `stdout`, `cursor`, `status`, `exit_code`, `alive` — `cursor` позволяет следующему чтению продолжить ровно с того места, где остановилось прошлое.

### `write_stdin` — управление живой сессией

Отправляет символы в stdin ещё работающей сессии `exec_command` и читает свежий вывод. Добавьте `\n`, чтобы отправить строку.

<ParamTable
    rows={[
        { name: "session_id", type: "string", required: true, description: "Session id из прошлого exec_command, который ещё жив." },
        { name: "input", type: "string", required: true, description: "Символы в stdin. Добавьте \\n, чтобы отправить строку." },
        { name: "since", type: "int", description: "Курсор из прошлого чтения; вернёт только вывод, появившийся после него." },
        { name: "wait_seconds", type: "float", description: "Сколько ждать нового вывода до возврата." },
    ]}
/>

### `edit_file` — точечные правки файлов

Search-and-replace правки файлов в песочнице с фолбэком на нечёткое сопоставление, когда целевой текст слегка изменился.

### `bsl_check` — статический анализ 1С (BSL)

Запускает `bsl-language-server` по коду 1С. Укажите `.bsl` / `.os` файл или папку выгрузки конфигурации; возвращает диагностику.

**Полный список инструментов**
Эта страница покрывает инструменты выполнения кода. Полный каталог по всем категориям (поиск, память, коннекторы, медиа, …) — на странице <a href="/docs/agents#available-tools">Агенты → Доступные инструменты</a>.