Agents API или Codex: как выбрать способ автоматизации

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

Материал основан на официальной документации, проверенной 15 сентября 2026 года. Сценарии ниже — примеры проектирования; сравнительных запусков и измерений производительности здесь нет.

Содержание

1. Общая картина: что именно вы выбираете.
2. Чеклист быстрой проверки.
3. Матрица вариантов.
4. Полезные сценарии: расписание, редакция, проект пользователя.
5. Как обеспечить обязательный порядок действий.
6. Шаблон решения и проверка выбора.

Общая картина: что именно вы выбираете

Название «Agents API или Codex» обозначает несколько способов подключения агента. В самом Agents API работу Codex организует сервис OpenAI. При выборе нужно разделить три вопроса: кто ведёт агентный цикл, где исполняются инструменты и что остаётся ответственностью приложения.

В Agents API OpenAI управляет harness. Можно обойтись без среды исполнения, использовать песочницу OpenAI или подключить собственную. Собственная среда переносит исполнение команд на вашу инфраструктуру; harness остаётся у OpenAI. Функции приложения исполняет ваш обработчик. Архитектура Agents API.

Удобно начать с такой схемы ответственности:

Пользователь или расписание
          ↓
Приложение: задача, права, обязательные этапы, сохранённые результаты
          ↓
Управление агентом: сервис OpenAI или процесс под вашим управлением
          ↓
Инструменты: функции приложения, внешние сервисы, среда исполнения
          ↓
Проверка результата → принятие → разрешённое действие

Responses API даёт доступ к ответам модели и инструментам. Agents SDK организует агентный цикл внутри вашего приложения. Agents API предоставляет управляемый Codex и сохраняемые сессии. Эти варианты допускают разный объём управления со стороны приложения. Сравнение агентных вариантов OpenAI.

Для программной работы с процессом Codex есть codex exec, Codex SDK и app-server. Они тоже пересекаются: например, Python-версия Codex SDK управляет локальным app-server через JSON-RPC. Поэтому SDK и app-server нельзя считать полностью независимыми движками. Codex SDK.

Чеклист быстрой проверки

Перед сравнением ответьте на 12 вопросов. Если ответа нет, запишите ограничение как неизвестное.

1. Задача: какое действие вы автоматизируете и какой конкретный результат ожидаете?
2. Запуск: работа начинается по расписанию, событию или запросу человека?
3. Владелец процесса: кто будет запускать, обновлять и восстанавливать агентную часть?
4. Ресурсы: достаточно переданных данных и API или нужны файлы, программы и приватная сеть?
5. Интерфейс: нужен итоговый документ или диалог с ходом работы и подтверждениями?
6. Продолжение: какие данные должны сохраниться после перезапуска приложения?
7. Порядок: какие этапы обязательны независимо от решений модели?
8. Доступ: как приложение установит, какие данные разрешены конкретному пользователю?
9. Изоляция: какие задачи нельзя запускать с общими файлами и полномочиями?
10. Инструменты: кто исполняет каждый вызов и что произойдёт при его повторе?
11. Остановка: как прервать работу и выяснить, какие действия уже выполнены?
12. Приёмка: каким способом вы проверите результат, кроме чтения ответа агента?

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

Матрица вариантов

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

Техническая опора таблицы: Responses API, Agents SDK, Agents API, неинтерактивный Codex, Codex SDK, app-server.

Уточните три различия перед окончательным выбором.

Продолжение работы доступно несколькими путями. codex exec поддерживает возобновление задачи, SDK — продолжение и восстановление thread. У Responses API есть механизмы работы с состоянием беседы. Само требование «помнить предыдущий шаг» ещё не определяет победителя. Сравнивайте место хранения, восстановление после сбоя и связь истории с данными продукта. Неинтерактивный режим, варианты хранения состояния.

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

Возможность интеграции и готовность транспорта к эксплуатации различаются. OpenAI описывает app-server как интерфейс для собственных клиентов, но прямой WebSocket-транспорт отмечен как экспериментальный и неподдерживаемый для production. Это нужно учитывать при проектировании удалённого подключения и проверять заново перед выпуском. Документация app-server.

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

Ограниченная операция по расписанию

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

