Выполнение кода и песочница
Когда ассистент выполняет 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
Разовое выполнение команды в песочнице. Возвращает захваченные потоки и файлы, записанные в воркспейс.
| Field | Type | Description |
|---|---|---|
| commandrequired | string | Shell-команда для выполнения. |
| description | string | Короткая метка того, что делает команда, напр. 'Установка зависимостей'. |
| timeout_seconds | int (1–3600) | Таймаут команды. По умолчанию 60с; повышайте для долгих установок, сборок, экспортов. |
| cwd | string | Рабочая директория (напр. /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.
| Field | Type | Description |
|---|---|---|
| commandrequired | string | Команда для запуска в PTY. |
| rows | int (1–1000) | Строки PTY. По умолчанию 24. |
| cols | int (1–1000) | Колонки PTY. По умолчанию 80. |
| grace_seconds | float | Сколько ждать завершения быстрой команды до возврата живого session_id. |
Возвращает session_id, pid, stdout, cursor, status, exit_code, alive — cursor позволяет следующему чтению продолжить ровно с того места, где остановилось прошлое.
write_stdin — управление живой сессией
Отправляет символы в stdin ещё работающей сессии exec_command и читает свежий вывод. Добавьте \n, чтобы отправить строку.
| Field | Type | Description |
|---|---|---|
| session_idrequired | string | Session id из прошлого exec_command, который ещё жив. |
| inputrequired | string | Символы в stdin. Добавьте \n, чтобы отправить строку. |
| since | int | Курсор из прошлого чтения; вернёт только вывод, появившийся после него. |
| wait_seconds | float | Сколько ждать нового вывода до возврата. |
edit_file — точечные правки файлов
Search-and-replace правки файлов в песочнице с фолбэком на нечёткое сопоставление, когда целевой текст слегка изменился.
bsl_check — статический анализ 1С (BSL)
Запускает bsl-language-server по коду 1С. Укажите .bsl / .os файл или папку выгрузки конфигурации; возвращает диагностику.
Полный список инструментов
Эта страница покрывает инструменты выполнения кода. Полный каталог по всем категориям (поиск, память, коннекторы, медиа, …) — на странице Агенты → Доступные инструменты.