OpenAI Agents API: Запуск Codex-агентов через один вызов

OpenAI официально запустила Agents API в публичную бета-версию. Это решение предоставляет разработчикам доступ к той же самой инфраструктуре и «арматуре» (harness), что и у сервиса Codex, но через стандартизированный API. Ключевое отличие от предыдущих подходов — управление долгоживущими сессиями, контекстом и под-агентами теперь берёт на себя OpenAI, а не разработчик.

01Архитектура: 4 ключевых понятия

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

• Agent (Агент): Конфигурация, включающая модель, системные инструкции, доступные инструменты (tools) и серверы MCP.
• Environment (Окружение): Опциональный «песочница» (sandbox), где агент получает доступ к файлам, загружает навыки и выполняет команды.
• Session (Сессия): Долговременный экземпляр агента, который сохраняет состояние, историю и продолжает работу над задачей.
• Events and Items: Входящие входные данные и выходные результаты, генерируемые агентом.

Работа сессии состоит из четырёх шагов: создание, постановка задачи, отслеживание прогресса (через стриминг или вебхуки) и продолжение работы или управление текущим ходом.

02Где запускается агент: выбор окружения

Это главное архитектурное решение при использовании Agents API. Поддерживается три варианта размещения:

1. OpenAI-hosted sandbox: Управляемая песочница на инфраструктуре OpenAI. Позволяет настраивать файлы, пакеты, навыки и плагины. Данные остаются только в США.
2. Self-hosted (Собственный хостинг): Вы запускаете codex exec-server в своей среде. Сервер регистрируется с ограниченным ключом и подключается к OpenAI через WebSocket. Все соединения инициируются исходящими от вашего сервера.
3. Partner sandboxes: Официальная интеграция с провайдерами: Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop и Vercel.

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

03Что делает «арматура» (Harness) автоматически

OpenAI берёт на себя сложную логику, которую ранее приходилось реализовывать самостоятельно:

• Автоматическая компиляция контекста: Когда сессия приближается к лимиту токенов, API автоматически сжимает ранние части диалога. Разработчику не нужно писать свою логику компрессии.
• Эффективное использование инструментов: Реализован Tool Search — определения инструментов загружаются только при необходимости. Это снижает расход токенов и сохраняет кэш модели. Поддерживается параллельный вызов инструментов и цепочки операций.
• Многоагентность (Subagents): Основной агент может разбивать сложные задачи на независимые подзадачи. Каждый подагент имеет свой собственный контекст. Главный агент координирует их и объединяет результаты.

04Пример кода: Запуск агента-расследователя

Ниже приведён пример инициализации агента для расследования инцидентов (investigation agent). Обратите внимание на использование MCP-серверов и параметра multi_agent.

Эта команда создаёт сессию, назначает модель gpt-6-astra, подключает MCP-сервер для мониторинга и запускает параллельный анализ.

import OpenAI

client = OpenAI()

session = await client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "tools": [
            {
                "type": "mcp",
                "server_label": "observability",
                "transport": {
                    "type": "http",
                    "server_url": "https://observability.example.com/mcp"
                }
            }
        ],
        "multi_agent": {
            "enabled": True
        },
        "vault_ids": ["vault_YOUR_VAULT_ID"]
    },
    environment={
        "type": "openai_hosted",
        "capability_directories": ["/workspace/capabilities/skills"]
    },
    input=[
        "Investigate service-api's elevated 5xx rate over the last 30 minutes.",
        "Delegate deployment, error, and dependency analysis to subagents.",
        "Save findings, evidence, and recommended mitigation in /workspace/outputs."
    ]
)

05Сравнение: Agents API vs Agents SDK vs Responses API

OpenAI позиционирует три своих инструмента для работы с агентами следующим образом: