Обзор E2B: песочница для кода ИИ-агента

Обзор E2B: песочница для кода ИИ-агента показывает, где живёт исполнение. Модель предлагает код, управляющее приложение держит ключи и решение, а изолированная среда запускает программу и возвращает результат. Документация проекта на https://e2b.dev/docs описывает sandbox как изолированную среду, в которой агенты безопасно исполняют код, обрабатывают данные и запускают инструменты.

Роль sandbox и граница с моделью

Sandbox отвечает за исполнение, файлы и команды. Модель отвечает за формулировку кода и объяснение результата. Эти роли расходятся по данным: в среду уходят только те файлы, которые нужны задаче, а ключ модели остаётся у управляющего приложения. Документация E2B называет sandbox быстрой защищённой Linux-машиной, создаваемой по требованию, которую можно приостанавливать и возобновлять. Шаблон задаёт стартовое окружение. Приостановка сохраняет файловую систему и память, а возобновление возвращает среду в прежнее состояние.

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

Карта данных для маленькой задачи: в среду передаются input.csv и main.py. Ключ модели для этого расчёта не нужен. Сеть для расчёта не требуется. Время ограничивается явно. После чтения report.json среда завершается. Это требования выбранной конфигурации; сетевые настройки E2B по умолчанию нужно проверить отдельно.

Для нашего расчёта нужно заранее решить, сохранять ли среду между пробами. Отрицательный CSV проверяется в чистой среде либо после удаления старого отчёта: иначе прежний файл можно ошибочно принять за новый результат.

Фрагменты кода и весь агент

Документация smolagents различает запуск фрагментов и всей системы агента в sandbox. Во втором случае внутри работает клиент модели; веса внешнего провайдера туда автоматически не переносятся.

Режим executor_type=e2b передаёт сгенерированный код в sandbox. Вызовы модели остаются у локального агента; для описанной интеграции многоагентный режим не поддерживается.

Для многоагентного режима руководство предлагает перенести систему агента внутрь E2B. Тогда отдельно настраивают окружение и передачу необходимых ключей.

Таблица ниже сопоставляет подходы по явным критериям из документации smolagents.

Для одиночного расчёта можно рассмотреть первый подход. Указанное ограничение многоагентного режима относится к описанной интеграции smolagents; его не следует переносить на любой способ использования E2B.

Core SDK и Code Interpreter SDK

Core SDK управляет командами и файлами; Code Interpreter добавляет runCode()/run_code() и пакет e2b_code_interpreter для Python. Устанавливайте пакет под выбранный способ исполнения, сверяясь с quickstart.

Code Interpreter сохраняет переменные между вызовами и возвращает результаты, включая графики. В нашем примере отдельная программа пишет report.json; это файл, который нужно прочитать и проверить независимо от текстового объяснения агента.

Установка core SDK:

pip install e2b

Установка Code Interpreter SDK:

pip install e2b-code-interpreter

Ключ задаётся переменной окружения E2B_API_KEY. Документация quickstart предлагает создать аккаунт, взять ключ в дашборде и положить его в .env. Актуальные условия доступа и стоимость исполнения проверяйте в своём аккаунте перед запуском.

Полный CSV, код и ручной эталон

Ниже учебный пример: маленькая задача с полным входом, полным кодом и ручным эталоном. Значения условные и служат проверкой логики. Редакция не запускала E2B, агента или этот код; ниже приведены ручные ожидаемые результаты.

Входной файл input.csv:

sku,qty
A-1,2
B-2,3
A-1,1

Программа main.py:

import csv
import json
from pathlib import Path

totals = {}
with open("input.csv", newline="", encoding="utf-8") as stream:
    for row in csv.DictReader(stream):
        quantity = int(row["qty"])
        if quantity < 0:
            raise ValueError("qty must be non-negative")
        sku = row["sku"]
        totals[sku] = totals.get(sku, 0) + quantity
report = json.dumps(totals, sort_keys=True, ensure_ascii=False)
Path("report.json").write_text(report, encoding="utf-8")
print(report)

Ручной эталон report.json: {«A-1″:3,»B-2»:3}. Всего 6 штук. Строка A-1 встречается дважды: 2 и 1, сумма 3. Строка B-2 встречается один раз: 3.

Для отрицательной пробы используйте отдельный чистый sandbox либо удалите прежний report.json перед запуском. Полный изменённый input.csv:

sku,qty
A-1,2
B-2,много
A-1,1

Преобразование int для второй строки должно вызвать ValueError. Программа не доходит до записи нового отчёта. Превращение нечислового значения в 0 считается дефектом. Старый файл от успешного прогона не является результатом отрицательной пробы; проверяйте его отсутствие в чистой среде либо время создания нового артефакта.

Проверка exit status, файла и объяснения

Проверка идёт по трём уровням. Первый уровень — статус завершения процесса. Ненулевой exit status означает сбой, и результат дальше не принимается. Второй уровень — файл report.json. Его содержимое сравнивается с эталоном по ключам и значениям. Третий уровень — итоговое объяснение агента.

Третий уровень ловит отдельный класс ошибок. Программа может записать верный файл, а агент сообщит «A-1=4». Файл при этом правильный, а объяснение неверное. Такая ошибка не проходит проверку, потому что читатель получает искажённый итог.

