OpenAI Assistants API 已棄用怎麼辦？Responses API 遷移檢查表

先理解物件對照，不要只做文字替換#

這張表是責任邊界的起點，不是自動 migration map。官方文件沒有提供把所有既有 Thread 自動轉成 Conversation 的一鍵流程；你要先判斷哪些歷史對話必須保留，哪些可以從新使用者請求開始建立。

遷移步驟一：盤點 Assistants 的設定與工具#

先從程式碼、資料庫和後台匯出以下資訊：

• instruction、system prompt、模型、temperature 或其他請求參數。
• 每個 Assistant 綁定的工具、tool schema、檔案和向量資料來源。
• Thread 的 user／tenant 關聯、訊息排序、metadata、保存期限。
• Run 的 polling、stream、timeout、取消、重試和錯誤處理。
• Run step 中真正會改變外部狀態的 tool call，以及 tool output 如何回寫。

把這份 inventory 當成遷移驗收清單。尤其不要只測「模型回了一段文字」：tool call、檔案、權限和外部 API 副作用才是最容易在新 API 中悄悄改變的部分。

遷移步驟二：處理 Assistants 對應的 Prompts#

官方 migration guide 將 Assistants 對照到 Prompts，實務步驟是把 instruction 和工具組合整理成可版本化的 named prompt，再用 prompt ID 在不同環境 rollout。建議同時把 prompt ID、匯出的規格、評估案例和變更原因放進 source control；不要讓 Dashboard 裡的一個可變物件成為唯一真相來源。

還有一個容易忽略的風險：同一份官方 migration 文件也提醒 reusable prompt objects 有自己的 deprecation timeline。換句話說，Prompts 可以協助過渡與 A/B test，但長期設計仍應保留能直接送入 Responses API 的 instruction、tool schema 和版本紀錄，並持續查看官方更新。

遷移步驟三：決定哪些 Thread 要 backfill#

Conversations 可以保存 messages、tool calls 和 tool outputs。對仍在進行中的使用者對話，建議先在新程式碼中建立 Conversation；對必須保留上下文的舊 Thread，再依時間順序讀取訊息並轉成新的 items。官方範例的流程是：

1
messages = client.beta.threads.messages.list(
2
    thread_id=old_thread_id,
3
    order="asc",
4
)
5

6
# 將 messages 轉成 Conversations 接受的 items，保留必要的 role、content 與 metadata
7
conversation = client.conversations.create(items=items)

上面的 items 不是把舊 API response 原封不動塞入去；要依實際訊息 content、tool call 和 tool output 做明確轉換。先決定哪些資料可包含在新對話，再處理敏感資料遮罩、附件和 metadata，避免為了「完整 backfill」把不必要的歷史資料複製到新保存機制。

遷移步驟四：改寫 Responses 呼叫與 tool loop#

Responses API 的基本呼叫可以是：

1
response = client.responses.create(
2
    model="gpt-5.6",
3
    input=[{"role": "user", "content": "Summarize this document."}],
4
    conversation=conversation_id,
5
)

真正的 migration 工作在呼叫前後：你的應用程式要明確處理 response items、tool call、tool output、失敗重試、取消和歷史修剪。官方遷移說明也指出，應用程式會承擔更多 orchestration、history pruning、tool loop 和 retry 責任；不要假設舊版 Run polling 邏輯可以原封不動保留。

逐一檢查每個工具：

1. tool schema 的參數名稱和必填欄位是否一致。
2. tool call 的 request ID 是否能和 tool output 正確配對。
3. 外部副作用是否有 idempotency key，重試時不會重複扣款或建立資料。
4. 失敗、拒絕、超時和部分完成是否能在 UI 和資料庫留下可追蹤狀態。
5. 檔案、搜尋或程式碼執行相關能力是否仍符合新 API 的支援方式。

遷移步驟五：用雙軌測試控制 rollout#

不要一次把所有租戶切到新 API。可以按照以下順序：

• 用固定問題集比較舊結果與 Responses 結果，重點看工具、引用、格式和拒答，不要求逐字相同。
• 用一個無外部副作用的測試 tenant 驗證 Conversation backfill 和歷史順序。
• 先讓新路徑 shadow 或只服務內部帳號，記錄 latency、token、錯誤和 retry 次數。
• 對會寫入外部系統的 tool 加上明確的 feature flag 和人工核准窗口。
• 確認新路徑能讀取必要資料後，再逐批切換 tenant，保留舊資料的唯讀備份。

由於官方關閉日期已到，這裡的「雙軌」是為了驗證資料和行為，不代表應繼續把 Assistants API 當成長期 fallback。若舊 endpoint 已在你的帳號不可用，直接以 fixtures、匯出資料和 mock tool 先完成遷移驗證。

常見問題#