OpenAI Assistants API 2026 年 8 月 26 日 Sunset：如何遷移 Responses API？

8 月 26 日到底關什麼

被關閉的是整個 Assistants 平臺，不是某一個模型。Assistant 配置（instructions、tools、model 綁定）、Thread 裏累積的消息、Run 及其 steps——這些對象在 sunset 之後都無法再通過 API 讀寫。Chat Completions 不在此次下線範圍內；Realtime API 也不受影響。容易誤判的是：代碼裏仍 import OpenAI 客戶端、仍用 gpt-4o，但只要路徑還在 beta.threads 或 beta.assistants，8 月 27 日就會整段掛掉。

OpenAI 沒有提供 Thread → Conversation 的自動遷移工具。官方文檔寫明：現有 Thread 歷史需要你自己 iterate messages，按 Conversations API 的 item 類型寫回。Vector store 與已上傳文件則繼續可用——file_search 在 Responses API 裏仍引用 vs_ 開頭的 ID，不必重新上傳索引。

時間線要記兩個日期：2025-08-26 公告與一年遷移期；2026-08-26 硬下線。GPT-5 等新模型已只走 Responses API，繼續押在 Assistants 上等於同時承擔「協議死亡」和「模型夠不着」兩層風險。

對象映射：Assistants → Responses

官方遷移指南用一張對照表描述概念遷移。紙面上名字一一對應，工程上職責變了：

Assistants 把「配置」和「會話」都託管在 OpenAI 側，很多團隊從未把 thread_id 當成一等公民建模。遷移後 Conversations API 仍託管狀態，但你要顯式創建 conversation_id、決定何時歸檔、以及 Thread 數據不會自動出現。若業務依賴「2024 年某條 thread 裏的客服記錄」，sunset 前必須導出或回填。

詳細對象說明見 OpenAI 文檔Migrate to the Responses API 與 Conversations API。

心智模型：從輪詢 Run 到一次 Response

Assistants 典型流程：create thread → add message → create run → while status in queued/in_progress → list messages。網絡往返多、失敗面在 run_id 與 step 上，調試時要對照 run steps 與 message 順序。Responses API 把「這次模型調用」收成單一 API：input（字符串或 item 數組）、instructions、tools、previous_response_id 或 conversation 綁定，都在同一請求裏。

Stateful 並沒有消失，而是從「隱式 Thread」變成「顯式 Conversation 或 previous_response_id 鏈」。多輪 Agent 仍可把 tool output 作爲下一跳的 input items 傳回，只是不再創建 Run 對象。Streaming 時讀 response.output 事件即可，不必再 poll。

對 JSON 流水線而言，最大的利好是 Structured Output 在 Responses API 是一等公民：text.format 下掛 json_schema，規則與 Chat Completions 的 response_format 相同，只是外殼字段名不同。站內AI Structured Output 教程已按 Chat Completions 講過 json_schema + strict；遷到 Responses 時把同一 Schema 挪到 text.format 即可，本地校驗流程不變。

遷移清單與 Thread 歷史

建議按下面順序做，避免漏網之魚：

• 代碼庫 grep：beta.threads、beta.assistants、/v1/threads、/v1/assistants、OpenAI-Beta.*assistants、run_steps、create_and_poll
• 盤查數據庫與環境變量裏的 assistant_id、thread_id；標記哪些 thread 仍活躍、哪些可歸檔
• Sunset 前對必須保留的 thread 寫導出腳本：list messages → 轉成 Conversations items → conversations.create + items.create
• 把 instructions 與 tools 從 Assistant 對象遷到代碼常量、配置中心或 Prompt 管理——長期不建議綁 Dashboard Prompt（2026-11-30 棄用）
• 用 staging 跑通一條 responses.create（含 file_search 或 function tool），對比舊 Assistants 輸出；JSON 結果用 JSONVue 做格式化與 Schema 校驗
• 刪除所有 run polling 與 run_id 持久化；改爲存 response.id 或 conversation.id

Thread 回填不是 copy-paste：Thread 只存 role/content 消息，Conversation items 還要容納 tool_call、tool_result 等類型。若歷史裏只有 user/assistant 文本，映射相對直接；若跑過 code_interpreter 或 file_search，要按官方 item schema 補全 type 字段。

代碼對照：舊 Assistants 與新 Responses

舊式 Assistants（8 月 26 日後報錯）大致如下：

thread = client.beta.threads.create()
client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Summarize ticket #8842 for billing.",
)
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id="asst_abc123",
)
messages = client.beta.threads.messages.list(thread_id=thread.id)

等價 Responses 調用把 instructions 與 tools 內聯，並用 previous_response_id 或 conversation 維持多輪：

response = client.responses.create(
    model="gpt-4o",
    instructions="You are a billing assistant.",
    input="Summarize ticket #8842 for billing.",
    tools=[{"type": "file_search", "vector_store_ids": ["vs_abc123"]}],
    # previous_response_id="resp_..."  # or conversation="conv_..."
)
print(response.output_text)

注意：function 工具在 Responses 裏返回的仍是結構化 item；arguments 是 JSON 字符串時，執行層仍要 JSON.parse + Schema 校驗——與Stateless MCP文裏講的 tools/call 參數校驗是同一類問題。

工具、文件搜索與 Structured Output

Vector store ID（vs_…）可繼續用於 Responses 的 file_search 工具，無需重新 embedding。已上傳文件與 Assistants 時代共用同一套 Files API。code_interpreter 在 Responses 側以內置 tool 形式提供，配置方式與 Assistants 不同，需對照最新 tool 文檔逐項遷移。

若最終答覆需要固定 JSON 形狀，在 Responses 請求裏使用 Structured Output，而不是在 instructions 裏重複寫字段表。示例片段：

response = client.responses.create(
    model="gpt-4o-2024-08-06",
    input=[{"role": "user", "content": "Extract ticket fields."}],
    text={
        "format": {
            "type": "json_schema",
            "name": "support_ticket",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "category": {
                        "type": "string",
                        "enum": ["billing", "bug", "other"],
                    },
                },
                "required": ["summary", "category"],
                "additionalProperties": False,
            },
        }
    },
)

響應體裏按 output item 取 text；整段即爲 JSON 字符串時，走 JSON.parse → 本地 Schema 二次校驗。遷移期建議雙寫對比：同一 prompt 在 sunset 前用 Assistants 跑一次、staging 用 Responses 跑一次，用JSON Diff看鍵名是否漂移。

延伸閱讀：AI Structured Output 教程、DeepSeek V4-Flash 與 JSON 輸出、Stateless MCP 解析。

常見問題 FAQ

總結與下一步

Assistants API sunset 是一次架構切換：四個服務端對象合併成 Responses + Conversations，Run 輪詢消失，Thread 歷史不會自動跟過來。Vector store 可複用，Structured Output 的 JSON Schema 契約可平移。真正的工作量在於找出所有 thread/assistant 依賴、回填必要歷史、重寫 orchestration。

下一步：grep 代碼庫確認無遺漏，在 staging 用 responses.create 跑通主流程，並把模型 JSON 貼進 JSONVue 校驗。需要對比 Schema 約束時閱讀 Structured Output 教程；需要 Remote 工具協議時閱讀 Stateless MCP 文。