跳到主要內容
黯羽輕揚每天積累一點點

Responses API 遷移完整指南：從原理到落地的工程實踐

免費2026-07-20#AI#AI

為什麼現在該認真看 Responses API 遷移

Chat 補全 API 已經夠用了嗎？當你的應用程式需要維護跨多輪對話的狀態、呼叫多個工具，甚至讓模型動態決策下一步呼叫哪個工具時，Chat 補全 API 的 stateless 設計會讓程式碼變得極為複雜。你需要自己管理訊息歷史、拼接工具回傳結果、處理多輪 context。 Responses API 正是為了解決這個痛點——它把多輪對話、工具呼叫和狀態管理統一為一個可編程的 API 對象，讓開發者聚焦於業務邏輯而非拼湊狀態。這不是簡單的版本升級，而是從「單一對話」到「工作流程」的範式轉換。現在遷移，你就能在 Agent 架構上搶跑；等別人都鋪好輪子時，你已經有了生產可用的工作流程。

它到底在解決什麼工程問題

問題 1：狀態管理惡夢

傳統 Chat 補全 API 每次請求都是獨立的。要實現一個有記憶的 Agent，你必須手動把歷史訊息、工具回傳、中間結果全部塞入 messages 陣列。當工具呼叫鏈變長（例如先搜尋、再分析、再產生），訊息清單可能會瞬間膨脹到數千 token，而且每次要求都要重新拼接。 Responses API 透過 previous_response_id 自動追蹤上下文。你只需建立一個 Response 對象，後續請求引用它的 ID，框架自動維護全量歷史。例如：

Responses API 請求負載截圖，展示 input、previous_response_id、tools 參數，對應正文中工具呼叫配置部分。

# Chat 补全方式：手动管理历史
messages = [{"role": "user", "content": "搜索最新的 AI 论文"}]
response = client.chat.completions.create(model="gpt-4", messages=messages)
messages.append(response.choices[0].message)
messages.append({"role": "user", "content": "摘要第一篇"})
response2 = client.chat.completions.create(model="gpt-4", messages=messages)

# Responses API 方式：自动维护上下文
response = client.responses.create(model="gpt-4", input="搜索最新的 AI 论文")
response2 = client.responses.create(model="gpt-4", input="摘要第一篇", previous_response_id=response.id)

这不仅减少了代码量，更重要的是避免了因手动拼接错误导致的 context 泄露或截断。

问题 2：工具调用编排混乱

当 Agent 需要调用多个外部工具（如搜索、数据库查询、代码执行）时，Chat 补全 API 只返回一个 tool_calls 列表，你需要自行决定调用顺序、处理嵌套调用（比如搜索结果需要再调用另一个 API）。Responses API 内置了工具调用编排：你只需在 API 调用时声明 tools，模型会自动发出工具请求，你只需把工具结果作为 tool_outputs 傳回，框架會負責繼續驅動 Agent 直到產生最終回應。

問題 3：流式與終態的割裂

Chat 補全 API 的串流模式回傳多個 chunk，你需要自己拼接出完整的訊息結構。 Responses API 統一了流式和非流式：即使使用流式，最後你也會得到一個完整的 Response 對象，方便持久化或後續引用。

最容易失敗的地方與錯誤理解

迷思 1：以為是簡單的 API 替換

很多人以為把請求從 /v1/chat/completions 改成 /v1/responses 就行。實際上 Responses API 的參數設計完全不同。 input 取代了 messages，但不再是陣列而是字串（如果只需要單輪）或包含 previous_response_id。如果你硬套舊參數，會直接報 invalid_request_error。遷移時必須檢查所有呼叫點，關鍵在於移除手動歷史拼接。

迷思 2：忽略 previous_response_id 的時效性

previous_response_id 所引用的 Response 物件並不是永久有效的。官方建議在一個會話內（例如 5 分鐘內）使用。如果你的 Agent 需要跨小時或天的記憶，需要結合資料庫持久化 Response ID 或額外使用向量記憶介面。有人曾經把 previous_response_id 換成歷史某天的 ID，結果模型遺失了最近兩輪對話。

誤區 3：工具呼叫時 missing tools 聲明

如果你在建立 Response 時沒有宣告 tools，但使用者輸入觸發了工具需求，模型會回覆一段「你需要我呼叫工具嗎？」而不是自動發起工具請求。正確做法是事先宣告所有可能用到的工具，並且處理好工具結果的逾時和重試，否則 Agent 會卡在等待工具輸出。

真實失敗場景：工具鏈死循環

某團隊建立一個多步驟分析 Agent：先搜尋關鍵字、再爬取內容、再產生摘要。由於沒有在工具輸出中加入中間狀態標識，模型重複呼叫第一個工具，導致死循環和 API 費用爆炸。 Responses API 本身不會偵測工具呼叫循環，你需要自己在工具輸出中加入 done 標誌或設定最大工具呼叫次數。

筆記本上顯示 Responses API 實作檢查清單，包含驗證單輪、多輪、工具呼叫等步驟，對應內文中落地第一步。

如果你現在就要落地，第一步怎麼做

1. 建立最小可運行的原型

別上來遷移整個生產系統。先寫一個單獨的小腳本，用 Responses API 實作一個簡單問答 Agent（例如「幫我查天氣然後發送郵件」）。驗證：

  • 單輪輸入輸出正常
  • 多輪對話（透過 previous_response_id）正常
  • 工具呼叫能正確發起和回傳結果

2. 檢查現有 API 呼叫點

在你的程式碼庫中搜尋所有 /v1/chat/completions 調用，區分哪些是簡單問答（無工具），哪些是含工具調用的複雜場景。簡單問答可以快速遷移，複雜場景建議優先遷移工具呼叫鏈較短的。

3. 重構工具呼叫邏輯

將原來的手動工具調度改為：在 responses.create 時宣告 tools，接收 Response 物件後，遍歷 output 列表，識別 tool_calls 欄位，對應工具，將結果透過 [[] responses.create 並 previous_response_id 繼續。

範例程式碼框架：

def run_agent(user_input, previous_response_id=None):
    response = client.responses.create(
        model="gpt-4",
        input=user_input,
        tools=[search_tool, email_tool],
        previous_response_id=previous_response_id
    )
    while response.output:
        for output in response.output:
            if output.type == "tool_call":
                tool_result = execute_tool(output.name, output.arguments)
                response = client.responses.create(
                    model="gpt-4",
                    input="",
                    previous_response_id=response.id,
                    tool_outputs=[{"id": output.id, "content": tool_result}]
                )
            else:
                # 最终回复
                return output.content

4. 监控与回滚

部署后监控工具调用成功率、平均响应时长和错误率。如果发现大量因 previous_response_id 失效或工具结果格式错误导致的失败，准备好回滚到 Chat 补全 API 的开关。

失败时的备用方案

备用方案 1：保留 Chat 补全 API 做降级

如果 Responses API 出现大范围故障（如超时、错误率飙升），立即降级回 Chat 补全 API。需要在代码中封装一个适配器：当 Responses API 失败时，自动切换到旧的 message 拼接逻辑。这个降级逻辑必须提前写好并测试。

备用方案 2：使用 assistants API 做備選

Assistants API 也提供狀態管理和工具調用，但複雜度更高（需要管理 Assistant 物件、File 等）。如果你的場景需要持久化歷史（跨小時/天），且 Responses API 的時效性不滿足，可以評估遷移到 Assistants API。不過注意 Assistants API 的工具呼叫模式是輪詢，延遲較高。

備用方案 3：手動狀態管理（回退到舊路）

如果都不行，最保守的方案是自己用資料庫儲存訊息歷史，繼續使用 Chat 補全 API。優點是穩定，缺點是程式碼維護成本高。

下一步：系統化學習

Responses API 只是 Agent 工作流程的起點。要真正成為 Agent 工程師，你還需要掌握：

  • 如何設計有效的工具描述（影響模型呼叫頻率）
  • 如何做 Context 視窗管理（避免超長歷史被截斷）
  • 如何為 Agent 新增錯誤復原（如工具逾時重試）
  • 如何用 Codex 或 Cloud IDE 偵錯多步驟 Agent 行為

這些內容在官方文件中分散且偏原理，更適合系統化的課程。如果你希望快速上手生產級 Agent 工程，可以看看下方的高品質原始付費文章和 AI 程式設計進階課程——它們直接跳過概念、聚焦你落地時最常遇到的坑和決策點。

評論

暫無評論，快來發表你的看法吧

提交評論