LLM Sandbox: пример реализации агента с песочницей [часть 2, практика]

Введение

Статья посвящена практической реализации агента с изолированной средой исполнения кода. Рассказываю как устроен агент, который пишет и исполняет код в Docker песочнице.

Это вторая часть серии про LLM Sandbox. В первой части мы разобрали риски исполнения кода от LLM, ограничения песочницы, способы изоляции (Docker, Wasm, gVisor, microVM) и минимальную архитектуру агент+песочница.

Код реализации агента, skills, полные логи и артефакты примера — в открытом GitHub-репозитории.

Пара слов обо мне

Меня зовут Евгений. Я разработчик и лид ML-команды. На работе и в свободное время занимаюсь проектами, связанными с агентами, LLM и обработкой естественного языка в целом. В своём тг-канале делюсь практическим опытом и рассказываю про техническую часть AI и ML. Ссылка на пост-навигатор канала.

Реализация агента с песочницей

В этом разделе посмотрим как агент реализован в репозитории: оркестратор, субагенты, skills и Docker Sandbox.

Архитектура агента

Если кратко, агент работает так:

1. Получает задачу от пользователя.

2. С помощью инструментов выполняет планирование и составляет набор подзадач.

3. Назначает их субагентам.

4. Субагент пишет код для решения подзадачи и исполняет его в песочнице.

5. После выполнения подзадачи обновляется список задач.

6. Артефакты, полученные в песочнице, сохраняются, а выходные файлы показываются в интерфейсе и доступны для скачивания.

7. На финальном этапе оркестратор агрегирует решение всех подзадач и артефакты.

8. Выдаёт пользователю ответ.

Основной паттерн работы агента – гибрид ReAct + Plan-Execute. Основной фреймворк – LangGraph.

Посмотрим подробнее на ключевые блоки.

Содержимое агента

1. Оркестратор — мозг агента. Обрабатывает запрос пользователя, планирует решение задачи, включая декомпозицию, выдаёт задачи субагентам и синтезирует финальный ответ.

2. Субагент — сессия с LLM и чистым контекстным окном. Оркестратор передаёт субагенту конкретную задачу и необходимый контекст. Так можно не перегружать основного агента, а выполнять подзадачи независимо.

3. Внутри оркестратора и субагента находится LLM с отдельными системными промптами.

4. Каталог навыков (skills) — набор подробных инструкций под конкретные задачи. Например, в skills/presentation в репозитории полностью описан процесс написания презентаций.

   Что такое skills, я писал в канале. Оркестратор и субагенты всегда видят название и описание навыка, а при необходимости подгружают полную инструкцию через инструмент read_skill.

5. Инструменты для управления подзадачами.

   • create_todo_list — создаёт набор подзадач.

   • complete_todo — закрывает подзадачу при успешном решении.

   • start_next_todo — начинает работу над подзадачей.

   • revise_todo_list — пересобирает список подзадач, если текущий план перестал подходить.

   • block_todo — блокирует подзадачу, если решение пошло не по плану.

6. Инструменты управления файлами.

   • read_skill — читает навык из файла и добавляет его в контекст.

   • list_input_files — список файлов, отправленных пользователем.

   • list_output_files — список файлов, созданных в ходе задачи.

   • read_file_content — читает файл.

7. Инструменты исполнения кода.

   • write_python_file — подготавливает полный Python-скрипт и сохраняет в /workspace/code.

   • run_python_file — исполняет ранее подготовленный скрипт в песочнице.

8. Docker Sandbox — песочница для изолированного исполнения кода. В режиме субагента создаётся отдельный Docker контейнер на время выполнения подзадачи и серии sandbox-вызовов. Команда запуска описана в теоретической части, флаги: --network=none, --read-only, --cap-drop=ALL, --security-opt=no-new-privileges, non-root user, лимиты CPU/RAM/PIDs, tmpfs для /tmp, read-only mount для /workspace/input и /workspace/code.

Важно: Docker с такими флагами — практичная изоляция для локального MVP, для продуктивной среды может понадобиться более серьезная изоляция в несколько уровней. См. теоретическую часть.

Инструменты работы с Bash умышленно не предоставляются агенту для прозрачной и контролируемой работы с заданными инструментами.

Состояние запуска: что видит пользователь

