Assistants APIからResponses APIへ移行する実務手順｜state・tool・file・streaming・rollback

先に結論：AssistantsからResponsesへは、fieldごとに移す

Assistants APIは2026-08-26に終了し、現在は利用できません。移行はclientのメソッド名を一括置換する作業ではなく、アプリ側に保存済みの会話履歴、prompt設定、tool call、fileやvector store、streamingイベント、非同期処理、テスト、ログを別々に棚卸しする作業です。終了したendpointを使った履歴取得や切り戻しを前提にせず、保存済みのデータと設定からResponses API側を組み立てます。

1. prompt設定：再利用Prompt objectへ長期依存しない

OpenAIの移行ガイドはAssistantからPromptへの対応を示していますが、Reusable Prompt objectもdeprecatedで、v1/prompts APIは2026-11-30にshutdown予定です。Prompt作成も2026-06-03からde-emphasizedされています。Prompt objectを短期の橋渡しに使う場合も終了日を管理し、長く運用するinstructionsやvariablesはapplication codeへ移して、review・test・deployment・versioningをアプリ側で行います。

• Assistantのinstructions、model、tool定義、変数をアプリの設定や自社exportから回収し、出所とversionを記録する
• 長期運用するprompt内容はapplication codeへ移し、review・test・deployment・versioningをアプリのreleaseと一緒に管理する
• Responses APIのリクエストでPrompt IDを参照している場合は、その依存箇所と置換期限を棚卸しする

2. state：ThreadのIDをConversationへ機械的に置換しない

最初に、ThreadやRunに相当する履歴をどこへ保存し、何を再実行時に復元するかを図にします。Assistants API終了後は、同APIのmessage取得呼び出しで履歴を取り出せません。移行ガイドが示すのはアプリケーションに保存済みのmessagesを使う方法です。新規会話をResponses / Conversations側で作る経路と、手元に保存済みの既存履歴を変換する経路を分け、履歴が存在すると思い込んだり、同じID形式だと決めつけたりしないでください。

• Thread ID、user ID、tenant、保持期限、削除依頼の扱いをConversation IDと別に対応表へ記録する
• Runのqueued / in_progress / completed / failedなど、現在の画面やDBが見る状態をResponseの状態へ対応づける
• 過去Threadの再生が必要なら、保存済みメッセージから検証用fixtureを作り、本番履歴を無確認で再送しない

3. tool：function callingと組み込みtoolの境界を分ける

Assistants側のtool定義をResponses側へ移すときは、tool名、引数schema、必須値、呼び出し結果、承認、再実行、失敗時の表示を一つずつ照合します。function calling、File Search、Code Interpreterなどの組み込み機能は、同じ名前や同じevent列がそのまま存在するとは限りません。公式移行ガイドと現行tool仕様で、入力・出力item、対応model、利用条件を確認し、未確認の互換性を記事や本番の前提にしないでください。

4. file：file IDとデータ保持を別の移行項目にする

fileは、promptへ添付したか、検索用vector storeへ登録したか、toolが生成したかで役割が変わります。移行時は、元ファイルの保存場所、file ID、vector store ID、アクセス主体、保持期限、削除フロー、ユーザーへ返すdownload linkを対応表にします。ファイルを再登録すれば同じIDになる、全履歴を自動で移せる、という前提は置かず、fixtureの小さなファイルで取得・検索・生成・削除を確認します。

• 個人情報、API key、Cookie、秘密鍵、社内資料を移行テストへ混ぜず、匿名化したfixtureだけで確認する
• fileのアップロード、参照、引用、生成物の取得、期限切れ、削除を別々のテストケースにする
• 旧resourceと新resourceの二重課金・二重保持を避けるため、移行後のcleanup ownerと期限を決める
• 検索結果の内容をそのまま信頼せず、tool出力のschema、対象file、ユーザー表示を人間が確認する

5. streaming / async：Run eventをResponse eventへ写経しない

UIがRunの状態更新やdelta eventを前提にしている場合、Responsesのstreaming event、item追加、tool call、完了、エラーの順序とpayloadを実測します。名称が似ているeventを一対一で置き換えず、途中切断、重複、再接続、tool結果待ち、キャンセル、タイムアウトを含む状態機械としてテストしてください。公式ページに書かれていないevent順序を保証扱いにせず、SDK versionと現行Docsを固定して検証します。

6. test：保存済み結果を基に業務要件を比較する

移行テストは、HTTPが成功したかだけでは不十分です。代表的なprompt、保存済み会話、tool呼び出し、file検索、stream切断、拒否、空出力、再試行をfixture化し、過去のgolden outputとResponses側の結果を比較します。Assistants APIは終了済みなので、稼働中の旧経路とのA/B比較や旧endpointへのprobeを前提にしません。Responsesが業務要件を満たすかは別に評価します。

• 入力、model、tool、file、temperature等の条件を固定し、出力の意味・schema・安全な拒否を比較する
• streamingと非streaming、同期とworker、途中失敗と再試行を同じ観点で記録する
• token、latency、retry、tool実行回数、ログ量、API料金は手元の実測として残す
• 成功率だけでなく、誤ったtool call、重複実行、ユーザーに見えない失敗、レビュー修正量を見る
• ResponsesのSDK version、公式Docsの確認日、過去出力との比較条件をテストレポートに書く
• アプリ内に移したprompt内容とversionを固定し、保存済みのgolden fixtureを使ってResponsesの結果を比較する

7. 復旧設計：終了済みのAssistants APIへ戻る前提を置かない

切り替えはfeature flagや小さな対象範囲から行い、Responses側を停止した場合にどこで処理を止め、ユーザーへ状態を伝えるかを先に決めます。Assistants APIは終了済みなので、旧endpointへ戻すrollbackは計画に含めません。異常時は保存済み履歴と未処理IDを保全し、二重のtool実行や課金を避けて、検証済みの現行処理または手動対応へ切り替えます。

既存の廃止一覧記事との役割分担

OpenAI API全体の廃止日・対象・移行先を横断して棚卸ししたい場合は、既存の「OpenAI API廃止予定チェックリスト」を参照します。このページはAssistantsからResponsesへ移す現場の対応表、event、file、テスト、復旧設計を主題にし、廃止予定の総合inventoryを重複させません。