Responses API 是怎麼工作的？ 我用一條真實鏈路把它講清楚

為什麼現在必須理解 Responses API

Responses API 是 OpenAI 2025 年主推的新介面形態，它把原來分散的 Chat Completions、Function Calling 和 Tool Use 合併成一個統一的請求-回應協定。 這意味著如果你還在用舊 API 拼接對話歷史、手動管理工具調用狀態，那麼往下半年你會越來越難維護——新 SDK 和 Agent SDK 都預設只支援 Responses API，舊版本已經進入倒計時。

但這不表示你只需要簡單替換 endpoint URL 就行。 我見過太多團隊在遷移後出現「對話上下文丟失」「工具調用順序錯亂」「超時回應被吞掉」等問題。 本質上，Responses API 把一部分“顯式狀態管理”從開發者手裡抽走了，如果你不理解它的數據流，就很容易掉坑。

一條真實用戶鏈路：從提問到完整回應

為了更好地說明，我們以一個實際場景來走通整個流程：使用者問“幫我查一下昨天的伺服器日誌，然後匯總錯誤類型”。

第一步：構造請求，發送使用者上下文

你只需要提供一個「輸入」字串和可用的工具清單（如果有）。 Responses API 會自動把這段輸入放入一個內部狀態上下文，不需要你手動拼接多輪 message 陣列。 例如：

POST /v1/responses
{
  "model": "gpt-4o",
  "input": "帮我查一下昨天的服务器日志，然后汇总错误类型",
  "tools": [{
    "type": "function",
    "name": "query_logs",
    "description": "查询指定日期的服务器日志",
    "parameters": { ... }
  }]
}

这里的关键区别：旧 API 需要你把“我”的历史消息都放在 messages 数组里，而 Responses API 只关心当前轮的输入，以及你是否开启 ]previous_response_id[ 来延续上下文。

第二步：模型决定调用工具

模型会返回一个 ]response[ 对象，其中 ]output[ 字段不再是简单的“assistant 消息”，而是一个数组，可能包含多个 ]function_call[ 和 ]content[ 块。例如：

{
  "id": "resp_abc123",
  "output": [
    { "type": "function_call", "name": "query_logs", "arguments": "{\"date\":\"2025-02-10\"}" },
    { "type": "function_call", "name": "query_logs", "arguments": "{\"date\":\"2025-02-11\"}" }
  ]
}

请注意，这里一口气发起了两个工具调用（因为“昨天”可能跨日）。你需要并行执行这两个调用，然后把结果作为下一次请求的一部分返回。容易出错的地方是：很多开发者会像旧 API 那样只处理第一个 function_call，导致日志查询不完整。

第三步：把工具结果送回上下文

这是最容易失败的一步。你需要把工具的结果拼接成 ]status: completed[ 的 tool_call，然后通过 ]previous_response_id[ 关联到上一个响应，再次发出请求：

POST /v1/responses
{
  "model": "gpt-4o",
  "previous_response_id": "resp_abc123",
  "input": [
    { "type": "function_call_output", "call_id": "call_001", "output": "[...日志行...]" },
    { "type": "function_call_output", "call_id": "call_002", "output": "[...日志行...]" }
  ]
}

如果你忘記設置 previous_response_id，模型就會認為這是一個全新的對話，完全不知道前面發生了什麼。 這是返回「上下文丟失」錯誤的根本原因。

第四步：模型生成最終回答

在得到工具結果后，模型會綜合所有資訊，返回一個 type: "message" 的 output，內容就是匯總后的錯誤類型。

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

誤區一：認為 Responses API 不需要管理上下文

這個誤解最大。 雖然 API 內部保留了一個上下文狀態，但你仍然需要顯式傳遞 previous_response_id。 如果你在多輪對話中不維護這個ID，模型每次都是“第一次見面”。

誤區二：並行工具調用時只處理第一個

如第二步所示，output 陣列可能包含多個 function_call。 你必須對所有調用都做出回應; 否則模型會卡住，或者返回一個不完整的回答。

失敗場景：超時導致響應丟失

Responses API 的預設超時是 30 秒。 如果你的工具執行時間超過 30 秒，API 會返回超時錯誤，且已經調用的工具結果不會保留。 這時你需要重試整個請求，並讓模型知道“前一步超時了”。

備用方案：回退到 Chat Completions + 手動狀態管理

如果你的工具調用邏輯特別複雜（多輪嵌套），或者延遲要求極高（<500ms），那麼繼續使用 Chat Completions API 手動管理消息陣列可能是更穩定的選擇。 Responses API 的設計主要是為了簡化常規 agent 場景，不是所有場景都適用。

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

1. 讀一遍 OpenAI 官方 Responses API 文檔（2025 年 2 月版），重點看 previous_response_id 和 output 結構。
2. 在你的開發環境里，把最常用的一個單輪工具調用（比如“查詢天氣”）從 Chat Completions 遷移到 Responses API，走通完整流程。
3. 記錄遷移前後的 Latency 和 Token 消耗。 Responses API 更容易預測 token 用量，因為 input 不再包含歷史消息（但上下文內部消耗 tokens）。
4. 針對多工具並行場景，編寫一個簡單的迴圈，確保所有 function_call 都被收集並回傳。
5. 設定錯誤重試邏輯：當超時或「context lost」錯誤出現時，最多重試 2 次，並考慮回退方案。

下一步去哪裡繼續系統化學習

以上只是 Responses API 的基礎用法。 如果你想把這條鏈路變成生產級別的 agent 服務——比如涉及長對話記憶、多工具編排、條件分支和錯誤恢復——那還需要更系統的方法論和實戰案例。