Если задача требует чтения репозитория и команд его анализа, разумный первый кандидат — codex exec. Расписание запускает отдельный процесс, передаёт конкретную задачу и сохраняет результат. Для обработки событий есть JSONL, для структурированного ответа — JSON Schema. Документация режима.

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

Если исходный текст уже извлечён и модели нужно только классифицировать его, начните сравнение с Responses API. Запуск полноценной работы Codex с репозиторием в таком сценарии может быть лишним. Для подключения модели есть отдельное руководство по Responses API.

Когда вокруг процесса появляется существенная прикладная логика, рассмотрите Codex SDK. Когда нужен интерактивный пользовательский сценарий с продолжением работы, вернитесь к требованиям к состоянию и интерфейсу. Само расписание не требует Agents API. Подробности запуска через терминал разобраны в руководстве по codex exec.

Собственная редакция с ходом работы в интерфейсе

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

В проекте редакции pimenov.ai на app-server уже описана архитектура собственного агентного приложения. Появление Agents API даёт дополнительный вариант для сравнения. Само по себе оно не доказывает необходимость переноса проекта.

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

Вариант с Agents API особенно интересен, если вы хотите передать управление harness сервису OpenAI. При этом обработчики функций CMS остаются вашей частью приложения: подключение среды не запускает их автоматически. Функции Agents API.

Вариант с app-server стоит изучать, если нужен глубокий клиент Codex и вы готовы обслуживать его процесс и протокол. Ограничения выбранного транспорта входят в решение. Продолжение доступно в руководстве по app-server.

Результат эксперимента — черновик, который восстановился после перезапуска интерфейса, и журнал действий с CMS. Отдельно проверьте повторную доставку запроса на запись: она не должна создавать второй материал.

Пользователь возвращается к своему проекту

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

Agents API позволяет сохранять идентификатор сессии в хранилище приложения и получать её текущее состояние. Это полезная основа для продолжения. Управление сессиями.

Для продукта добавьте явную модель данных:

Пользователь → права на проект
Проект → документы, версии, принятые решения
Задача проекта → сессия агента или другая история выполнения
Результат задачи → версия документа, проверка, статус принятия

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

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

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

Как обеспечить обязательный порядок действий

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

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

Распределяйте ответственность по характеру решения:

Здесь часто подходит сочетание обычного кода и агентных шагов. Код проводит материал через обязательные состояния, агент выполняет работу внутри разрешённого этапа. Agents SDK предоставляет средства организации агентного цикла, но расположение проверок и правил доступа всё равно нужно спроектировать. Agents SDK.

Шаблон решения и проверка выбора

Скопируйте карточку и заполните её для одной операции. Пример ниже относится к ночному анализу репозитория; это проект эксперимента, а не отчёт о работающей системе.

task: "Подготовить отчёт об изменениях между двумя ревизиями"
input: "Репозиторий и два точных идентификатора ревизий"
result: "Структурированный отчёт с компонентами и ссылками на файлы"

constraints:
  trigger: "Расписание на существующем сервере"
  access: "Чтение репозитория; запись отчёта выполняет обвязка"
  interaction: "Без диалога во время запуска"
  state: "Отдельная задача на каждый диапазон ревизий"

choice: "codex exec"
reason: "Ограниченная работа с репозиторием в существующем скрипте"
application_owns:
  - "Запуск, ограничение времени и остановку процесса"
  - "Фиксацию входных ревизий и результата запуска"
  - "Проверку структуры и содержимого отчёта"
  - "Защиту от повторной обработки того же диапазона"

experiment:
  normal: "Сравнить отчёт с заранее известными изменениями"
  failure: "Проверить обработку недоступного входного файла"
  repeat: "Повторить ту же задачу без дублирования принятого результата"

reconsider_when: "Появятся диалог, подтверждения или сложное продолжение"

Это форма для принятия решения, а не конфигурация Codex: поля не нужно передавать SDK или CLI.

Выбор готов к эксперименту, когда другой человек может объяснить его по карточке, назвать главную альтернативу и показать условие пересмотра. Техническая проверка должна включать обычное выполнение и хотя бы один значимый сбой. Для операций записи добавьте повторную доставку; для продолжаемых задач — перезапуск и восстановление.

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

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

Codex App — единый справочник по среде от OpenAI: выберите подходящее руководство по инструментам и рабочим процессам Codex для вашей карточки решения.

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

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

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

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