- Agents API, Agents SDK и Responses API
- Что такое среда выполнения агента?
- Зачем агенту все еще нужна песочница
- Novita Sandbox в этой архитектуре
- Жизненный цикл, сохранение состояния и длительные задачи
- Подключение Novita к пути самостоятельного хостинга
- Безопасность и учетные данные
- Затраты и лимиты
- Где эта архитектура подходит
- Часто задаваемые вопросы
- Рекомендованные статьи
API агентов OpenAI позволяет запустить долговечного облачного агента одним вызовом для создания сессии, пока OpenAI управляет средой выполнения агента в облаке. Novita Sandbox не заменяет API агентов или управляемую OpenAI среду выполнения. Он предоставляет изолированную, сохраняющую состояние среду выполнения для пути с самостоятельным хостингом, описанного OpenAI: ваше приложение подключает песочницу к сессии, агент выполняет команды и редактирует файлы внутри этой среды, а ваше приложение управляет жизненным циклом песочницы. Такое разделение важно, когда вам нужен рабочий процесс агента, размещенный в OpenAI, но требуется отдельная, повторно используемая среда для кода, файлов, браузера, использования компьютера и длительных задач.
Это руководство объясняет основные концепции API, как распределяются обязанности между средой выполнения и приложением, как подключить Novita Sandbox к пути самостоятельного хостинга и что проверить перед переходом от прототипа к продакшену. Если вам нужна только страница продукта, Novita Sandbox — лучшая отправная точка.
Agents API, Agents SDK и Responses API
Сравнение сред выполнения агентов от OpenAI разделяет три модели интеграции:
| Что вы хотите | Используйте | Что управляет состоянием |
|---|---|---|
| Запустить длительную задачу через управляемую OpenAI среду выполнения Codex | Agents API | Сохраненная конфигурация сессии, шаги и элементы |
| Оставить цикл агента в вашем приложении | Agents SDK | Состояние вашего приложения, сессии SDK или беседы Responses |
| Вызывать модели напрямую и управлять всем самостоятельно | Responses API | История вашего приложения или беседы Responses |
Agents API — самый высокоуровневый вариант. OpenAI описывает его как доступ к среде выполнения Codex через управляемый OpenAI API. Он обрабатывает сессии, оркестрацию, сжатие контекста и восстановление. Agents SDK работает внутри вашего приложения и дает больше контроля над развертыванием, хранением, утверждениями и интеграцией среды выполнения. Responses API находится ближе всего к уровню модели. Это разделение полезно, потому что «Агент» может означать либо повторно используемую конфигурацию модели/инструментов, либо долговечного запущенного агента; документация API использует эти термины по-разному в каждой среде выполнения.
Что такое среда выполнения агента?
Среда выполнения агента — это облачный сервис, обеспечивающий шаг агента. Она отправляет инструкции и контекст модели, вызывает инструменты, отслеживает прогресс, обрабатывает прерывания и возобновление, а также организует работу в наблюдаемый поток. В Agents API этой средой является управляемая среда выполнения Codex.
Управляемая среда выполнения поддерживает:
- Выполнение команд и кода при подключении среды.
- Применение соответствующих навыков и инструкций.
- Подключение к внешним данным через инструменты или MCP.
- Управление агентом во время его работы.
- Обобщение предыдущей работы для управления окном контекста.
- Разбиение работы на подзадачи и делегирование подчиненным агентам.
- Возобновление сессии с того места, где она остановилась.
Это не означает, что ваше приложение исчезает. Ваше приложение по-прежнему создает сессию, отправляет ввод, получает события, обрабатывает утверждения или вызовы функций и решает, как хранить идентификаторы и артефакты. Среда выполнения уменьшает объем работы по оркестрации, но не отменяет политику продукта.
Зачем агенту все еще нужна песочница
Некоторые агенты отвечают на вопросы или вызывают удаленные API без доступа к файловой системе. Другим нужно создавать файлы, устанавливать зависимости, выполнять скрипты, инспектировать браузер, управлять рабочим столом или поддерживать многошаговую задачу активной, пока пользователь отсутствует. Песочница предоставляет таким действиям заменяемую среду выполнения, не позволяя им касаться вашего сервера продукта или локальной машины.
Agents API рассматривает среду как опциональную. Архитектурная документация OpenAI поддерживает три варианта выполнения:
none— у среды выполнения нет оболочки или файловой системы. Инструменты-функции возвращают результаты в среду выполнения.openai_hosted— OpenAI предоставляет и управляет песочницей.self_hosted— ваше приложение запускает и подключает среду, так что вы можете использовать свои собственные вычислительные ресурсы, частную сеть или пользовательское ПО.
Здесь граница между двумя системами наиболее ясна. Agents API и OpenAI могут размещать среду выполнения, но среда с самостоятельным хостингом позволяет вашей команде выбирать платформу выполнения. Этот выбор влияет на изоляцию, форму файловой системы, сетевые возможности, SDK, поведение при паузе/возобновлении, биллинг и объем поддерживаемой инфраструктуры.
Novita Sandbox в этой архитектуре
Novita Sandbox — это управляемая среда выполнения для AI-агентов. Официальный обзор описывает изолированные, сохраняющие состояние среды выполнения для запуска кода, установки зависимостей, доступа к файлам, использования браузеров и сохранения состояния между сессиями без управления инфраструктурой. В прямом стеке, использующем только Novita, ваше приложение создает песочницу, модель или фреймворк агента выбирает вызовы инструментов, песочница их выполняет, а ваше приложение обеспечивает политику, утверждения и хранение вне среды выполнения.
При использовании Agents API рекомендуется точная формулировка: дополнение, а не родная интеграция. Текущие руководства OpenAI по песочницам с самостоятельным хостингом перечисляют Cloudflare, Daytona, DigitalOcean, E2B, Blaxel, Modal, Runloop, OCI и Vercel как документированных провайдеров. Novita Sandbox в настоящее время отсутствует в этом списке провайдеров. Поэтому практический путь — использовать Novita как управляемую вашим приложением среду выполнения и подключить ее к сессии Agents API через контракт OpenAI для самостоятельного хостинга. Это сохраняет полезное разделение — OpenAI запускает долговечную среду выполнения, Novita Sandbox предоставляет среду выполнения — без заявлений об официальной интеграции провайдера, которая в текущих документах не поддерживается.
Novita Sandbox построена на пяти концепциях:
| Концепция | Что она дает агенту |
|---|---|
| Sandbox (Песочница) | Изолированная среда выполнения с собственной файловой системой и пространством процессов |
| Template (Шаблон) | Воспроизводимый начальный образ, зависимости, конфигурация и настройка |
| Snapshot (Снимок) | Сохраненное состояние песочницы, которое можно повторно использовать, чтобы избежать повторной настройки |
| Secret (Секрет) | Зашифрованные значения в рамках команды, позволяющие избежать жесткого кодирования учетных данных |
| Region (Регион) | Местоположение текущих US v1/v2 конечных точек |
Среда выполнения поддерживает задачи для агентов кодирования, браузерных агентов, анализа данных, исследований и подкрепляющего обучения. Обзор Novita Sandbox является источником информации о текущих регионах и поведении жизненного цикла.
Жизненный цикл, сохранение состояния и длительные задачи
Novita Sandbox имеет три состояния жизненного цикла: запущена, приостановлена и завершена. Запущенная песочница может выполнять команды и обслуживать соединения. Приостановленная песочница сохраняет файловую систему и состояние в памяти, включая запущенные процессы и переменные, при этом биллинг за ЦП и ОЗУ останавливается. Сетевые соединения прерываются до возобновления. Завершенная песочница уничтожается и не может быть восстановлена.
Два тайм-аута управляют переходами: тайм-аут песочницы отсчитывается с момента создания, а тайм-аут бездействия срабатывает, когда в течение заданного времени ни один клиент не был подключен. В любом из этих событий вы можете выбрать приостановку, а не завершение, и при желании включить автоматическое возобновление. Это полезно для задачи редактирования кода, ожидающей проверки, для сеанса браузера, который приостанавливается между шагами, или для ноутбука анализа данных, который возобновляется позже с сохраненными зависимостями и переменными.
Снимки отличаются от приостановки. Приостановка сохраняет текущее состояние песочницы для этого экземпляра. Снимок фиксирует состояние как повторно используемую среду, так что новая песочница может запуститься с уже установленными зависимостями, конфигурацией и файлами. В продакшене используйте шаблоны для повторяемых базовых образов, снимки для повторно используемых рабочих состояний, а секреты для учетных данных, а не встраивайте их в шаблон или снимок.
Подключение Novita к пути самостоятельного хостинга
Руководство OpenAI по песочницам с самостоятельным хостингом определяет форму соединения. Ваше приложение создает сессию с environment.type: "self_hosted", получает идентификатор среды и удаленный URL, запускает исполнителя внутри вашей среды выполнения, а затем сообщает о подключении сессии. Официальная команда исполнителя:
codex exec-server \
--remote "<session.environment.remote_url>" \
--environment-id "<session.environment.id>"
Поток событий сессии сообщает agent.session.environment.pending, connected или failed. Вы должны оставить исполнителя работающим, пока агент работает, и координировать завершение работы перед остановкой вычислений.
Следующий эскиз показывает сторону Novita этого потока с использованием официального SDK Novita. Он создает песочницу, подготавливает аутентификацию без размещения секрета в исходном коде и предоставляет вам место для запуска исполнителя OpenAI. Точный способ внедрения ключа исполнителя и ожидания потока событий зависит от вашего приложения и версии SDK OpenAI.
import os
from novita_sandbox import Novita
def create_agent_runtime() -> str:
novita = Novita(api_key=os.environ["NOVITA_API_KEY"])
sandbox = novita.sandbox.create(
"codex",
timeout=3600,
envs={"CODEX_API_KEY": os.environ["CODEX_EXECUTOR_KEY"]},
)
try:
sandbox.git.clone(
"https://github.com/your-org/your-repo.git",
path="/home/user/repo",
username="x-access-token",
password=os.environ["GITHUB_TOKEN"],
depth=1,
)
print(
"Создайте сессию Agents API с environment.type=self_hosted, "
"затем запустите codex exec-server здесь."
)
except Exception:
sandbox.kill()
raise
return sandbox.sandbox_id
Перед использованием этого пути в продакшене проверьте текущие объекты SDK OpenAI, имя ключа среды, поведение удаленного URL и требования жизненного цикла в руководстве OpenAI по песочницам с самостоятельным хостингом. Не предполагайте, что API сессии будет управлять песочницей за вас; при self_hosted эта ответственность явно лежит на вас.
Для более простого рабочего процесса без Agents API руководство Novita по агенту Codex показывает, как запустить CLI Codex непосредственно в шаблоне codex, передавать его вывод и завершить песочницу после завершения.
Безопасность и учетные данные
Относитесь к среде выполнения, песочнице и серверу приложения как к отдельным доменам доверия.
- Храните ключи API OpenAI, ключи API Novita, токены Git и учетные данные базы данных вне подсказок и исходных файлов.
- Используйте секреты Novita Sandbox для конфиденциальных значений в масштабах команды, используемых внутри песочницы.
- Используйте хранилища OpenAI для учетных данных, которые, согласно рекомендациям OpenAI, должны находиться вне песочницы.
- Отдавайте предпочтение безопасному доступу к песочнице. Документация Novita говорит, что безопасный доступ включается автоматически для песочниц, созданных с использованием SDK версии 2.0.0 или новее; старые пользовательские шаблоны могут потребовать пересборки.
- Установите явную сетевую политику и расширяйте ее только тогда, когда это необходимо для задачи.
- Проверяйте сгенерированный код и артефакты, прежде чем они получат более широкие разрешения или попадут в производственные системы.
Эти элементы управления работают вместе. Песочница уменьшает радиус взрыва сгенерированного кода, но она не авторизует агента, не проверяет намерения и не решает, какие артефакты могут покинуть среду выполнения.
Затраты и лимиты
OpenAI выставляет счета за использование модели Agents API по тарифам выбранной модели и за инструменты OpenAI по стандартным тарифам. Для среды, размещенной OpenAI, применяется тариф контейнера. Для пути с самостоятельным хостингом ресурсы выполнения оплачиваются вашему провайдеру.
Биллинг Novita Sandbox осуществляется за секунду за ЦП и ОЗУ, пока песочница работает. Приостановка останавливает начисление платы за ЦП и ОЗУ. Приостановленные данные хранятся как постоянное хранилище; каждая учетная запись включает 60 ГБ бесплатного постоянного хранилища, дополнительное хранилище оплачивается почасово. Каждая запущенная песочница включает 20 ГБ эфемерного хранилища. Официальные кредиты и цены на Sandbox могут меняться, поэтому подтвердите текущие значения на странице цен Novita Sandbox.
Квоты Novita также важны для параллельных рабочих нагрузок. На момент написания статьи бесплатные учетные записи имеют по умолчанию 5 одновременных песочниц, а платные — 100; максимальное количество vCPU и объем памяти для одной песочницы различаются в зависимости от уровня. Корпоративные лимиты можно настроить. Проверьте руководство по лимитам квот и Sandbox.get_quota(), а не полагайтесь на примеры с маркетинговых страниц.
Где эта архитектура подходит
Среда выполнения Novita с самостоятельным хостингом хорошо подходит, когда:
- Агент должен выполнять код, изменять файлы, устанавливать зависимости, запускать тесты, просматривать веб-страницы или взаимодействовать с рабочим столом.
- Приложению требуются сессии с сохранением состояния с учетом задержек от человека, повторных попыток или многоэтапных проверок.
- Вы хотите изолированное выполнение, отдельное от вашего сервера продукта.
- Ваша рабочая нагрузка выигрывает от шаблонов, снимков, паузы/возобновления или воспроизводимых сред.
Она не подходит, когда:
- Задаче нужны только удаленные вызовы функций и не требуется файловая система или оболочка.
- Вам нужна среда, управляемая OpenAI, и вы не хотите управлять жизненным циклом среды.
- Вам требуется провайдер, указанный в текущих прямых руководствах OpenAI по провайдерам песочниц.
- Ваша модель соответствия требует элементов управления изоляцией, управляемых провайдером, которые Novita не документировала для вашего развертывания.
Самая безопасная оценка — это небольшой proof of concept с вашим реальным репозиторием, командами, сетевой политикой, обработкой секретов и путями отказов. Затем измерьте время запуска, паузу/возобновление, завершение задачи и общую стоимость репрезентативного запуска.
Часто задаваемые вопросы
Имеет ли Novita Sandbox нативную интеграцию с OpenAI Agents API?
Согласно текущим руководствам OpenAI по провайдерам среды — нет. Корректная архитектура — использовать путь самостоятельного хостинга Agents API, запустить Novita Sandbox как управляемую вашим приложением среду выполнения и запустить в ней документированного исполнителя. Проверьте текущие руководства перед выпуском, так как интеграции провайдеров могут меняться.
Нужна ли мне все еще Novita, если OpenAI предлагает размещенную песочницу?
Это зависит от ваших требований. Размещенная песочница OpenAI — это путь с минимальными операциями. Novita Sandbox полезна, когда вам нужен отдельный выбор среды выполнения для пользовательских образов, шаблонов, снимков, рабочих процессов с браузером или компьютером, сохранения состояния с паузой/возобновлением или контроля ресурсов на уровне провайдера.
Может ли агент сохранять процессы и файлы во время паузы?
Да. Документация Novita по паузе/возобновлению говорит, что файловая система и состояние в памяти, включая запущенные процессы и переменные, сохраняются. Сетевые соединения прерываются до возобновления работы песочницы.
Это то же самое, что OpenAI Agents SDK?
Нет. Agents SDK работает в вашем приложении и дает больше контроля над циклом агента. Agents API использует управляемую среду выполнения Codex от OpenAI. Novita Sandbox может размещать выполнение для любого из шаблонов, но поведение сессии и оркестрации различается.
С чего мне начать?
Попробуйте краткое руководство по OpenAI Agents API, чтобы понять сессии среды выполнения и события. Затем создайте Novita Sandbox и решите, соответствуют ли ее среда выполнения, жизненный цикл, безопасность и модель затрат вашим производственным потребностям.
