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

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

Assistants APIをResponses APIへ移行する作業は、clientのメソッド名を一括置換する作業ではありません。会話の状態、入力と出力の保存方法、tool call、fileやvector store、streamingイベント、非同期処理、テスト、ログ、切り戻しを別の境界として棚卸しします。最初に公式移行ガイドの対応表を読み、現在のコードがどのオブジェクトとイベントを前提にしているかを記録してください。

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

最初に、ThreadやRunをどこへ保存し、どの時点でユーザーへ見せ、再実行時に何を復元しているかを図にします。現行の公式移行ページには既存ThreadをConversationsへ自動移行するtoolの案内が見当たらないため、非提供を一般断定せず、自分のprojectで移行手段を確認します。新規会話をResponses / Conversations側で作る経路と、既存履歴を参照専用で保持する経路を分け、履歴を黙って捨てたり、同じID形式だと決めつけたりしないでください。

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

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

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

3. 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、ユーザー表示を人間が確認する

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

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

5. test：品質比較と提供状態確認を分ける

移行テストは、HTTPが成功したかだけでは不十分です。代表的なprompt、長い会話、tool呼び出し、file検索、stream切断、拒否、空出力、再試行をfixture化し、旧経路と新経路の差を比較します。Responses側が利用できることと、業務要件を満たすことも別の判定です。API probeをしていない段階では、この記事の公式文言と自分のprojectで確認した状態を混同しません。

• 入力、model、tool、file、temperature等の条件を固定し、出力の意味・schema・安全な拒否を比較する
• streamingと非streaming、同期とworker、途中失敗と再試行を同じ観点で記録する
• token、latency、retry、tool実行回数、ログ量、API料金は手元の実測として残す
• 成功率だけでなく、誤ったtool call、重複実行、ユーザーに見えない失敗、レビュー修正量を見る
• API status、管理画面、SDK version、公式Docsの確認日をテストレポートに書く
• Prompt IDとexported specを固定し、旧経路と新経路のA/B結果を同じfixtureで比較する

6. rollback：旧経路を消す前に、戻せる境界を作る

切り替えはfeature flagや小さな対象範囲から始め、旧Assistants経路の読み取り・診断・停止手順を先に残します。新経路で異常が出たら、履歴を再送して二重のtool実行や課金を起こすのではなく、処理を止めて状態を確認します。旧APIの提供可否は変わり得るため、rollbackとは「いつでも旧endpointが動く」という保証ではなく、未処理データを保全し、ユーザーへ案内し、別の処理へ切り替える計画です。

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

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