什麼是 Responses API：開發者必須理解的 AI 工程核心概念

一個具體的工程場景

你正在開發一個客服 agent，需要讓模型輸出結構化的 JSON 回應，包含意圖、實體和回應文案。你呼叫了 POST /v1/chat/completions，但回傳的資料裡總是混著換行、縮排和多餘的 key，你需要寫一堆正則去清洗。更糟的是，當你想在使用者持續對話中加入外部搜尋工具時，模型輸出和工具回傳的資料擠在一起，你分不清哪一段是模型生成的、哪一段是工具回傳的。

這個問題的本質是：AI 模型的輸出沒有一個標準化的、機器可讀的容器。而 Responses API 正是為了解決這個問題而出現的。

Responses API 到底指什麼

Responses API 是一套約定：它定義了模型輸出應該被包裝成一個結構化的 Response 對象，包含明確的元資料（如 token 用量、完成原因、工具呼叫記錄）和按類型區分的內容區塊（如文字區塊、工具呼叫區塊、圖片區塊）。它不是一個特定的 HTTP 端點，而是一種設計模式，目前主要由 OpenAI 在 Assistants API 和 Chat Completions API 的進化版本中推動，兼容 Anthropic 的 Message API 和 Cohere 的 Chat API 也部分遵循這一模式。

在程式碼層面，一個典型的 Responses API 返回結構如下：

程式碼編輯器截圖，顯示包含 function 定義的 API 請求 payload 以及對應的 Responses API 回應

{
  "id": "resp_abc123",
  "object": "response",
  "created": 1712345678,
  "model": "gpt-4-turbo",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": [
          {"type": "text", "text": "您好，请问有什么可以帮您？"},
          {"type": "function_call", "name": "search_knowledge_base", "arguments": "{\"query\": \"退款流程\"}"}
        ]
      }
    }
  ],
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 50,
    "total_tokens": 150
  }
}

注意这里的 content 是一个数组，每种类型（文本、工具调用、图片等）都独立成块。这种设计使得你不再需要猜测模型输出里哪部分是自然语言、哪部分是工具触发器。

为什么 Responses API 突然成为热词

有三个推动力：

多模态输出的需求爆发。单一文本输出已经不够用了。模型同时返回文本和图片、文本和表格、文本和函数调用变得越来越常见。Responses API 通过 content 数组自然容纳了多种输出类型。
Agent 工作流的标准化压力。当模型需要调用外部工具时，如何区分“模型自己的思考过程”和“工具返回的结果”成了痛点。Responses API 明确分离了模型消息和工具消息，使得 agent 循环更容易实现（例如 OpenAI 的 submit_tool_outputs）。
成本透明度要求。企业用户对 token 用量的精确核算需求强烈。Responses API 在每个响应里都包含准确的 usage 數據，無需額外計算。

如果你在 2023 年用 Chat Completions API 寫過一個簡單的聊天機器人，你可能沒有註意到輸出結構的變化——因為那時模型只返回文字。但今天，幾乎所有生產級 AI 應用程式都在用多內容區塊回應。

筆記型電腦上的開發環境，螢幕顯示 Responses API 遷移 checklist 文檔，桌面有鍵盤和咖啡

最容易被誤解或做錯的地方

迷思一：Responses API = Streaming API

這是最常見的混淆。 Streaming API（如 SSE）是傳輸方式，Responses API 是資料格式定義。 Streaming 可以在 Responses API 之上實現，例如逐塊返回 content blocks。但許多開發者在啟用 streaming 後，試圖手動拼接 response 對象，結果弄丟了 token 統計或工具呼叫 ID。正確做法：使用 SDK 內建的 streaming 解析，不要自行處理 chunk 邊界。

迷思二：所有模型廠商的 Responses API 是相容的

事實是，各廠商在 content block 的類型命名和元資料欄位上存在差異。例如 OpenAI 使用 function_call，Anthropic 使用 tool_use，Cohere 使用 tool_calls。遷移時需要適配層。一個常見的失敗場景是：把 OpenAI 的回應直接傳給 Anthropic 的 agent 框架，導致工具呼叫解析失敗。

迷思三：Responses API 能解決所有輸出解析問題

並不能。 Responses API 只保證資料結構的約定，不保證模型輸出完全符合你的 schema。例如你要求 JSON 格式，模型還是可能回傳非法字元。這時你仍然需要額外的驗證層（如 Pydantic 或 Zod 解析+糾錯）。

實際踩坑案例

某團隊在遷移到 Responses API 後，發現函數的 arguments 欄位總是被截斷。排查後發現是 HTTP 用戶端預設對 JSON 做了 2MB 大小的限制，而模型回傳的 tool call 參數（包含圖片 base64）超過了這個閾值。解決方案是調整客戶端的 max_payload_size 配置，並啟用回應壓縮。

如果你現在要開始實踐，第一步該怎麼做

確認你使用的模型版本支援 Responses API。 OpenAI 的 gpt-4-turbo-preview 以上版本、Anthropic 的 claude-3 系列、Cohere 的 command-r 系列都支援類似結構。使用最新 SDK 版本。
啟用 experiments 標誌（如果需要）。某些平台（如 Azure OpenAI）需要傳遞 api-version 參數才能啟用 content blocks。
改寫你的解析邏輯。如果你之前直接取 choices[0].message.content 字串，現在需要遍歷 content 數組，按 type 分支處理。
增加 content block 類型的校驗。在程式碼中定義枚舉類型（TextBlock, ToolCallBlock 等），不要假設回傳類型。
新增 unit test。模擬不同 types 的反應，確保解析器正確處理邊界情況（如空數組、未知 type）。

學完基礎後下一步該往哪條工程路徑深入

既然你已經理解了 Responses API 如何規範化模型輸出，下一個自然的問題是：如何基於它建立完整的 agent 工作流程？具體包括：

工具編排（Tool Orchestration）：如何將函數定義轉換為模型可識別的 function/tool 描述，並正確處理多次工具呼叫的循環。
情境管理與記憶：Responses API 的 messages 陣列如何擴展為持久化會話，避免 token 溢出。
Evals 與測試：如何撰寫針對多內容區塊回應的 Assertion，驗證工具呼叫是否如預期觸發。
成本追蹤：基於 usage 資料建立計量系統，支援按使用者或會話層級的計費。

如果你發現這些方向正是你工作中遇到的瓶頸，那麼你已經準備好從「呼叫 API」過渡到「設計 AI 系統」了。