OpenAI Agents API: как устроены агенты, сессии и инструменты

OpenAI Agents API позволяет встроить в приложение агента, который выполняет задачу в несколько шагов и продолжает работу в сохранённой сессии. Руководство поможет разобраться в его устройстве и подготовить первый проверочный запуск.

Содержание

1. Что получает приложение — назначение API и основные понятия.
2. Где выполняется работа — три варианта среды.
3. Что сохраняет сессия — история, контекст и данные проекта.
4. Как подключаются инструменты — функции, MCP и плагины.
5. Как работают субагенты — делегирование и общие ресурсы.
6. Подключение и первый запуск — пример на Python.
7. Проверка результата — события, ошибки и восстановление.
8. Полезные сценарии — сравнение документов и проверка проекта.
9. Что остаётся за приложением — границы готового решения.

Что получает приложение

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

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

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

Где выполняется работа

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

В размещённой у OpenAI среде можно задать исходные файлы, пакеты и сетевой доступ. Детали подключения перечислены в документации OpenAI-hosted.

Для собственной среды используется исполнитель codex exec-server. Он запускается у вас и по исходящему соединению получает команды управляемого агента. Подготовка компьютера, его доступность и сохранение нужных файлов остаются вашей задачей. Подключение self-hosted.

Что сохраняет сессия

Идентификатор сессии позволяет вернуться к начатой работе. Приложение сохраняет его у себя, получает текущее состояние и продолжает взаимодействие. Например, после первого отчёта пользователь просит проверить ещё один документ в рамках той же задачи. Управление сессиями.

Здесь полезно разделить три слоя:

• История сессии: сообщения, обращения к инструментам и результаты работы.
• Контекст модели: информация, которую модель использует на очередном шаге. Agents API поддерживает сжатие предыдущей работы для управления объёмом контекста.
• Данные проекта: исходные документы, утверждённые решения и правила доступа, которые нужны самому продукту.

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

Например, в приложении можно хранить связь «пользователь → проект → сессии», а принятые решения записывать в карточку проекта. При следующем обращении приложение передаст агенту актуальную версию этой карточки. Это вариант проектирования, который нужно реализовать самостоятельно. Подробнее о таком разделении — в руководстве по контекст-инжинирингу.

Как подключаются инструменты

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

Функции приложения

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

Подключённая среда сама по себе не начинает исполнять такие функции. Нужен обработчик в вашем приложении. Ожидающие вызовы отражаются в required_actions; результат возвращается с идентификаторами turn_id и call_id. Функции в Agents API.

MCP-серверы

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

Навыки и плагины

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

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

Как работают субагенты

Главный агент может делегировать независимые части задачи помощникам. Для этого при создании сессии включается multi_agent.enabled. У каждого субагента собственный контекст; основной агент координирует работу и собирает результат.

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

Поэтому роль «проверяющий» сама по себе не делает помощника технически ограниченным чтением. Разделение полномочий надо обеспечивать устройством инструментов и среды. Для постановки независимых задач пригодятся четыре принципа делегирования субагентам.

Подключение и первый запуск

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

Понадобятся Python, доступ к Agents API в проекте OpenAI Platform и API-ключ приложения. По официальной инструкции ключу нужны разрешения api.agents.read, api.agents.write и api.responses.write. Получить ключ можно в OpenAI Platform. Доступ конкретного аккаунта здесь не проверялся.

Создайте отдельную папку и установите SDK в виртуальное окружение:

mkdir agents-api-check
cd agents-api-check
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade openai

Сохраните файл check_agent.py:

from getpass import getpass
from openai import OpenAI

# Ключ вводится скрыто и остаётся в клиентском приложении.
api_key = getpass("API-ключ OpenAI: ")

