Руководство по нативной песочнице и Manifest в OpenAI Agents SDK

OpenAI выпустила важное обновление Agents SDK 15 апреля 2026 года, и показательной деталью стала строка установки в анонсе: pip install "openai-agents>=0.14.0" (OpenAI). Эта строка с версией важна. Это был не новый шаблон промпта и не очередная обертка над function calling. OpenAI перенесла работу с файлами, shell-командами, патчами, жизненным циклом песочницы и описанием workspace на уровень примитивов SDK.

Для разработчиков, которые создают кодинговых агентов, агентов для документов, агентов для очистки данных или ботов для поддержки репозиториев, сдвиг в дизайне прост: перестать заставлять каждую команду заново собирать один и тот же хрупкий harness вокруг Docker, временных директорий, схем инструментов, подготовки файлов и логики повторов. SDK теперь дает model-native harness, sandbox-native выполнение, инструменты файловой системы, MCP, AGENTS.md, доступ к shell, apply_patch и абстракцию Manifest для описания переносимых рабочих пространств.

Изменение: от вызовов инструментов к настоящему workspace

Оригинальный Agents SDK уже был полезен для оркестрации: агенты, инструменты, handoffs, guardrails, трассировка. Апрельское обновление добавляет недостающую форму runtime для агентов, которым нужно долго работать с файлами.

OpenAI описывает обновленный SDK как средство, помогающее разработчикам создавать агентов, которые могут инспектировать файлы, запускать команды, редактировать код и работать над долгими задачами в контролируемых средах-песочницах (OpenAI). Ключевая фраза здесь — «контролируемый workspace». Серьезному агенту, работающему с файлами, нужен не просто список инструментов. Ему нужны корневая директория, смонтированные входные данные, места для выходных данных, shell, разрешения, снапшоты и способ продолжить работу, если контейнер упадет.

До этого обновления типичная production-схема выглядела так:

• создать временный workspace
• скопировать в него файлы
• предоставить инструменты чтения, записи, shell и патчей
• вручную валидировать пути
• запустить песочницу или контейнер
• собрать артефакты
• сохранить снапшот состояния, если задача выполняется долго
• перевести все это в инструкции, понятные модели

Именно в таком glue code многие проекты агентов незаметно становятся запутанными. Новый SDK превращает значительную часть этого в конфигурацию первого класса.

В анонсе OpenAI перечислила встроенную поддержку Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop и Vercel как провайдеров песочниц, а также вариант «принести свою песочницу» (OpenAI). То есть семь hosted-провайдеров на старте плюс пути для локальной разработки.

Manifest — слой переносимости

Абстракция Manifest — самая практичная часть релиза. Она описывает, что должно находиться в sandbox workspace до того, как модель начнет работу.

В Python-документации Sandbox Agents помечены как beta, требуют Python 3.10 или выше и представлены как способ дать модели постоянный workspace, где она может искать по наборам документов, редактировать файлы, запускать команды, генерировать артефакты и продолжать работу из сохраненного состояния песочницы (документация OpenAI Agents SDK для Python).

Компактная форма на Python выглядит так:

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import LocalDir
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

agent = SandboxAgent(
    name="Repo maintainer",
    model="gpt-5.5",
    instructions="Read repo/task.md, edit with apply_patch, then run the targeted test.",
    default_manifest=Manifest(entries={"repo": LocalDir(src="./repo")}),
)

result = await Runner.run(
    agent,
    "Fix the failing test and summarize the change.",
    run_config=RunConfig(
        sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())
    ),
)

Важна не синтаксическая форма. Важен контракт. Manifest может описывать локальные файлы, директории, Git-репозитории, синтетические файлы, переменные окружения, пользователей, группы, выходные директории и монтирования удаленного хранилища. В JS-документации сказано, что пути записей Manifest задаются относительно workspace, не могут быть абсолютными и не могут выходить за пределы workspace через ... Это ровно то скучное ограничение, которое лучше enforce-ить на уровне runtime, а не помнить в каждом промпте (документация OpenAI Agents SDK для JS).

Возможности: shell, файловая система, skills, memory, compaction

SandboxAgent — это не просто обычный агент с временной папкой. У него есть возможности, специфичные для песочницы.

JS-документация по концепциям перечисляет встроенные capabilities, включая shell(), filesystem(), skills(), memory() и compaction() (документация OpenAI Agents SDK для JS). Здесь важны значения по умолчанию: в документации сказано, что Capabilities.default() включает файловую систему, shell и compaction. Это значит, что типичный цикл coding agent больше не является кучей самописных определений инструментов.

Возможность файловой системы предоставляет редактирование файлов в стиле патчей. Возможность shell предоставляет выполнение команд внутри sandbox-сессии. Skills позволяют постепенно раскрывать специализированные инструкции или процедуры. Memory и compaction помогают долгим запускам сохранять полезное состояние, не запихивая все предыдущие токены обратно в следующий ход.

Это соответствует тому, как на самом деле работают сильные coding agents. Они инспектируют. Запускают команду. Редактируют файл. Запускают команду поменьше. Смотрят diff. Резюмируют, что изменилось. Если ваш harness обрабатывает каждый шаг как несвязанный API-вызов, модель тратит слишком много внимания на реконструкцию своего мира. Sandbox-сессия дает модели точку опоры.

AGENTS.md тоже естественно вписывается в эту модель. Открытый сайт AGENTS.md описывает его как Markdown-формат для направления coding agents и говорит, что он используется более чем в 60 000 open-source проектов (AGENTS.md). Этот файл должен содержать команды сборки, инструкции по тестированию, правила стиля и специфичные для репозитория предупреждения. В мире песочниц AGENTS.md становится локальным для workspace операционным контекстом, а не гигантским промптом, вставляемым в каждую задачу.

Сначала Python, TypeScript догоняет

На старте это был Python-first релиз. TechCrunch сообщил 15 апреля, что новый harness и возможности песочницы сначала запускаются в Python, а поддержка TypeScript запланирована позже (TechCrunch). PyPI подтверждает дату: версии openai-agents 0.14.0 и 0.14.1 были загружены 15 апреля 2026 года (PyPI).

По состоянию на 16 июня 2026 года практическая картина стала более сбалансированной. Официальная JS-документация теперь включает beta Sandbox Agents, требует Node.js 22 или выше и показывает Manifest, SandboxAgent, UnixLocalSandboxClient, поддержку Docker и клиенты hosted-провайдеров через @openai/agents-extensions (quickstart OpenAI Agents SDK для JS). В JS-документации также отмечено, что Deno и Bun могут работать, если совместимы package resolution и runtime API.

Область	Python	TypeScript / JavaScript
Статус запуска 15 апреля	Первый поддерживаемый путь	Запланировано позже
Текущая документация по песочнице	Beta, Python 3.10+	Beta, Node.js 22+
Локальная песочница	UnixLocalSandboxClient	UnixLocalSandboxClient
Docker-песочница	openai-agents[docker]	DockerSandboxClient
Hosted-провайдеры	Поддерживаются через интеграции SDK	Пути провайдеров через @openai/agents-extensions

Это не значит, что две экосистемы идентичны. Python был исходной поверхностью запуска, и многие примеры по-прежнему сначала появляются там. У TypeScript теперь достаточно официальной поверхности, чтобы прототипировать настоящих sandbox agents, но детали hosted-провайдеров, поведение PTY, монтирования и поддержка жизненного цикла все еще требуют внимательного чтения для каждого backend.

Как я бы сейчас структурировал агента для работы с файлами

Ошибка — воспринимать песочницу как магическую коробку безопасности. Это runtime-граница, а не спецификация продукта. Workspace все равно нужно проектировать.

Чистая структура выглядит так:

• repo/: рабочее дерево или смонтированный репозиторий
• task.md: спецификация задачи, которую модель должна прочитать первой
• inputs/: read-only документы, датасеты, скриншоты или логи
• output/: единственное место, куда должны попадать финальные сгенерированные артефакты
• AGENTS.md: инструкции по сборке, тестам, стилю и безопасности
• пользователь песочницы: non-root идентичность там, где backend это поддерживает
• Manifest env: несекретная конфигурация, сохраняемая по умолчанию; секреты помечены как ephemeral

Manifest должен описывать входные данные. Инструкции агента должны описывать workflow. Пользовательский промпт должен описывать одноразовую задачу. Держите это отдельно. JS-документация прямо предупреждает, что не стоит запихивать длинные справочные материалы в instructions, если им место в Manifest (документация OpenAI Agents SDK для JS).

Для production выбирайте backend по blast radius, а не по демо-пути. Unix-local подходит для разработки. Docker — лучший вариант по умолчанию, когда нужна воспроизводимость. Hosted-провайдеры имеют смысл, когда нужны чистая изоляция на каждый запуск, удаленное выполнение, масштабирование или специфичное для провайдера поведение снапшотов. В документации JS-клиентов сказано, что поддержка hosted-провайдеров различается, и разработчикам следует проверять документацию провайдера по переменным окружения, портам, PTY, снапшотам и поведению очистки (клиенты OpenAI Agents SDK для JS).

Что это говорит об экосистеме

Это обновление важно, потому что оно стандартизирует форму агентов, работающих с файлами. Индустрия уже сошлась на нескольких примитивах: MCP для внешних инструментов, AGENTS.md для инструкций по репозиторию, shell для реальной инспекции, патчи для проверяемых правок и песочницы для containment. OpenAI Agents SDK теперь упаковывает эти части в runtime, который разработчики действительно могут компоновать.

Острый край по-прежнему — разрешения. Агент в песочнице с широким доступом к сети, writable-монтированиями, долгоживущими учетными данными и расплывчатыми инструкциями все еще может нанести ущерб. Manifest помогает, потому что делает входные данные workspace и выданные права видимыми. Но он не отменяет необходимости в политиках подтверждения, гигиене секретов, фиксации зависимостей и ревью артефактов.

Лучший сценарий сегодня — не «агент делает все». Он уже и ценнее: дать модели ограниченный workspace, понятный task file, локальные для репозитория инструкции, инструменты shell и патчей, а также один явный путь проверки. Пусть она работает как junior-инженер в одноразовой среде. Потом проверьте diff.

Это гораздо более здоровая абстракция, чем вручную собирать очередную полупесочницу вокруг chat loop.

Читатели, которые хотят попробовать эти модели на практике, могут вызывать их через onehop с OpenAI-совместимым API, изменив один base_url. Это дешевле, чем first-party, а новые аккаунты получают $10 бесплатного кредита без карты: вызывать Claude и другие модели на onehop или получить $10 бесплатного кредита.