Миграция с OpenAI Agents SDK на Agents API: что на самом деле меняется архитектурно?

Переход с OpenAI Agents SDK на Agents API — это не просто переименование импорта. Меняется ключевая архитектурная граница: SDK выполняет цикл агента внутри вашего приложения, тогда как Agents API запускает управляемый Codex-каркас и долговременную сессию на стороне OpenAI. Поэтому вопрос миграции не в том, «какие классы соответствуют каким эндпоинтам?», а в том, «какие обязанности среды выполнения переходят через границу, какие остаются в нашем приложении и какие нужно перепроектировать?»

Миграция — это переход от цикла, принадлежащего приложению, к управляемому каркасу

В Agents SDK один запуск — это ход на уровне приложения. Исполнитель SDK вызывает модель, проверяет вывод, выполняет инструменты, следует передачам управления и продолжает, пока не достигнет точки остановки. Ваш процесс размещает этот цикл и, следовательно, владеет его жизненным циклом.

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

Этот сдвиг владения и есть миграция. Всё остальное — синтаксис API, схемы инструментов, обработка событий, идентификаторы сессий — следует из него.

Карта миграции границ среды выполнения

Что может мигрировать концептуально без изменения владения

Несколько концепций приложения без проблем переживают миграцию, хотя их представление меняется. Модели, инструкции, определения функций в формате JSON-схемы, доступ к MCP, описания инструментов и требования к структурированному выводу по-прежнему относятся к конфигурации агента.

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

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

Опасный шаблон миграции — воссоздать каждую абстракцию среды выполнения SDK внутри Agents API. Это может привести к тому, что вы будете платить за управляемый каркас, но при этом всё ещё будете эксплуатировать теневой каркас в своём приложении.

Шаг 1 — Отделите состояние домена от состояния сессии агента

Прежде чем трогать вызовы API, классифицируйте состояние, которое в настоящее время несёт ваше SDK-приложение. Часть состояния существует только для того, чтобы поддерживать движение диалога агента. Другое состояние — это бизнес-истина: права пользователя, статус проекта, данные заказа, утверждение рабочего процесса, записи клиентов, версии документов, состояние политики или конфигурация приложения.

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

Шаг 2 — Преобразуйте мышление раннера в мышление сессии и событий

SDK-приложения часто мыслят в терминах вызова run и получения результата. Agents API мыслит в терминах долговечной сессии, ходы которой могут выполняться асинхронно. Сообщение в бездействующую сессию запускает работу; сообщение во время активного хода может его направить. Прогресс поступает через потоковую передачу или вебхуки.

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

Шаг 3 — Перепроектируйте функциональные инструменты вокруг требуемых действий

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

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

Шаг 4 — Решите, где должно происходить выполнение

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

Это создаёт решение о миграции, которое SDK-приложения, возможно, никогда не принимали явно: какой код должен выполняться как функция приложения, какой код принадлежит песочнице и какие рабочие нагрузки требуют инфраструктуры, которую вы контролируете?

Шаг 5 — Замените неявное восстановление явной обработкой жизненного цикла

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

Поэтому миграция нуждается в двух моделях восстановления: восстановление среды выполнения агента и восстановление бизнес-операций. Первое всё больше управляется Agents API. Второе остаётся вашей ответственностью.

Шаг 6 — Перестройте наблюдаемость вокруг новой границы трассировки

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

Не отказывайтесь от наблюдаемости вашего приложения только потому, что трассировки платформы улучшились. Журналы продукта по-прежнему должны связывать сессию агента с идентичностью пользователя, решением об авторизации, доменным объектом, побочным эффектом инструмента, записью об утверждении и окончательным принятым результатом. Полезная производственная трассировка — это соединение свидетельств среды выполнения агента и свидетельств бизнес-среды выполнения.

Шаг 7 — Сохраните оценки до изменения среды выполнения

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

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

Тест доказательства миграции

Что измерять во время миграции

Когда ещё не стоит мигрировать

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

• Требуемая возможность SDK ещё недоступна в Agents API.
• Миграция нарушит критический производственный период, не принося ближайшей пользы.
• Приложение зависит от пользовательской семантики оркестрации, которая не была проверена на управляемом каркасе.
• Переносимость между провайдерами является жёстким требованием, и текущая абстракция SDK существенно ценна.
• Ваша команда ещё не отделила бизнес-состояние от состояния среды выполнения агента, что делает переключение небезопасным.
• Поведение нового Agents API не было протестировано на репрезентативных производственных нагрузках.

Когда миграция становится стратегически важной

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

Самый сильный сигнал — не «старый SDK функционально завершён». Это «наша дорожная карта теперь зависит от возможностей, естественным домом которых является управляемая среда выполнения Agents API».

Что изменило бы этот ответ?

Стратегия миграции изменится, если OpenAI опубликует инструменты автоматизированной миграции, представит явные слои совместимости, изменит семантику сессий Agents API, расширит или сузит поддержку сред с самостоятельным размещением или изменит политику поддержки Agents SDK.

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

Ограничения

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

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

Заключение

Миграцию с Agents SDK на Agents API лучше всего понимать как перемещение границы среды выполнения агента. Управляемая среда выполнения берёт на себя большую часть цикла, непрерывности сессии, сжатия и восстановления. Ваше приложение должно стать более явным в отношении обязанностей, которые остаются за вами: доменная истина, авторизация, побочные эффекты функций, артефакты, аудируемость и жизненный цикл продукта.

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

