OpenAI Agents SDK: как запускать агентов в песочницах Modal

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

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

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

В этом руководстве мы разберём, как совместить фреймворк OpenAI Agents с песочницами Modal, чтобы создать практическое агентное приложение. Агент сможет работать внутри изолированной среды Modal, безопасно выполнять команды, работать с файлами и возвращать полезные результаты в основное приложение.

Для введения без использования песочниц также рекомендуем прочитать наш учебник по OpenAI Agents SDK. 

Что нового в OpenAI Agents SDK?

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

Ключевые обновления:

• Нативная поддержка песочниц для запуска агентов в изолированных средах
• Манифест для определения файлов, папок и результатов, к которым агент имеет доступ
• SandboxAgent для подключения агента к изолированному рабочему пространству
• SandboxRunConfig для управления местом и способом запуска песочницы
• Инструменты в стиле Codex для редактирования файлов, shell-команд и инспекции проекта
• Поддержка MCP для подключения агентов к внешним инструментам и сервисам
• Поддержка Skills и AGENTS.md для более чётких инструкций по проекту для агентов
• Поддержка нескольких провайдеров песочниц, включая Modal, E2B, Cloudflare, Daytona, Blaxel, Runloop и Vercel

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

1. Настройка проекта

В этом демонстрационном проекте мы создадим небольшой пример триажа заявок в поддержку с помощью OpenAI Agents SDK и песочниц Modal. Приложение создаст изолированное рабочее пространство, добавит в него несколько файлов проекта, а затем попросит агента GPT-5.4-mini изучить эти файлы перед ответом.

Начните с установки необходимых пакетов в вашу среду:

pip install "openai-agents[modal]" modal

Перед запуском проекта вам нужны два аккаунта:

• Аккаунт OpenAI: Создайте аккаунт на OpenAI Platform и пополните API-кредиты банковской картой. Убедитесь, что ваш аккаунт верифицирован для доступа к последним поддерживаемым моделям.
• Аккаунт Modal: Зарегистрируйтесь в Modal. Бесплатный план включает месячные кредиты, которых достаточно для тестирования по этому руководству.

Затем добавьте ваш API-ключ OpenAI в локальную среду.

• В macOS или Linux: export OPENAI_API_KEY="your_openai_api_key"
• В Windows PowerShell: $env:OPENAI_API_KEY="your_openai_api_key"

Затем аутентифицируйте Modal локально:

modal setup

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

Когда всё будет настроено, вы увидите в терминале сообщение об успешной аутентификации в Modal.

2. Определение рабочего пространства песочницы

Далее создайте файл Python, например main.py, и добавьте необходимые импорты. Эти импорты подключают OpenAI Agents SDK, классы конфигурации песочницы и клиент песочницы Modal. 

import asyncio

from agents import ModelSettings, Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import File
from agents.extensions.sandbox import ModalSandboxClient, ModalSandboxClientOptions

Теперь нужно определить рабочее пространство песочницы. В этом примере оно включает небольшой проект триажа заявок в поддержку с README.md, файлом приложения и чек-листом релиза.

manifest = Manifest(
    entries={
        "README.md": File(
            content=(
                b"# Support Ticket Triage\n\n"
                b"Small service that labels customer tickets by urgency and team.\n"
            )
        ),
        "src/app.py": File(
            content=(
                b"def route_ticket(subject: str, customer_tier: str) -> dict:\n"
                b"    urgent = customer_tier == \"enterprise\" or \"outage\" in subject.lower()\n"
                b"    return {\n"
                b"        \"priority\": \"high\" if urgent else \"normal\",\n"
                b"        \"team\": \"support-ops\" if urgent else \"customer-care\",\n"
                b"    }\n"
            )
        ),
        "docs/release-checks.md": File(
            content=(
                b"# Release Checks\n\n"
                b"- Confirm routing rules match the current support escalation policy.\n"
            )
        ),
    }
)

Manifest сообщает агенту, какие файлы существуют внутри песочницы. Это даёт агенту реальную структуру проекта для изучения, редактирования и рассуждений, а не только текст из подсказки.

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

3. Создание агента для песочницы

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

agent = SandboxAgent(
    name="Modal Sandbox Assistant",
    model="gpt-5.4-mini",
    instructions=(
        "You are a coding assistant reviewing a small production service. "
        "Inspect the sandbox workspace before answering. "
        "Keep the answer short and practical."
    ),
    default_manifest=manifest,
    model_settings=ModelSettings(tool_choice="required"),
)

Здесь мы называем агента Modal Sandbox Assistant и используем модель gpt-5.4-mini для более быстрых ответов. Инструкции предписывают агенту изучить рабочее пространство песочницы перед ответом, что важно, когда ответ зависит от реальных файлов проекта.

Параметр default_manifest=manifest связывает агента с ранее созданным рабочим пространством. Настройка tool_choice="required" поощряет агента использовать доступные инструменты песочницы вместо ответов только по памяти или контексту подсказки.

4. Создание клиента песочницы Modal

Теперь создайте клиент песочницы Modal. Это соединение между рабочим процессом OpenAI Agents и песочницей Modal, где будет происходить реальная работа с файлами и командами.

client = ModalSandboxClient()
options = ModalSandboxClientOptions(
    app_name="openai-agents-modal-demo",
    workspace_persistence="tar",
)

ModalSandboxClient() указывает агенту использовать Modal в качестве провайдера песочницы. Это означает, что агент может работать в изолированной среде Modal вместо запуска напрямую на вашем локальном компьютере.

Параметры ModalSandboxClientOptions управляют конфигурацией песочницы Modal. Здесь app_name задаёт понятное имя приложению Modal, а workspace_persistence="tar" определяет, как Modal будет упаковывать и сохранять файлы рабочего пространства во время запуска.

5. Запуск сессии песочницы

Когда клиент и опции готовы, создайте песочницу из manifest и запустите сессию. 

sandbox = await client.create(
    manifest=manifest,
    options=options,
)

await sandbox.start()

Вызов client.create() создаёт новую песочницу Modal с файлами, определёнными в Manifest. То есть песочница стартует с той же структурой проекта, включая README.md, src/app.py и docs/release-checks.md.

Затем await sandbox.start() запускает сессию песочницы. На этом этапе у вас есть активное изолированное рабочее пространство на Modal, готовое для инспекции файлов агентом, запуска команд и работы с проектом.

6. Запуск агента в песочнице

Когда песочница активна, запустите агента, передав живую сессию песочницы через SandboxRunConfig. Это сообщает OpenAI Agents SDK, что во время выполнения агент должен использовать рабочее пространство песочницы Modal. 

result = await Runner.run(
    agent,
    (
        "Explain what this service does and name one production check "
        "before release. Keep it under 3 sentences."
    ),
    run_config=RunConfig(
        sandbox=SandboxRunConfig(session=sandbox),
        workflow_name="Modal sandbox example",
    ),
)

print(result.final_output)

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

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

7. Очистка песочницы

После завершения работы агента удалите песочницу, чтобы не оставлять неиспользуемые сессии в Modal.

await client.aclose(sandbox)

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

В реальном проекте следует поместить это в блок finally. Так очистка выполнится даже если вызов агента завершится с ошибкой или сценарий упадёт.

8. Полный пример кода

Ниже полный скрипт в одном месте. Он создаёт рабочее пространство, запускает песочницу Modal, выполняет в ней агента, печатает итоговый результат и затем очищает сессию песочницы. 

import asyncio

from agents import ModelSettings, Runner
from agents.extensions.sandbox import ModalSandboxClient, ModalSandboxClientOptions
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import File


async def main():
    manifest = Manifest(
        entries={
            "README.md": File(
                content=(
                    b"# Support Ticket Triage\n\n"
                    b"Small service that labels customer tickets by urgency and team.\n"
                )
            ),
            "src/app.py": File(
                content=(
                    b"def route_ticket(subject: str, customer_tier: str) -> dict:\n"
                    b"    urgent = customer_tier == \"enterprise\" or \"outage\" in subject.lower()\n"
                    b"    return {\n"
                    b"        \"priority\": \"high\" if urgent else \"normal\",\n"
                    b"        \"team\": \"support-ops\" if urgent else \"customer-care\",\n"
                    b"    }\n"
                )
            ),
            "docs/release-checks.md": File(
                content=(
                    b"# Release Checks\n\n"
                    b"- Confirm routing rules match the current support escalation policy.\n"
                )
            ),
        }
    )

    agent = SandboxAgent(
        name="Modal Sandbox Assistant",
        model="gpt-5.4-mini",
        instructions=(
            "You are a coding assistant reviewing a small production service. "
            "Inspect the sandbox workspace before answering. "
            "Keep the answer short and practical."
        ),
        default_manifest=manifest,
        model_settings=ModelSettings(tool_choice="required"),
    )

    client = ModalSandboxClient()
    options = ModalSandboxClientOptions(
        app_name="openai-agents-modal-demo",
        workspace_persistence="tar",
    )

    sandbox = await client.create(
        manifest=manifest,
        options=options,
    )

    await sandbox.start()

    try:
        result = await Runner.run(
            agent,
            (
                "Explain what this service does and name one production check "
                "before release. Keep it under 3 sentences."
            ),
            run_config=RunConfig(
                sandbox=SandboxRunConfig(session=sandbox),
                workflow_name="Modal sandbox example",
            ),
        )

        print(result.final_output)

    finally:
        await sandbox.aclose()

if __name__ == "__main__":
    asyncio.run(main())

Этот скрипт следует текущей структуре песочницы OpenAI и использует Modal как бэкенд выполнения. Логика агента остаётся в вашем приложении на Python, а фактическое рабочее пространство запускается внутри песочницы Modal.

Блок finally важен, потому что закрывает и удаляет песочницу, даже если выполнение агента завершилось неудачно. Это помогает держать вашу среду Modal в порядке и не оставлять неиспользуемые сессии.

9. Тестирование приложения локально

Когда скрипт готов, запустите его локально из терминала в той же папке, где сохранён main.py:

python main.py

Если всё настроено правильно, скрипт создаст песочницу Modal, загрузит в неё манифест, запустит агента OpenAI в рабочем пространстве, выведет ответ и затем очистит песочницу.

Вы должны увидеть примерно такой вывод:

This service triages customer support tickets by assigning urgency and routing them to the right team. One production check before release is to confirm the routing rules still match the current support escalation policy.

Запуск может занять несколько секунд. Пока он идёт, откройте панель управления Modal, нажмите на приложение openai-agents-modal-demo и проверьте логи. Это полезно, чтобы убедиться, что песочница создана, запущена, использована агентом и успешно очищена.

10. Создание интерактивного веб‑приложения 

Первый скрипт статичен: можно отправить один запрос, получить один ответ и остановиться. Чтобы упростить работу с проектом, можно превратить его в интерактивное веб‑приложение с помощью Gradio. Это позволит общаться с агентом в песочнице, задавать уточняющие вопросы, создавать или редактировать файлы и запускать тесты из простого интерфейса браузера.

Сначала установите последнюю версию Gradio:

pip install gradio

Затем создайте новый файл под названием app.py и скопируйте код приложения Gradio (OpenAI-Agents-in-Modal/app.py) в него. Это приложение использует ту же связку OpenAI Agents и песочницы Modal, но оборачивает её в чат-интерфейс. Код также при возможности переиспользует сессию песочницы, чтобы для каждого сообщения не создавать её с нуля.

Запустите приложение командой:

python app.py

В терминале появится локальный URL:

* Running on local URL:  http://127.0.0.1:7860
* To create a public link, set share=True in launch().

Откройте этот локальный адрес в браузере, чтобы воспользоваться чат‑приложением. Вы можете попросить агента изучить проект, объяснить, что делает сервис, создать вспомогательные файлы, отредактировать существующие или запустить тесты внутри песочницы Modal.

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

Затем я попросил агента создать новый вспомогательный файл для маршрутизации. Этот запрос занял немного больше времени, потому что агенту пришлось изменить рабочее пространство песочницы, добавить тесты и запустить тестовый набор.

Агент создал src/routing_rules.py, добавил новый файл тестов tests/test_routing_rules.py и проверил изменения с помощью pytest. Все 6 тестов прошли, что подтвердило корректную работу нового помощника и сохранность существующей логики маршрутизации заявок.

В целом это приложение на Gradio даёт простой фронтенд для работы с агентом OpenAI, запущенным на Modal. Пользователь отправляет сообщение через браузер, приложение передаёт его в SandboxAgent, агент работает внутри песочницы Modal, а итоговый ответ отображается в чат‑интерфейсе.

Заключение

OpenAI Agents с песочницами Modal позволяет аккуратно строить агентные приложения, которые работают с реальными файлами, выполняют команды и возвращают полезные результаты из изолированной среды. 

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

Тем не менее, создание интерактивного приложения и настройка модели потребовали больше усилий, чем ожидалось. Шаги по созданию файлов и тестированию также занимали больше времени, поскольку песочница Modal иногда уходила в таймаут. Мне пришлось увеличить таймаут песочницы с 300 секунд до 600 секунд, чтобы у агента было достаточно времени завершить полный сценарий.

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

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

В целом это сильный рабочий процесс для создания агентных приложений в песочнице, особенно если вашему агенту нужно работать с файлами, кодом и сгенерированными результатами. Полный проект доступен на GitHub — клонируйте его локально и запустите сами: kingabzpro/OpenAI-Agents-in-Modal.

Если вы хотите глубже разобраться в создании продвинутых ИИ-систем, рекомендуем наш курс Building Scalable Agentic Systems.