with OpenAI(api_key=api_key) as client:
    with client.beta.agents.sessions.create(
        agent={
            # Модель из официального quickstart на дату проверки.
            "model": "gpt-6-astra",
            "instructions": (
                "Выполняй задания на тестовых данных. "
                "Показывай фактический вывод запущенных команд. "
                "Если команда завершилась ошибкой, сообщи об этом."
            ),
        },
        environment={"type": "openai_hosted"},
        input=(
            "Создай файл check.py. Скрипт должен вычислить сумму "
            "чисел 12, 18 и 30 и вывести одну строку: total=60. "
            "Запусти скрипт командой python check.py. "
            "Затем отдельной командой прочитай созданный файл "
            "и покажи его содержимое. Не используй сеть."
        ),
        stream=True,
    ) as events:
        for event in events:
            print(event.to_json(indent=None), flush=True)

Запустите:

python check_agent.py

Пример адаптирован из официального quickstart. SDK использует пространство имён beta.agents и добавляет заголовок OpenAI-Beta: agents=v1 автоматически. При прямом HTTP-вызове этот заголовок нужен явно; создание сессии выполняется через POST https://api.openai.com/v1/agents/sessions.

Клиентский check_agent.py работает на вашем компьютере. Создаваемый агентом check.py находится в среде OpenAI. Файла в вашей локальной папке после этого ожидать не нужно.

Проверка результата

В терминале появятся события в JSON. Для этой проверки ищите три подтверждения:

1. Пришло событие agent.session.turn.completed.
2. В результатах выполнения команды есть строка total=60.
3. Чтение созданного файла показывает вычисление суммы заданных чисел, а не только печать заранее записанного ответа.

Этого достаточно для узкой проверки цепочки «создать файл → выполнить → прочитать». Это ещё не проверка надёжности приложения или качества сложных задач.

События показывают происходящее сейчас. Сохранённые записи позволяют восстановить картину после разрыва соединения; поток не воспроизводит все пропущенные события. В приложении сохраняйте session_id и обрабатывайте восстановление отдельно. События и история выполнения.

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

Полезные сценарии

Следующие примеры — варианты проектирования первого эксперимента. Их качество необходимо проверить на ваших данных.

Сравнить две версии документа

Задача: понять, что изменилось в требованиях к проекту.

Исходные данные: две версии одного документа с номерами разделов. Для первого опыта выберите короткие тексты и заранее внесите несколько известных изменений.

Действие: передайте тексты в сессию без среды (none). Попросите составить таблицу: раздел, прежняя формулировка, новая формулировка, следствие изменения. Запретите заполнять отсутствующие сведения догадками.

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

Ограничение: такой опыт проверяет сравнение предоставленного текста. Он не проверяет распознавание PDF, доступ к хранилищу или способность обработать документы произвольного объёма.

Проверить согласованность документов проекта

Задача: найти расхождения между утверждёнными требованиями и текущим описанием реализации.

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

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

Проверяемый результат: для каждого требования указан один из выводов: «подтверждено», «обнаружено расхождение», «недостаточно данных». Человек проверяет выводы по исходникам.

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

Что остаётся за приложением

Чтобы превратить проверочный запуск в полезный продукт, определите:

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

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

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

Официальные ресурсы

• OpenAI Platform — проект приложения и управление доступом.
• Документация Agents API — актуальные возможности и примеры.
• Состояние сервисов OpenAI — проверка известных сбоев.
• Сообщество разработчиков OpenAI — обсуждения; технические решения из них нужно сверять с документацией.

Следующий шаг

Опишите, какие документы, решения и ограничения должен получать агент в вашем проекте. В этом поможет руководство по контекст-инжинирингу.

Связанные материалы

• Статья: Редакция pimenov.ai на Codex app-server: архитектура собственного агентного приложения.
• Блог: Agent Plugins: переносимые компетенции для ИИ-агентов.
• База знаний: Codex App — единый справочник по среде от OpenAI.

Если вы планируете встроить агента в собственный продукт, полезно заранее разобрать доступные ему данные и границы самостоятельных действий.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov