OpenAI Agents SDK Sandbox 2026: как провести приёмку перед запуском?

Победитель — поэтапная приёмка OpenAI Agents SDK Sandbox, а не успешный демонстрационный запуск. К запуску можно допускать только среду, которая последовательно прошла проверку контракта рабочего пространства, детерминированной логики, реального выполнения, изоляции прав, восстановления состояния и отката. Отдельный облачный Mac нужен лишь тогда, когда в задаче есть зависимости от macOS, параллельные изолированные прогоны или короткое окно интенсивной регрессии.

Эта статья предназначена для трёх групп:

• разработчиков, которые уже запустили пример SandboxAgent, но ещё не установили критерии допуска;
• платформенных инженеров, проверяющих чтение файлов, выполнение команд, сеть и границы доступа к секретам;
• технических руководителей, распределяющих проверки между локальной машиной, контейнером и облачным Mac.

Последнее обновление: 26 августа 2026 года. Статус beta и описанные границы сверены с официальным руководством по Sandbox Agents, описанием жизненного цикла Sandbox, справочником SandboxRunConfig и руководством по тестированию.

До первого запуска: зафиксируйте контракт рабочего пространства

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

В контракте стоит указать:

• какие файлы агент может читать;
• какие файлы он может изменять или создавать;
• где разрешены временные артефакты;
• какие каталоги запрещены без исключения;
• какие переменные окружения разрешены;
• разрешён ли доступ к сети;
• какие секреты передаются задаче и в каком виде;
• какие команды требуют отказа или ручного подтверждения;
• что должно произойти после завершения или аварийного окончания сессии.

Для каждого запуска полезно сохранять манифест, идентификатор версии окружения, ожидаемую конфигурацию SandboxRunConfig, список инструментов и идентификатор исполнителя. Такой снимок становится исходной точкой для расследования: без него нельзя надёжно понять, изменилась ли среда или изменилась логика агента.

Окружение должно создаваться повторно. Файл, случайно оставшийся на ноутбуке, установленный вручную пакет или широкое право доступа не являются частью контракта. Если пример работает только на машине автора, это пока демонстрация, а не приёмочный стенд.

Что нужно проверить перед запуском OpenAI Agents SDK Sandbox? Не только успешный ответ модели. В область проверки входят входные файлы, команды, права, сетевые направления, секреты, создаваемые артефакты, состояние сессии и процедура удаления. Каждая граница должна иметь ожидаемый результат: разрешено, отклонено или отправлено на подтверждение.

Важно: статус beta означает, что API, настройки по умолчанию и поддерживаемые возможности могут измениться до общего выпуска. Приёмочные записи должны содержать версию SDK и дату проверки, а не только название функции. Текущий статус и ограничения следует сверять с официальной документацией Sandbox Agents.

Этап 1 против Этапа 2: логика оркестрации и реальное выполнение

Первый технический проход должен быть детерминированным. Для него используются официальные тестовые инструменты, которые заменяют реальную модель и выполнение в Sandbox заранее заданными ответами. Это позволяет проверить маршрутизацию инструментов, параметры вызова, ветвления ошибок, повторные попытки и обработку финального результата без нестабильности внешнего исполнителя.

Минимальный набор сценариев:

1. обычный вызов инструмента с корректными параметрами;
2. команда возвращает ошибку;
3. запрошенный файл отсутствует;
4. инструмент отвечает неполными или неожиданными данными;
5. процесс завершается раньше ожидаемого шага;
6. повторная попытка не должна дублировать уже выполненное опасное действие.

Названия сценариев и ожидаемые результаты нужно хранить рядом с кодом. Для воспроизводимого сеанса можно изучить API scripted_sandbox_session. В документации по трассировке Agents SDK следует дополнительно проверить, какие события записываются и как связывать вызов инструмента с итоговым решением.

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

На втором этапе запускается тот же представительский сценарий в настоящей Sandbox-сессии. Здесь сравниваются не только текстовые ответы, но и наблюдаемые последствия:

• фактический рабочий каталог;
• список изменённых файлов;
• права созданных файлов;
• код завершения команды;
• содержимое и формат артефактов;
• сетевые обращения, если сеть разрешена;
• поведение при отсутствии зависимости;
• очистка временных данных.

Почему локально прошедший агент ломается после публикации? Обычно причина не в одном «плохом» ответе модели. Локальная машина могла содержать файл, пакет, переменную окружения или право на каталог, которых нет в целевой среде. Обратная ситуация также опасна: тестовый контейнер может получить более узкий доступ, чем будущий управляемый исполнитель, и тогда команда ошибочно считает границу проверенной.

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

Этап 2 против Этапа 3: воспроизводимость среды и macOS-зависимости

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

В журналах приёмки стоит отдельно отметить:

• как создаётся чистая рабочая область;
• откуда берутся зависимости;
• какие каталоги монтируются;
• какие файлы считаются входом и выходом;
• как определяется завершение задачи;
• что сохраняется после прогона;
• как очищается среда перед следующим запуском.

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

Если в цепочке есть macOS-инструменты, системные фреймворки, подпись, профили, сборка приложений или иные компоненты операционной системы, контейнер на другой платформе не заменяет реальную проверку. В таком случае требуется настоящий Mac. Облачный Mac становится полезным не потому, что слово «облако» само по себе повышает изоляцию, а потому, что команда получает отдельный воспроизводимый экземпляр macOS для повторной приёмки.

Проверяемая граница	Детерминированный тест	Реальный Sandbox	Отдельный Mac
Параметры инструментов	Да	Да, с реальными последствиями	Только если инструмент зависит от macOS
Файлы и рабочий каталог	Нет, лишь смоделированный ответ	Да	Да при системной зависимости
Процессы и коды завершения	Частично	Да	Да, если важен системный процесс
Подпись и системный SDK	Нет	Только в совместимой среде	Да
Параллельные независимые прогоны	Моделируются	Проверяются интеграционно	Удобен для изолированных стендов
Восстановление снимка или состояния	Моделируется	Обязательно проверяется	Нужен, если целевая доставка использует Mac

Какие проверки требуют отдельного Mac? Только те, где результат меняется из-за macOS: системная сборка, подпись, доступ к специфическому инструменту, совместимость с окружением доставки или параллельные прогоны, которые нельзя безопасно разместить на рабочем компьютере. Для обычной логики маршрутизации и обработки ошибок отдельная машина не заменяет детерминированные тесты и не должна использоваться вместо них.

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

Этап 3 против Этапа 4: минимальные права и опасные операции

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

Как проверить права SandboxAgent на файлы и команды? Для каждого инструмента нужно составить пару «разрешено — запрещено». Например, разрешить чтение входного каталога, запретить соседний каталог, разрешить создание результата, запретить перезапись исходного файла. Для команд аналогично проверяются допустимый исполняемый файл, аргументы, рабочий каталог и код завершения.

Отдельно проверяются четыре класса риска:

1. чтение данных за пределами рабочей области;
2. удаление или перезапись без подтверждения;
3. отправка содержимого во внешнюю сеть;
4. выполнение команды с незаявленной привилегией.

Если операция опасна, ожидаемый результат должен быть формализован. Это может быть отказ, запрос подтверждения или остановка сессии. Формулировка «агент должен быть осторожным» не является критерием приёмки.

Проверяются также:

• отсутствие лишних секретов в окружении;
• запрет вывода токенов в логи;
• ограничения на внешнее хранилище;
• поведение при неверном или просроченном секрете;
• невозможность использовать результат одной задачи как вход другой;
• очистка секретов после завершения.

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

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

Этап 4 против Этапа 5: прерывание, снимок и продолжение задачи

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

Затем проверяется:

• сохранилось ли ожидаемое состояние сессии;
• доступен ли снимок или сохранённая рабочая область;
• продолжает ли задача с последнего подтверждённого шага;
• не выполняется ли опасная команда повторно;
• не попадают ли старые файлы в новую сессию;
• очищается ли повреждённая рабочая область.

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

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

• остановить задачу и уведомить владельца;
• удалить среду и создать новую;
• вернуть задачу в очередь;
• запретить автоматическое продолжение;
• сохранить журналы для расследования.

Новая сессия не должна автоматически наследовать старые рабочие файлы только потому, что используется тот же каталог. Если наследование требуется, его нужно объявить частью контракта и проверить отдельным тестом.

Этап 5 против Этапа 6: критерии допуска, дополнительная проверка и блокировки

Результаты лучше делить на три статуса:

• пройдено — ожидаемое поведение подтверждено повторяемым тестом;
• нужна дополнительная проверка — есть неполный журнал, несовпадение среды или неисполненный отрицательный сценарий;
• блокировка — обнаружено нарушение границы или отсутствует безопасный путь завершения.

Блокирующими считаются:

• доступ к незаявленному каталогу;
• утечка секрета в вывод или трассировку;
• невозможность повторно создать целевую среду;
• непредсказуемое восстановление;
• повторное выполнение уже завершённой опасной операции;
• отсутствие отката после неудачного прогона;
• смешивание файлов двух задач;
• подмена реальной macOS-проверки результатом на другой платформе.

Таблица ниже помогает не спутать тип доказательства с типом риска.

Этап	Что считается доказательством	Что блокирует выпуск
Контракт	Версионированный манифест, список прав и ожидаемых артефактов	Неясные границы или зависимость от случайных файлов
Детерминированная логика	Повторяемые сценарии успешного вызова и ошибок	Неверный маршрут, бесконтрольный retry, потеря финального результата
Интеграционная среда	Чистое создание, одинаковые зависимости и проверенные артефакты	Невоспроизводимость или отличие рабочего каталога
Изоляция	Отказы на запрещённые файлы, команды, сеть и секреты	Любое подтверждённое превышение полномочий
Восстановление	Контрольная точка, прерывание, продолжение без дублирования	Повтор опасной операции или перенос старого состояния
Откат	Правило остановки, очистки и повторного создания	Нет безопасного выхода после сбоя

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

Для команд, которые проводят длительную регрессию на Mac, полезно заранее определить способ доступа и порядок передачи стенда. Данные учётной записи и параметры подключения лучше хранить отдельно от кода; для управления доступом можно использовать консоль ProxyMac. Это организационная мера, а не доказательство изоляции Sandbox, поэтому права самого агента всё равно проверяются описанными сценариями.

Чек-лист перед решением о выпуске

Ниже перечислены действия, которые можно отмечать только после сохранения подтверждающего артефакта.

• [ ] Зафиксирован манифест рабочей области и версия SandboxRunConfig.
• [ ] Описаны разрешённые и запрещённые файлы, каталоги, команды и переменные.
• [ ] Среда создаётся с нуля без ручных файлов на машине разработчика.
• [ ] Детерминированно проверены нормальный путь, ошибка команды и отсутствие файла.
• [ ] Отдельно проверены раннее завершение, повторная попытка и обработка финального результата.
• [ ] Реальный Sandbox-прогон выполнен с целевыми зависимостями и рабочим каталогом.
• [ ] Сохранены список артефактов, коды завершения и результаты очистки.
• [ ] Проверены чтение за пределами области, перезапись, удаление, сеть и секреты.
• [ ] Для опасных действий задан отказ, запрос подтверждения или остановка.
• [ ] Выполнено прерывание до и после контрольной точки.
• [ ] Восстановление не повторяет завершённую опасную операцию.
• [ ] Новая сессия не получает старые файлы без явно объявленного наследования.
• [ ] Для неудачного восстановления определены остановка и пересоздание среды.
• [ ] Mac-зависимые операции проверены на реальном Mac.
• [ ] Все результаты распределены по статусам «пройдено», «нужна дополнительная проверка» или «блокировка».
• [ ] Сохранены конфигурация, журналы, трассировка, исключения и ответственный.
• [ ] Установлена дата следующего пересмотра после изменения API или снятия beta-статуса.

Когда текущая среда уже не подходит

Если проверка блокируется macOS-зависимым инструментом, локальная машина часто создаёт сразу несколько проблем: она занята разработчиком, её состояние трудно воспроизвести, а параллельные тесты могут пересекаться по файлам и учётным данным. Контейнер решает часть проблем с повторяемостью, но не заменяет системные компоненты macOS и не доказывает корректность подписи или специфичного toolchain.

В таких условиях аренда изолированного облачного Mac у ProxyMac может быть более управляемым вариантом на период приёмки. Это особенно оправдано для короткой серии регрессий, одновременной работы нескольких инженеров и проверки доставки, которая действительно зависит от macOS. Перед началом следует зафиксировать образ среды, порядок очистки, способ доступа и срок использования, а после каждого существенного изменения повторить чек-лист.

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