Порядок действий:

1. Запустить main.py в песочнице и зафиксировать exit status.
2. Прочитать report.json из среды.
3. Сравнить ключи и значения с эталоном {«A-1″:3,»B-2»:3}.
4. Сверить текстовое объяснение агента с содержимым файла.
5. Прогнать отрицательную пробу и убедиться, что обработка завершилась ошибкой.
6. Завершить sandbox.

Для нашего расчёта достаточно входного CSV и программы. Полномочия, сеть и время работы следует ограничить по этой задаче.

Ресурсы, сеть, секреты и завершение

Эти параметры настраиваются отдельно. Ресурсы: CPU и память проверяйте в конфигурации выбранного шаблона и информации о созданной среде. Сеть: в той же структуре есть поля allow_internet_access и network. Секреты: документация smolagents советует передавать их через переменные окружения. Завершение: метод kill в JavaScript и Python закрывает среду немедленно, до истечения таймаута.

Таймаут задаётся при создании. В JavaScript единицы измерения — миллисекунды, в Python — секунды. Пример из документации: timeoutMs 60_000 в JavaScript и timeout 60 в Python дают одну минуту. Метод setTimeout в JavaScript и set_timeout в Python меняют таймаут у работающей среды. Предельное время зависит от условий выбранного сервиса и аккаунта; сверяйте его перед запуском. Если используете pause/resume, отдельно проверяйте сохранение нужного состояния и дальнейший порядок завершения среды.

E2B Cloud и AWS sample

E2B Cloud и пример развёртывания на AWS — разные контуры. У них собственные домены, шаблоны и версии. Ключи и адреса одного контура не переносятся в другой. Документация quickstart на https://e2b.dev/docs/quickstart описывает облачный сценарий: аккаунт, ключ в дашборде, установка SDK, запуск. Пример на AWS идёт отдельным репозиторием со своим README.

Самостоятельное развёртывание описано в README проекта на https://raw.githubusercontent.com/e2b-dev/E2B/main/README.md. Инфраструктура разворачивается через Terraform. Поддерживаемые провайдеры: AWS, Google Cloud, Azure и обычная Linux-машина через Embed. Это отдельный путь со своими требованиями к окружению.

Практическое правило: выберите один контур и держите его ключи, домены и версии в одном месте. Смешение настроек облака и самостоятельного развёртывания даёт ошибки, которые трудно отнести к источнику.

Границы изоляции и обещаний

Изоляция не доказывает правильность вычисления. Руководство smolagents предупреждает, что безопасность локального исполнения не абсолютна. Наш эталон проверяет арифметику и обработку ошибочного входа; аудит защищённости E2B здесь не проводился.

Бесплатность, скорость и абсолютную изоляцию обещать нельзя. Условия доступа и ограничения сервиса могут меняться. Скорость зависит от шаблона, задачи и окружения. Изоляция снижает риск и не устраняет его полностью.

Промпт для проверки результата агентом:

Ты проверяешь результат расчёта в изолированной среде.
Вход: файл input.csv со столбцами sku и qty.
Программа: main.py, суммирует qty по sku и пишет report.json.
Эталон: {"A-1":3,"B-2":3}, всего 6 штук.
Сделай по шагам:
1. Запусти main.py и верни exit status.
2. Прочитай report.json и приведи его содержимое.
3. Сравни ключи и значения с эталоном, перечисли расхождения.
4. Сверь свой итоговый текст с содержимым файла.
5. В чистой среде подставь отрицательный CSV из статьи, где у B-2 qty=много. Покажи ошибку обработки и проверь, что новый report.json не создан.
Не заменяй нечисловое значение нулём. Заверши среду после проверки.

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

Частые вопросы

Что такое E2B простыми словами?

E2B — инфраструктура с изолированными песочницами, в которых агенты исполняют код, обрабатывают данные и запускают инструменты. Документация проекта описывает sandbox как защищённую Linux-машину, создаваемую по требованию. Управление идёт через JavaScript или Python SDK. Модель предлагает код, а среда его исполняет и возвращает результат.

Чем core SDK отличается от Code Interpreter SDK?

Core SDK управляет командами и файлами. Code Interpreter добавляет исполнение кода с сохранением переменных. Python-пакеты: e2b и e2b-code-interpreter.

Как проверить, что расчёт верный?

Сравните report.json с ручным эталоном по ключам и значениям. Проверьте exit status процесса. Сверьте текстовое объяснение агента с содержимым файла. Прогоните отрицательную пробу с нечисловым значением qty и убедитесь, что обработка завершилась ошибкой. Верный файл при неверном объяснении считается ошибкой.

Можно ли запустить весь агент внутри песочницы?

Да, smolagents описывает перенос системы агента внутрь sandbox. Передача ключей и настройка окружения требуют отдельной проверки.

Как завершить среду и ограничить время?

Таймаут задаётся при создании: миллисекунды в JavaScript, секунды в Python. Метод set_timeout меняет таймаут у работающей среды. Метод kill закрывает sandbox немедленно. Предельное время и доступность pause/resume сверяйте с условиями выбранного сервиса; завершение и сохранение состояния проверяйте отдельно.