Часто задаваемые вопросы

Глоссарий

Первоисточники и дополнительное чтение

Переход с OpenAI Agents SDK на Agents API — это не просто переименование импорта. Меняется ключевая архитектурная граница: SDK выполняет цикл агента внутри вашего приложения, тогда как Agents API запускает управляемый харнесс Codex и долговременную сессию на стороне OpenAI. Поэтому вопрос миграции не в том, «какие классы соответствуют каким эндпоинтам?», а в том, «какие обязанности среды выполнения перемещаются через границу, какие остаются в нашем приложении и какие нужно перепроектировать?»

Миграция — от цикла, принадлежащего приложению, к управляемому харнессу

В Agents SDK один запуск — это ход на уровне приложения. Раннер SDK вызывает модель, проверяет вывод, выполняет инструменты, следует передачам и продолжает, пока не достигнет точки остановки. Ваш процесс размещает этот цикл и, следовательно, владеет его жизненным циклом.

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

Этот сдвиг владения и есть миграция. Всё остальное — синтаксис API, схемы инструментов, обработка событий, идентификаторы сессий — следует из него.

Карта миграции границ среды выполнения

Что может мигрировать концептуально без изменения владения

Несколько концепций приложения без проблем переживают миграцию, хотя их представление меняется. Модели, инструкции, определения функций в формате JSON-схемы, доступ к MCP, описания инструментов и требования к структурированному выводу по-прежнему относятся к конфигурации агента.

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

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

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

Шаг 1 — Отделите доменное состояние от состояния сессии агента

Прежде чем трогать вызовы API, классифицируйте состояние, которое в настоящее время несёт ваше приложение на SDK. Часть состояния существует только для того, чтобы поддерживать движение разговора агента. Другое состояние — это бизнес-истина: права пользователя, статус проекта, данные заказа, утверждение рабочего процесса, записи клиентов, версии документов, состояние политики или конфигурация приложения.

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

Шаг 2 — Преобразуйте мышление раннера в мышление сессий и событий

Приложения на SDK часто мыслят в терминах вызова run и получения результата. Agents API мыслит в терминах долговечной сессии, ходы которой могут выполняться асинхронно. Сообщение в бездействующую сессию запускает работу; сообщение во время активного хода может его направлять. Прогресс поступает через потоковую передачу или вебхуки.

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

Шаг 3 — Перепроектируйте функциональные инструменты вокруг требуемых действий

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

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

Шаг 4 — Решите, где должно происходить выполнение

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

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

Шаг 5 — Замените неявное восстановление явной обработкой жизненного цикла

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

Поэтому миграция требует двух моделей восстановления: восстановление среды выполнения агента и восстановление бизнес-операций. Первое всё больше управляется Agents API. Второе остаётся вашей ответственностью.

Шаг 6 — Перестройте наблюдаемость вокруг новой границы трассировки

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

Не отказывайтесь от наблюдаемости вашего приложения только потому, что трассировки платформы улучшились. Журналы продукта по-прежнему должны связывать сессию агента с идентификацией пользователя, решением об авторизации, доменным объектом, побочным эффектом инструмента, записью об одобрении и окончательным принятым результатом. Полезная производственная трассировка — это соединение доказательств среды выполнения агента и доказательств бизнес-среды выполнения.

Шаг 7 — Сохраните оценки перед изменением среды выполнения

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

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

Тест доказательства миграции

Что измерять во время миграции

Когда ещё не стоит мигрировать

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

• Требуемая возможность SDK ещё недоступна в Agents API.
• Миграция нарушит критический производственный период, не принося ближайшей пользы.
• Приложение зависит от пользовательской семантики оркестрации, которая не была проверена на управляемой среде.
• Переносимость между поставщиками является жёстким требованием, и текущая абстракция SDK существенно ценна.
• Ваша команда ещё не отделила бизнес-состояние от состояния среды выполнения агента, что делает переключение небезопасным.
• Поведение нового Agents API не было протестировано на репрезентативных производственных нагрузках.

Когда миграция становится стратегически важной

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

Самый сильный сигнал — не «старый SDK функционально завершён». Это «наш план развития теперь зависит от возможностей, естественным домом для которых является управляемая среда выполнения Agents API».

Что могло бы изменить этот ответ?

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

Она также изменилась бы, если бы изменились требования вашего продукта. Простому ассистенту запрос-ответ может вообще не понадобиться долговременная управляемая среда выполнения. Долго работающий агент для программирования, исследований или операций может получить гораздо больше пользы от модели владения Agents API.

Ограничения

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

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

Заключение

Миграцию с Agents SDK на Agents API лучше всего понимать как перемещение границы среды выполнения агента. Управляемая среда выполнения берёт на себя большую часть цикла, непрерывности сессии, сжатия и восстановления. Ваше приложение должно стать более явным в отношении обязанностей, которые остаются за ним: доменная истина, авторизация, побочные эффекты функций, артефакты, аудируемость и жизненный цикл продукта.

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

Часто задаваемые вопросы

Глоссарий

Первоисточники и дополнительное чтение