Выполнение кода и песочница
Когда агент выполняет shell-команду, ячейку Python или сборку, это происходит внутри управляемой песочницы, а не на хосте, который обслуживает API. Эта страница описывает, где идёт выполнение, насколько оно изолировано и какие инструменты использует агент, с параметрами и форматом ответа.
Это инструменты агента, а не эндпоинты API
sandbox_bash, exec_command, write_stdin, edit_file и описанный ниже repl_execute агент вызывает внутри своего хода; ваш запрос вызвать их не может, и их параметры не являются полями запроса. Вы видите их только как события инструментов потокового хода. Напрямую клиент вызывает один инструмент: repl_execute через MCP-сервер, со своими параметрами code, skills (id навыков, чьи скрипты подключаются) и timeout_seconds (ограничен потолком песочницы).
Изоляция
Среду исполнения выбирает и обслуживает платформа; в запросе к API она не задаётся. Вы пишете одни и те же вызовы инструментов, а изоляция остаётся операционной гарантией, а не параметром.
- Файловая тюрьма: доступ к файлам ограничен воркспейсом сессии; выход за пределы корня отклоняется до любого I/O.
- Сеть закрыта по умолчанию: наружу открыт только ограниченный список хостов платформы. Сторонние API с ключами вызываются через коннекторы, а не из песочницы.
- Секретов коннекторов внутри нет: секреты коннекторов (ключи API, токены, пароли) в окружение песочницы не попадают: код обращается к коннектору через хост, у которого и лежат креды. В os.environ есть только несекретные реквизиты подключения, собственные переменные пользователя и переменные, которые называет Environment.
- ФС на сессию: у каждой сессии свой воркспейс. Каждый вызов
sandbox_bashстартует в новом shell:cdи переменные окружения следующего вызова не достигают, промежуточное состояние держите в файлах.
Файлы и персистентность
| Корень | Путь в облаке по умолчанию | Назначение |
|---|---|---|
input | /tmp/input | Загрузки пользователя, только чтение |
work | /tmp/work | Черновики, сборка, промежуточные файлы |
output | /home/user/output | Результаты, которые агент отдаёт пользователю |
| домашняя папка | /home/user | cwd по умолчанию; её ничто не сохраняет и не доставляет |
work и output переживают перезапуск песочницы между ходами. Пространство имён repl_execute тоже снимается и восстанавливается; если восстановить не удалось, агент видит пометку [SYSTEM: …] или NameError. Файлы между облаком и компьютером пользователя переносят copy_from_computer и copy_to_computer (до 100 мегабайт на файл, файл адресуется artifact_id).
На компьютере analyze принимает путь из папки чата или её рабочих каталогов. Для файла за их пределами copy_from_computer проверяет разрешение на импорт конкретного файла. Агент передаёт полученный artifact_id в analyze.
Инструменты
Ход исполняется либо в облачной песочнице (sandbox_bash), либо на компьютере пользователя через десктоп-приложение (exec_command + write_stdin). Не тот shell отвечает отказом, который называет нужный. edit_file правит файлы там, где идёт ход.
sandbox_bash: shell / Python
Разовая неинтерактивная команда в облачной песочнице. Возвращает захваченные потоки и файлы из output.
| Field | Type | Description |
|---|---|---|
| commandrequired | string | Shell-команда. Каждый вызов в новом shell; `grep`, `diff`, `test` законно отвечают ненулевым кодом. |
| purposerequired | string | Одна строка для человека о том, что делает вызов. Есть у каждого инструмента, у меняющих воркспейс обязательна. |
| timeout_seconds | int (1–300) | Таймаут команды, по умолчанию 60 с. Потолок задаёт меньший из лимита песочницы и бюджета ожидания хода (300 с). Для долгих вычислений на Python используйте `repl_execute`. |
| cwd | string | Абсолютный путь или корень (`work/fetch`). По умолчанию домашняя папка. Задавайте его вместо `cd`. |
Возвращает:
| Поле | Значение |
|---|---|
stdout / stderr | Захваченные потоки вывода. |
exit_code | Код выхода процесса. |
command_success | false только если команда не запустилась (126/127) или была убита. Ненулевой exit_code сам по себе не провал. |
truncated | true, если stdout обрезан; полный вывод лежит по full_data_path конверта. |
files / file_count | Файлы, созданные командой в воркспейсе. |
local_paths | Карта файлов воркспейса в извлекаемые пути. |
repl_execute: постоянный Python REPL
Jupyter-подобная сессия Python: один процесс на разговор, пространство имён переживает вызовы, упавшая ячейка не откатывает уже выполненное. Встроенные хелперы (peek, grep, chunk_indices, llm_query, save_artifact, FINAL и др.) помогают работать с большими данными без перезагрузки на каждом шаге.
Результат вызова содержит квитанцию исполнения и захваченный вывод. Вычисленные объекты остаются в переменных Python: read_stdout(ref) читает вывод, а read_first(ref) выбирает запись квитанции. Чтобы посмотреть сохранённый объект, напечатайте его в следующей ячейке, например print(rows). Повторять вычисление не требуется.
Если ячейка не уложилась в начальное окно, она продолжает выполняться, пока ход стоит на паузе. Рантайм забирает квитанцию перед возобновлением хода. У ячейки остаётся собственный срок исполнения. По его истечении ядро сбрасывается. Переменные завершённых ячеек восстанавливаются из снимка, а изменения имён прерванной ячейки теряются. Уже выполненные записи во внешние сервисы сохраняются. Перед повтором сверяйте их состояние и сохранённый прогресс.
Синтаксическая ошибка возвращает строку и позицию для исправления; сама по себе она не завершает ход и не повышает лимит токенов. Обрезанный вызов определяет ответ провайдера: такой вызов не исполняется и повторяется с увеличенным бюджетом вывода.
| Field | Type | Description |
|---|---|---|
| coderequired | string | Код ячейки. Длинные шаги (больше 150 строк) делите на ячейки. |
| yield_seconds | float | Начальное окно наблюдения в секундах. Рантайм ограничивает его длительность. Если ячейка успевает завершиться, вызов сразу возвращает квитанцию. |
exec_command: живая shell-сессия
Запускает команду в shell-сессии на компьютере пользователя через десктоп-приложение, в папке чата, с вводом и выводом через каналы. Если команда завершилась в начальном окне, вызов сразу возвращает stdout и exit_code. Если конечная команда ещё выполняется, ход встаёт на паузу. При пробуждении рантайм проверяет ту же сессию и читает вывод с сохранённой позиции. Если связь оборвалась, исход остаётся неизвестным до успешного чтения. Для оставленных работать серверов, REPL и watcher'ов агент может использовать write_stdin с их session_id.
Claude Code и поддерживаемые ACP-агенты запускаются в управляемом режиме с прямой командой, cli_agent и task. Система передаёт поручение и обрабатывает запросы разрешений. Для отдельной диагностики, например claude auth status --text, используется обычная команда.
| Field | Type | Description |
|---|---|---|
| commandrequired | string | Команда для запуска в shell-сессии. |
| workdir | string | Папка относительно папки чата или корень (`work/site`). Путь вне папки чата отклоняется. |
| grace_seconds | float (0–300) | Начальное окно наблюдения, по умолчанию 10 с. Для конечных команд рантайм ограничивает длительность окна. |
| notify_on_exit | boolean | По умолчанию `true`, чтобы получить итог автоматически. Укажите `false` для сервера, watcher'а или демона, которого оставляют работать. |
| sandbox | "workspace" | "host" | На Mac shell идёт под профилем Seatbelt (`workspace`, по умолчанию). `host` снимает профиль на один вызов и показывает человеку карточку согласия. |
| justification | string (≤300) | Обязательна с `sandbox="host"` и только с ним: одна фраза для карточки согласия. |
Возвращает session_id, pid, stdout, status (running / exited / killed), exit_code, alive и next_since: передайте его в since у write_stdin, чтобы продолжить чтение с того же места. dropped_bytes > 0 значит, что начало вывода вытеснено из буфера и потеряно.
write_stdin: управление живой сессией
Читает вывод и состояние сессии exec_command, в том числе сохранённый результат после выхода. Работающая сессия также принимает ввод. Добавьте \n, чтобы отправить строку.
| Field | Type | Description |
|---|---|---|
| session_idrequired | string | Идентификатор сессии, полученный от exec_command. |
| input | string | Символы в stdin. Добавьте \n, чтобы отправить строку. Пустая строка (по умолчанию) только читает вывод; одиночный \u0003 это Ctrl-C. |
| since | int | `next_since` из прошлого ответа; вернёт только вывод после него. Без него читается вывод, появившийся после этой записи. |
| wait_seconds | float (0–300) | Окно сбора вывода интерактивной сессии. Ноль с пустым вводом сразу возвращает снимок. Положительное значение с пустым вводом ставит ход на паузу до результата ещё выполняющейся конечной команды. |
edit_file: точечные правки файлов
Создаёт, перезаписывает, правит, удаляет и переименовывает файлы там, где идёт ход (облако или компьютер пользователя). Операцию выбирает op; op="patch" принимает V4A-патч сразу по нескольким файлам. При сопоставлении целых строк допускаются различия в краевых пробелах и типографских знаках; если текст не найден или неоднозначен, агент получает диагностику для исправления правки.
Что видно через API
Вызовы инструментов приходят в OpenAI-совместимом эндпоинте именованными событиями samreshuuu.tool (tool_started / tool_completed), если потоковый запрос передаёт tool_events: true (Стриминг). repl_execute доступен внешним клиентам и через MCP-сервер.
Полный список инструментов
Эта страница покрывает инструменты выполнения кода. Полный каталог по всем категориям (поиск, память, коннекторы, медиа, …) на странице Агенты → Доступные инструменты.