В интерфейсе показывается весь путь агента: текущий план, закрытые подзадачи, вызовы инструментов и их результаты. Полные логи — в подключённом Langfuse, а локально — в agent/runs/<run_id>/events.jsonl, agent/traces/<run_id>.jsonl и agent/web-artifacts/<run_id>/.

Пример работы агента

Для наглядности посмотрим на конкретный запуск.

Задача (промпт)

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

Набор данных

Датасет соревнования «Титаник».

P.S. Модели видели этот датасет множество раз при обучении, и написать код аналитики несложно. Цель примера — показать взаимодействие агента с песочницей, а не способность LLM писать код.

Модель

Qwen3.5-27B — модель, которую можно развернуть на доступном железе. В репозитории это значение используется как дефолт (Qwen/Qwen3.5-27B), но его можно заменить через LLM_MODEL на любую OpenAI-совместимую модель.

Шаги выполнения задачи

Первым шагом агент создаёт список подзадач:

1. eda-analysis — первичный анализ данных.

2. create-presentation — создание презентации.

# Plan

- [>] eda-analysis: Exploratory data analysis of basic_dataset.csv **(active)**
    - skills: eda, python-scripts
    - inputs: /workspace/input/basic_dataset.csv
    - success: EDA script runs successfully and prints key statistics, distributions, correlations, and missing value summaries to stdout.
    - outputs: /workspace/out/eda_summary.csv
- [ ] create-presentation: Create PowerPoint presentation with key EDA findings
    - skills: presentation, python-scripts
    - inputs: /workspace/input/basic_dataset.csv, /workspace/out/eda_summary.csv
    - success: A .pptx file is generated with slides covering dataset overview, survival analysis, demographics, fare analysis, and key insights.
    - outputs: /workspace/out/titanic_eda_presentation.pptx

Для каждой подзадачи заданы требуемые навыки, входные/выходные файлы и критерии успеха.

Второй шаг — start_next_todo. Агент просматривает доступные входные файлы через list_input_files:

status: success
summary: Listed 1 input file(s).

- /workspace/input/basic_dataset.csv (61194 bytes)

Читает фрагмент CSV через read_file_content, затем пишет код через write_python_file:

import pandas as pd
import numpy as np

df = pd.read_csv('/workspace/input/basic_dataset.csv')

# === SHAPE ===
print("=== SHAPE ===")
print(df.shape)
print()

# === DTYPES ===
print("=== DTYPES ===")
print(df.dtypes)
print()
... <truncated>

Результат:

status: success
summary: Staged `eda_analysis.py` (131 lines). Next: run_python_file({"script_path": "eda_analysis.py"}).

Срабатывает валидация: файл не может быть больше 120 строк — агент делит его на два скрипта.

Исполняет в песочнице через run_python_file:

status: success
summary: success: Python execution succeeded (exit_code=0).

exit_code: 0
timed_out: False
succeeded: True
STDOUT:
=== SHAPE ===
(891, 12)

=== DTYPES ===
PassengerId      int64
Survived         int64
Pclass           int64
Name               str
Sex                str
Age            float64
SibSp            int64
Parch            int64
Ticket             str
Fare           float64
Cabin              str
Embarked           str
dtype: object
...<truncated>

Аналогично создаётся /workspace/out/eda_summary.csv. Подзадача закрывается через complete_todo:

{
  "id": "eda-analysis",
  "notes": "EDA script ran successfully, printed key statistics/distributions/correlations/missing values to stdout, and saved /workspace/out/eda_summary.csv with 25 summary metrics."
}

Следующая подзадача — презентация. Агент подгружает skills presentation и python-scripts. В процессе возможны ошибки, которые агент исправляет в следующих итерациях работы с кодом:

STDERR:
Traceback (most recent call last):
  File "/workspace/code/deck_build_part1.py", line 11, in <module>
    add_bg_rect(slide, DARK)
  File "/workspace/code/deck_helpers.py", line 17, in add_bg_rect
    width = slide.slide_width
            ^^^^^^^^^^^^^^^^^
AttributeError: 'Slide' object has no attribute 'slide_width'. Did you mean: 'slide_id'?

Итоговый ответ агента (сокращённо):

## Результаты анализа и презентация

