OpenAI Responses API vs Assistants API: план міграції до sunset

Assistants API уже deprecated і, за поточною офіційною документацією OpenAI, має припинити роботу 26 серпня 2026 року. Для нового застосунку вибір фактично закритий: OpenAI рекомендує Responses API. Для чинного продукту питання складніше — не «який endpoint сучасніший», а як перенести object model, conversation state, tools, streaming і операційні контроли без непомітної зміни поведінки.

Responses API поєднує model response, tool calls та item-based output в одному примітиві й підтримує built-in tools. Assistants API організований навколо довгоживучих Assistant, Thread, Message і Run. Тому безпечна міграція — це не search-and-replace endpoint. Спочатку зафіксуйте поведінковий контракт чинної системи, потім зіставте state та execution semantics, і лише після shadow/dual run перемикайте traffic.

• Новий проєкт → Responses API.
• Чинний Assistants workload → inventory, mapping, replay, shadow, canary, cutover.
• Sunset → 26 серпня 2026 року за поточною документацією OpenAI.
• Критерій готовності → parity на власних задачах, а не лише успішна HTTP-відповідь.

У Assistants API конфігурація зберігається в Assistant, діалог — у Thread і Messages, а виконання — у Run та Run Steps. У Responses API instructions і tools зазвичай передаються у request або керуються у власному application configuration; відповідь складається з typed items. Для multi-turn state можна передати previous_response_id, власну історію input або використати conversation primitives, якщо це відповідає вашій політиці зберігання.

Практичний mapping виглядає так: Assistant instructions/model/tools → versioned agent configuration; Thread → application conversation ID або OpenAI Conversation; Message → input/output items; Run → Response; Run Steps → response output items і ваш trace. Не копіюйте identifiers механічно. Збережіть таблицю відповідності old_thread_id → new_conversation_id, migration version, last migrated message і reconciliation status, щоб повторний запуск був idempotent.

Responses — цільова платформа для нових agentic integrations, має простіший item model та актуальні built-in tools. Assistants може тимчасово залишатися production source під час міграції, але не є розумною основою для нової функції через зафіксований sunset. Якщо поточний assistant стабільний, це не причина робити big-bang rewrite; це причина почати контрольований dual run із достатнім запасом до дедлайну.

Оцінюйте не тільки feature parity. Перевірте event ordering у streaming, форму citations і tool calls, retry semantics, usage accounting, file/vector-store bindings, conversation retention, deletion workflow, latency та observability. Навіть однакова відповідь моделі може порушити контракт UI або backend, якщо змінилися identifiers, status events чи момент, коли tool result вважається завершеним.

• State → хто зберігає conversation і скільки часу.
• Tools → schema, approvals, side effects та result correlation.
• Streaming → event mapping, partial output і reconnect behavior.
• Files → ownership, vector stores, citations, deletion та access boundary.
• Operations → tracing, rate limits, budgets, retries та rollback switch.

Офіційна таблиця data controls розрізняє application-state retention за endpoint. Responses за замовчуванням зберігає response state щонайменше 30 днів, якщо store не вимкнено; conversation objects та їх items мають інший lifecycle. Assistants-related objects, які не видалені через API або dashboard, можуть зберігатися безстроково. Ці правила змінюють privacy design міграції, а не лише implementation detail.

До копіювання історії класифікуйте дані, визначте legal purpose, TTL, deletion owner і ZDR/MAM constraints. Якщо застосунок сам керує історією, не створюйте другу нескінченну копію лише заради зручності. Якщо використовуєте hosted conversation state, перевірте delete cascade на тестовому tenant і збережіть evidence, що subject/account deletion прибирає всі пов’язані files, conversations та application mappings.

Function calling означає, що модель пропонує структурований виклик, а ваш код виконує зовнішню дію. Під час dual run старий і новий path не можуть обидва відправити лист, створити ticket або списати кошти. Shadow path має замінювати write tools на simulators або policy-denied stubs і порівнювати лише запропоновані action envelopes.

Для canary writes використовуйте один authoritative action service з idempotency key, policy check і postcondition read. Ключ прив’язуйте до business operation, а не до response ID. Timeout після tool call переводить workflow у reconciliation: спочатку прочитати system of record, потім вирішити, чи повтор безпечний. Tool schema, required fields та approval policy версіонуйте окремо від prompt.

Почніть з inventory всіх assistants, threads, files, vector stores, tools, models, traffic classes та owners. Заморозьте створення нових Assistants-only capabilities. Далі побудуйте compatibility adapter: він перетворює канонічний application request на старий або новий provider path і нормалізує output у власний стабільний contract.

З historical traces сформуйте replay set із happy path, long thread, citations, parallel tool calls, malformed tool output, refusal, timeout, cancellation, sensitive data та deletion. Після offline replay запустіть write-disabled shadow, потім 1–5% canary для low-risk slice. Підвищуйте частку лише за severity-aware gates. Після cutover залиште read-only migration lookup і rollback flag, але припиніть створення нового legacy state.

• 1. Inventory і owner для кожного workload.
• 2. Canonical application contract та object mapping.
• 3. Historical replay і deterministic assertions.
• 4. Shadow traffic без side effects.
• 5. Risk-sliced canary з одним action authority.
• 6. Cutover, reconciliation і rollback window.
• 7. Legacy export/delete evidence до sunset.

Порівняйте task success, supported-claim rate, citation validity, tool-selection accuracy, argument validity, final-state correctness, latency percentiles, token/tool cost і escalation rate. Text similarity між старою і новою відповіддю слабкий oracle: формулювання може змінитися, а business outcome лишитися правильним — або навпаки.

Critical gates бінарні: cross-user state leak, пропущена deletion, unauthorized tool, duplicate side effect або неправильна consequential action блокують promotion незалежно від середнього score. Для streaming додайте protocol tests на ordering, reconnect і terminal events. Для довгих conversations — slices на context truncation, stale instructions і змішування версій agent configuration.

Rollback має перемикати нові requests на перевірений legacy path, доки він доступний, не відкотуючи вже підтверджені зовнішні actions. Conversation mapping та action ledger залишаються спільними, тому повторний request бачить authoritative state. Після sunset такий rollback зникне: резервним шляхом має бути власний degraded mode — read-only, human queue або інший уже перевірений provider path, а не виклик вимкненого API.

Не плануйте production cutover на останній тиждень. Завершіть inventory і replay негайно, shadow — з достатнім вікном для виправлень, а основний traffic cutover — до внутрішнього дедлайну, що залишає кілька тижнів на reconciliation, export і deletion evidence. Офіційні API semantics і retention rules можуть оновлюватися, тому pinned migration checklist треба повторно звірити з OpenAI docs перед кожною promotion.

Станом на 25 серпня 2026 року офіційна документація OpenAI усе ще вказує shutdown Assistants API на 26 серпня 2026 року. Якщо production traffic досі залежить від assistants, threads або runs, повний redesign уже не є безпечним планом на залишок вікна. Спочатку побудуйте dependency manifest із кожним endpoint, workload owner, traffic share, критичністю, типами tools, state store, fallback і останнім підтвердженим викликом. Шукайте не лише прямі SDK calls: background workers, retry queues, admin scripts, integration tests і dormant tenants можуть зберігати legacy dependency після перемикання основного UI.

Розділіть workloads на чотири черги. Уже мігровані потребують доказового negative probe, що legacy endpoint більше не викликається. Response-compatible workloads перемикайте через готовий adapter і canary. Неперенесені read-only flows переводьте у degraded mode з application-owned context або human queue. Write-capable чи regulated flows без перевіреної parity зупиняйте fail closed: дедлайн не надає права пропускати authorization, idempotency або deletion tests. Зафіксуйте точний час рішення, owner і критерій відновлення для кожного route.

Перед фінальним cutover увімкніть окрему legacy-call telemetry за endpoint і credential, але не логуйте message content або secrets. Нуль викликів протягом короткого вікна ще не доводить незалежність: виконайте synthetic probes для рідкісних scheduled jobs і кожного fallback path. Після успішної перевірки забороніть нові Assistant, Thread і Run operations на рівні adapter або egress policy, щоб прихований retry не повернув систему на deprecated path.

• Discover → direct calls, SDK wrappers, queues, cron jobs, tests і tenant-specific fallbacks.
• Classify → migrated, response-compatible, read-only degraded або fail-closed blocked.
• Verify → synthetic probe, legacy-call telemetry, authoritative state і owner sign-off.
• Contain → deny new legacy operations без видалення evidence, потрібного для reconciliation.

Після фактичного shutdown перевіряйте не лише те, що Responses повертає текст. Запустіть continuity suite для нового conversation, продовження дозволеного migrated state, file search, code execution, function calls, streaming terminal events, cancellation, timeout і account deletion. Для previous_response_id пам’ятайте окремий контракт: API reference попереджає, що instructions попередньої response автоматично не переносяться. Versioned instructions мають явно потрапляти в кожен потрібний request або керуватися вашим перевіреним configuration layer; інакше діалог може технічно продовжитися зі зміненою policy поведінкою.

Legacy identifiers, exports і mapping records зберігайте лише за визначеним retention purpose. Data-controls documentation розрізняє lifecycle Responses, Conversations та Assistants-related objects, тому успішний response cutover не є доказом видалення старого state. Створіть deletion ledger із типом об’єкта, owner, requestedAt, verification method, result і exception expiry. Не заявляйте, що hosted state видалено, доки API або dashboard evidence цього не підтверджує; application mapping і зовнішні files також мають власні delete checks.

Після shutdown rollback більше не може означати повернення на Assistants API. Чесний rollback — це feature flag до перевіреної Responses revision, read-only degraded path, контрольована human queue або зупинка небезпечного workflow. Incident record має відокремлювати provider availability, migration defect, state mismatch і tool-side-effect ambiguity. Якщо зовнішня дія могла відбутися, спочатку reconcile system of record; повторний model run не є rollback і може подвоїти наслідок.

• Continuity evidence → state, instructions, tools, streaming, cancellation і deletion.
• Residual-state evidence → object inventory, retention purpose, delete request і verified result.
• Operational fallback → known-good Responses revision, read-only mode, human queue або stop.
• Unknown side effect → reconcile before retry; never infer failure from a missing response.