OpenAI Responses API чи Chat Completions: вибір і безпечна міграція

OpenAI рекомендує Responses API для нових проєктів, а Chat Completions продовжує підтримувати. Це не означає, що кожен стабільний endpoint треба терміново переписати. Якщо застосунок надсилає масив messages, отримує текст або власні function calls і вже має перевірений state, retry та observability layer, міграція повинна мати вимірювану причину, а не лише нову назву endpoint.

Responses є природнішим вибором, коли потрібні OpenAI-hosted tools, item-based output, зв’язування відповідей між turns, background execution або складні reasoning/tool loops. Головна архітектурна відмінність — не якість одного prompt, а те, хто володіє conversation state, tool lifecycle і протоколом подій. Бізнес-авторизація, idempotency та перевірка side effects в обох випадках залишаються відповідальністю застосунку.

Залишайте Chat Completions для зрілої текстової або structured-output інтеграції, якщо вона має низьку змінність, власний conversation store і не потребує Responses-only capability. Це мінімізує regression surface. Для нового agentic сервісу починайте з Responses: офіційний migration guide називає його рекомендованим API для нових проєктів і описує built-in web search, file search, computer use, code interpreter та remote MCP.

Не вибирайте endpoint за абстрактною обіцянкою «агентності». Спочатку зафіксуйте task contract: input, дозволені tools, state owner, latency budget, retention policy, очікуваний output і terminal outcome. Потім зіставте контракт із capability matrix. Якщо достатньо одного model call і локальних functions, обидва API можуть бути технічно придатними; перемогу визначає нижча повна складність експлуатації.

• Новий workflow із built-in tools або multi-step reasoning → Responses API.
• Стабільний text/JSON endpoint без нових capabilities → Chat Completions може залишатися.
• Власний provider-neutral gateway → підтримайте окремі adapters і явну capability matrix.
• Long-running task → оцініть Responses background mode, webhook/polling і recovery contract.
• Consequential tool action → endpoint не замінює application policy, approval та reconciliation.

Chat Completions повертає choices із message, тоді як Responses використовує item-based output: одна відповідь може містити message, tool call, reasoning-related або інші typed items. SDK helper output_text зручний для простого UI, але production adapter не повинен зводити весь output до рядка. Інакше він загубить tool calls, статуси, annotations та причини incomplete response.

Внутрішній контракт краще будувати як потік типізованих ModelEvent: text delta, output item added/completed, tool call requested, usage, refusal, incomplete і terminal state. Provider adapter перекладає Chat Completions chunks або Responses semantic events у цей контракт. Бізнес-код тоді не читає сирі payloads, а міграція endpoint не поширюється на кожен feature module.

У Chat Completions клієнт зазвичай повторно передає потрібну історію messages. У Responses можна передати previous_response_id або працювати з conversation primitives, але зручність state chaining не звільняє команду від data governance. Потрібно визначити, які дані дозволено зберігати в провайдера, який retention прийнятний, як виконуються deletion і subject requests та чи сумісна конфігурація з Zero Data Retention.

Не використовуйте server-side state як єдине джерело істини для бізнес-процесу. Authoritative workflow state — order status, approval, виконаний платіж або release decision — належить domain system. Model conversation зберігає лише контекст reasoning і посилання на перевірені артефакти. Для stateless або суворо контрольованих workloads явно передавайте потрібний context і тестуйте поведінку параметра store та організаційної data policy.

Responses спрощує доступ до built-in tools і може поєднувати кілька tool/model turns. Це зменшує orchestration code, але розширює failure surface: недовірений web result, prompt injection у файлі, помилковий computer action, timeout після side effect або надто широкий remote MCP server. Function calling у Chat Completions має ті самі базові ризики для application-owned tools.

Перед кожною зовнішньою дією application policy plane перевіряє authenticated identity, tenant, resource, action, risk tier і поточний стан. Mutating operation має idempotency key, bounded retry та authoritative postcondition. High-impact дія потребує окремого approval. Tool description допомагає моделі обрати виклик, але не може видавати scopes або скасовувати правила, навіть якщо його повернув hosted tool чи довірений MCP connector.

Механічна заміна create call часто ламається не на фінальному тексті, а на streaming parser. Responses має semantic event types і item lifecycle; клієнт повинен обробляти відомі terminal states, error/incomplete paths та нові event types без мовчазного зависання. UI не оголошує задачу завершеною після останньої text delta, якщо tool loop або background response ще не досяг terminal outcome.

Trace фіксує internal correlation ID, provider response ID, endpoint/adapter version, model snapshot, input fingerprint, output items, tool attempts, usage, latency, terminal status і verified business outcome. Сирі prompts та tool results редагуються за privacy policy. Dashboard порівнює не лише HTTP success, а task success, schema validity, tool-call accuracy, duplicate-action rate, p95 time-to-verified-outcome і cost per accepted task.

Почніть з inventory: prompts, system/developer instructions, message roles, structured outputs, tools, streaming events, storage assumptions, retries та telemetry. Створіть Responses adapter за тим самим внутрішнім ModelRequest/ModelEvent контрактом. Не додавайте одночасно web search, нову модель і нову memory policy — інакше regression не матиме одного пояснення.

Проганяйте historical corpus через старий і новий adapters у shadow mode. Для детермінованих полів перевіряйте exact/schema parity; для відкритого тексту — task rubric, factual support і human review на ризиковій вибірці. Окремо тестуйте refusal, malformed tool arguments, partial stream, timeout after commit, previous response unavailable, retention constraint і prompt injection у tool output. Canary отримує малу частку трафіку лише після offline gate.

Promotion відбувається, коли новий adapter не погіршує critical slices, observability повна, unit economics прийнятні, а on-call має runbook. Rollback перемикає feature flag на Chat Completions adapter і коректно завершує або ізолює in-flight Responses runs. Provider response IDs зберігаються в trace, але domain state не залежить від них, тому повернення endpoint не відкатує вже підтверджені зовнішні дії.

• Inventory → payloads, tools, state, streaming, errors і retention.
• Adapter → один внутрішній контракт для двох endpoints.
• Replay → parity та risk-sliced evals на зафіксованому corpus.
• Canary → task success, p95, cost і high-severity failures.
• Rollback → endpoint flag без повторення підтверджених side effects.

Responses дає кілька способів продовжити довгу взаємодію: передати previous_response_id, прив’язати response до conversation або керувати input items у власному сховищі. Додатково OpenAI документує compaction для довгих tool-heavy workflows. Але жоден із цих механізмів не визначає, які бізнес-факти є чинними. Conversation continuity допомагає моделі продовжити reasoning; customer profile, approval, inventory або ticket status усе одно читаються з authoritative domain system на момент дії.

Введіть окремий ContextLifecycle contract: mode of continuation, owner of raw history, compaction trigger, maximum context budget, retention class, deletion path і recovery behavior. Compacted item слід вважати opaque continuation artifact, а не summary, який application може інтерпретувати як аудит або доказ. Після compaction повторно інжектуйте чинні developer instructions і freshness-sensitive domain facts за явною політикою, замість припущення, що старий контекст лишився повним і актуальним.

Міграційний replay має перевіряти не лише короткий prompt, а й довгі trajectories: зміна інструкції після кількох turns, відкликаний approval, compaction біля tool boundary, відновлення після недоступного previous response і запит на видалення. Якщо команда не може пояснити, де живе кожен клас стану та як він відновлюється, Responses-only continuity ще не готова замінити власний conversation adapter.

• Model continuity → items, previous response або conversation.
• Domain memory → чинні факти з system of record.
• Policy memory → versioned instructions і дозволи, що перевіряються заново.
• Audit evidence → незмінний trace подій, а не compacted model context.

Background response змінює production contract із синхронного request/response на state machine. Збережіть власний job ID, provider response ID, input fingerprint, tenant, deadline і дозволений terminal policy до запуску. Webhook про completed, failed, incomplete або cancelled є тригером для обробки, але consumer повинен перевірити підпис, дедуплікувати event і отримати authoritative response state перед фіналізацією domain job. Порядок доставки та повторне надходження подій не мають змінювати результат.

Не зв’язуйте HTTP timeout із автоматичним створенням нового response. Спочатку знайдіть run за idempotent application key або збереженим provider ID, retrieve його стан і лише потім вирішуйте, чи безпечно повторити model work. Якщо response уже породив application tool request, повторний model run не повинен повторити зовнішній side effect: mutation має власний idempotency key і reconciliation у system of record.

Визначте terminal mapping явно: provider `completed` може означати лише завершення model run, а не успішну оплату, відправлений лист чи оновлений ticket. Domain outcome стає `verified` тільки після schema validation, policy check, tool execution та postcondition. Rollback вимикає нові background submissions, продовжує приймати й reconcile in-flight notifications і залишає оператору чергу станів `unknown`, а не губить їх під час перемикання назад на Chat Completions.

Для кожного workload створіть короткий decision record: поточний Chat Completions contract, потрібна Responses capability, альтернативний спосіб реалізації, очікувана operational вигода, нові failure modes, retention impact, eval slices, owner і rollback date. Формулювання «новіший API» не є acceptance criterion. Достатньою причиною може бути built-in tool, довга reasoning continuity, background execution або item-level event model — але лише якщо capability справді використовується й дає перевірений результат у вашому контексті.

Під час canary тримайте model snapshot, prompt, tool schema та policy version максимально стабільними, щоб endpoint залишався основною змінною. Порівнюйте verified task success, context growth, incomplete/unknown states, duplicate events, time to terminal domain outcome, reviewer corrections і повну вартість. Якщо нова capability не проходить визначений gate, поверніть traffic на старий adapter; зібраний Responses trace лишається regression evidence, а не аргументом завершити міграцію будь-якою ціною.

• Adopt → capability потрібна, replay пройдено, runbook і rollback перевірені.
• Defer → endpoint стабільний, а нова capability не змінює outcome.
• Reject for now → retention, lifecycle або critical-slice gate не виконано.
• Re-review → після зміни model, API contract, workload або data policy.