### 📊 Ключевые выводы EDA (Titanic, 891 пассажир)

|Метрика|Значение|
|---|---|
|**Общий уровень выживших**|~38%|
|**Пропущенные данные**|Age: 20%, Cabin: 77.1%, Embarked: 0.22%|
...

### 📁 Созданные файлы

|Файл|Описание|
|---|---|
|`titanic_eda_presentation.pptx`|Презентация из 9 слайдов с графиками и выводами|
|`eda_summary.csv`|Сводка из 25 метрик EDA|
|`chart_survival.png`|Общая выживаемость|
...

Полные логи и артефакты — в репозитории.

Токен-экономика запуска

Пример выше — не только демонстрация песочницы, но и типичный агентский запуск с заметной «стоимостью» в токенах. Все LLM-вызовы, тайминги и usage отслеживались через Langfuse. Ниже — разбор run feec9b8b1e754c018d6de3f2f09d4f8c (Titanic + презентация, Qwen3.5-27B, OpenRouter/OpenAI-совместимый API).

Что считаем. На каждом шаге цикла модель получает промпт (input_tokens), генерирует ответ (output_tokens). Часть промпта может быть взята из KV-cache (cached_input_tokens). Песочница и файловые инструменты сами по себе токены не тратят, но результаты их работы возвращаются в контекст — и именно это раздувает входной запрос в модель на следующих шагах. В таблице ниже суммируются все вложенные LLM-вызовы оркестратора и субагентов из Langfuse.

Итого по запуску

Sandbox занял ~3% общего времени работы. Основная задержка — ожидание LLM и накопление контекста, а не исполнение Python.

Разбивка по фазам (данные Langfuse-трейса):

Что видно из цифр:

1. Оркестратор дешёвый — 17,6 тыс. токенов (4,7% от запуска). Он планирует, делегирует и синтезирует ответ, не таская в контекст логи.

2. Субагент presentation — главный потребитель — 286,5 тыс. токенов (76%) и 128 с (70% времени). Причина: много итераций write_python_file / run_python_file, ошибки в коде (slide_width), повторные прогоны и растущий контекст.

3. Контекст растёт по цепочке. Input на последнем LLM-вызове presentation-субагента — 24 706 токенов (против 4 445 на первом).

4. Самые дорогие вызовы — генерация кода, а не sandbox. write_python_file с output 1 777 токенов vs run_python_file с output 56 токенов.

5. Cache помогает, но не спасает от роста контекста. Суммарно из cache обслужено 252 384 токенов input (~70% у presentation-субагента).

Практический вывод: песочница изолирует исполнение, но не стоимость. Чтобы удержать token budget, нужны те же приёмы, что и в инжиниринге контекста: субагенты с чистым окном, лимиты на размер tool output, сокращение stdout/stderr, skills по требованию (read_skill), а не в каждый промпт целиком.

Заключение

На практике песочница встраивается в агентскую обвязку как один из инструментов агентского цикла — рядом с планированием, skills и файловыми операциями. Из этого запуска видно три вещи:

• Docker Sandbox с жёсткими флагами — рабочий вариант для локального MVP: отдельная сессия для подзадачи/сессии исполнения кода в песочнице, изоляция исполнения, понятный обмен артефактами через /workspace/input и /workspace/out.

• Оркестратор + субагенты помогают не смешивать планирование и «грязный» контекст исполнения кода.

• Основное время тратится на работу LLM. 7 запусков кода заняли ~5 с; основная стоимость — в генерации и накоплении контекста.

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

Теорию про риски, ограничения и альтернативы (Wasm, gVisor, microVM) смотрите в первой части. Код, логи и все артефакты смотрите в репозитории на GitHub.

P.S. Спасибо за прочтение. Приглашаю в тг-канал «В погоне за NLP» (@chasing_nlp) — там про новости из мира AI/ML, анонсы новых статей и опыт разработки проектов с LLM и агентами.

Серия «LLM Sandbox»

1. Часть 1. Теория — риски, ограничения, способы изоляции.

2. Часть 2. Практика — эта статья.

Другие мои статьи

1. Agent Harness: одна LLM, разные результаты — в чем секрет?

2. Второй мозг и LLM-Wiki: Теория и практический гайд по созданию и поддержке личной базы знаний