OpenAI Agents API vs Responses API：2026 AI Agent 開發者應該如何選擇？從 JSON Tool Calling、Structured Output 到多 Agent 協作完整對比

閱讀前速覽

入口	一句話	你持有什麼
Agents API	OpenAI 跑 Codex harness	Session / Environment
Responses API	你自己打模型、自己轉循環	input / output items
Agents SDK	循環留在你的行程	runner / handoff
JSON 鏈	工具名、參數、結果仍是物件	call_id / Schema

先選主語：要不要自己持有循環。換入口，JSON 呼叫鏈還在。

選的是誰跑循環，不是誰更聰明

2026 年 GPT-6 Astra 的工具呼叫已經走 Responses。Agents API 是另一層：託管 session、壓縮上下文、派 subagent。兩套入口共用同一條 JSON 鏈，主語不同。

• 要自己控每一步：審批、重試、把 function_call_output 寫回——用 Responses API。
• 要跨小時任務、託管恢復、沙箱和 subagent：用 Agents API。
• 循環必須留在自己行程，又想要現成 runner：用 Agents SDK，底層仍常打 Responses。

Agents API 本身怎麼調工具，見 OpenAI Agents API 完整解析。若 Agent 和 Function Calling 還糊在一起，先讀 AI Agent 完整指南。

兩個 API 各管一層

Responses API 是低層：/v1/responses。你給 input，收回一組 typed items：message、reasoning、function_call。GPT-6 Astra 指南 的工具呼叫要求走這條。Structured Output 寫在 text.format，不再是 Chat Completions 的 response_format。

Agents API 是託管 harness：POST /v1/agents/sessions。你宣告 Agent、Tools、Environment；OpenAI 跑循環、compact、恢復。function 要你回結果時，session 發 requires_action，你按 turn_id / call_id 交 tool_result。

Agents SDK 不是第三套協議。它是你行程裡的 runner：handoff、審批、儲存由你管，模型呼叫往往仍落在 Responses。官方也寫明：Session、SDK session、Responses conversation、sandbox 是四份不同資源。

Tool Calling：同一條鏈，兩套回寫

Responses 上，你每輪自己 responses.create。工具表和最終卡片可以寫在同一請求裡：

{
  "model": "gpt-6-astra",
  "input": "Look up order A-1042.",
  "tools": [
    {
      "type": "function",
      "name": "lookup_order",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" }
        },
        "required": ["order_id"],
        "additionalProperties": false
      }
    }
  ],
  "text": {
    "format": {
      "type": "json_schema",
      "name": "order_card",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" },
          "status": { "enum": ["paid", "pending", "void"] }
        },
        "required": ["order_id", "status"],
        "additionalProperties": false
      }
    }
  }
}

模型若要查單，output 裡會出現獨立的 item，用 call_id 把呼叫和結果釘在一起：

{
  "output": [
    {
      "type": "function_call",
      "call_id": "call_3c91",
      "name": "lookup_order",
      "arguments": "{\"order_id\":\"A-1042\"}"
    }
  ]
}

你的應用執行函數，再把結果當作下一次 input 的一條 item 送回去：

{
  "type": "function_call_output",
  "call_id": "call_3c91",
  "output": "{\"status\":\"paid\",\"amount\":99.00}"
}

Agents API 把這幾輪收進 session。建立時一次宣告工具、沙箱和是否開 multi_agent：

{
  "agent": {
    "model": "gpt-6-astra",
    "tools": [
      { "type": "function", "name": "lookup_order", "parameters": {
        "type": "object",
        "properties": { "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" } },
        "required": ["order_id"],
        "additionalProperties": false
      }},
      { "type": "web_search" }
    ],
    "multi_agent": { "enabled": true, "max_concurrent_subagents": 3 }
  },
  "environment": { "type": "hosted", "workspace_directory": "/workspace" },
  "input": [{ "role": "user", "content": [{ "type": "input_text", "text": "Look up A-1042." }] }]
}

輪到你的 function，harness 停在 required_actions。回寫不是 function_call_output，而是帶 turn_id 的 tool result：

{
  "type": "tool_result",
  "turn_id": "turn_2",
  "call_id": "call_3c91",
  "success": true,
  "output": "{\"status\":\"paid\"}"
}

名字不同，門一樣：Schema 決定什麼能進執行。MCP 那一行只是另一張工具表，邊界見 MCP Tool Schema vs Function Calling。

Structured Output：收的是最終卡片，不是工具參數

Responses 把最終形狀放在 text.format。這管的是模型最後吐給使用者的物件，不管工具參數。工具參數仍要自己的 Schema。口徑見 AI 為什麼需要 JSON Schema。

• Responses：text.format.json_schema + strict: true 鎖最終卡片。
• Agents API：循環託管了，最終產物仍該有 Schema；function / MCP 參數各自收緊。
• 兩邊都成立：Structured Output 不是門禁。金額、確認、放行仍由宿主寫。

常見錯法是只鎖最終卡片，把 lookup_order 留成寬 object。卡片漂亮，副作用已經走了。

多 Agent：託管扇出，還是自己 handoff

「多 Agent 協作」不是第三種智能，是誰持有編排：

• Agents API：multi_agent.enabled，subagent 自帶上下文，主 Agent 用 create / wait / interrupt。預設併發要設上限。
• Agents SDK：handoff 物件在你的 runner 裡，審批和儲存你說了算。
• Responses：沒有內建 subagent。你要自己把多個 responses.create 串成圖，或把狀態放進 Conversations。

handoff 該是可審計的 JSON，不是一句「請交給帳單組」。怎麼收成 Schema，見 JSON Schema 與 AI Agent 工作流。

一張表看完三個入口

官方對比表可以再壓成工程問題：

沒有「更好的 API」。只有「主語在不在你這邊」。

四步決定入口

不要從品牌頁選。按這四問選：

1. 業務副作用能不能離開你的行程？退款、改庫必須你點頭，先 Responses 或 SDK。
2. 任務會不會跨過一個上下文視窗？會，而且你不想自己 compact，才需要 Agents API。
3. 要不要沙箱裡跑命令、讀檔案？要，Agents API 的 Environment 是現成的；Responses 你自己準備執行世界。
4. 要不要並行 subagent？要且不想自建編排，開 Agents API 的 multi_agent，並寫死併發上限。

四個「要」都落在託管側，再進 Agents API。有一個「必須自己握著」，就從 Responses 起。SDK 是第三種：循環在你這，膠水少寫一點。

對比之前，先把兩段 JSON 攤開

選錯入口，多半是沒看物件。把兩條軌跡放在一起看。

• 把 Responses 的 output[] 和 Agents 的 session items 格式化，確認 call_id 對得上。
• 用 JSONPath 提取 抽出 name、arguments、text.format，不要靠眼睛掃文件。
• 同一筆訂單在兩種入口下的軌跡 JSON Diff。漂了，先看回寫形狀，再怪模型。
• 最終卡片 Schema 和工具參數 Schema 要分開審。鎖卡片不鎖參數，等於只裝修門面。
• 訂單和內網 MCP 不要貼進公共格式化站。JSONSort 在瀏覽器本地跑。

兩段軌跡都能重建，你才知道自己在選入口，而不是在選口號。

常見誤區

• 以為 Agents API 取代了 Responses。官方把它們寫成兩個起點。Astra 的 tool calling 仍走 Responses。
• 把 Session 和 Conversation 當成同一個資源。刪一份不會自動清另一份。
• 只給最終卡片 Schema，工具參數放寬。副作用發生在 function_call 被執行時。
• 開 multi_agent 卻不設併發上限。託管扇出一樣燒 token、放大副作用。
• 用 SDK 卻以為自己不用再寫門禁。runner 替你轉循環，不替你校驗金額。
• 按演示影片選 API。演示裡循環被藏起來了。先問主語在哪。

FAQ

2026 年新專案該從哪個 API 開始？

預設從 Responses 起：你看得見每一跳。只有任務要跨視窗、要託管沙箱或 subagent，再把循環交給 Agents API。

GPT-6 Astra 能不能只用 Agents API、不碰 Responses？

可以只開 Agents session。但 Astra 的底層 tool calling 文件仍指向 Responses。短鏈路、Structured Output、自己轉循環，繼續用 Responses。

Structured Output 能不能代替 Tool Calling？

不能。Structured Output 鎖最終物件。Tool Calling 鎖副作用。退款、查單、改檔案走工具 JSON；給使用者看的卡片走 text.format。

多 Agent 是不是必須上 Agents API？

不是。SDK 的 handoff、你自己串的多次 Responses，都是多 Agent。Agents API 只是把扇出做成託管能力。

兩套 API 能混用嗎？

能，但資源不要混。用 Responses 抽結構化卡片，用 Agents session 跑長任務。Session、Conversation、sandbox 分開建、分開刪。

結論

Agents API 和 Responses API 不是兩代產品。一個託管循環，一個把循環交給你。JSON Tool Calling、Structured Output、多 Agent，都只是這條鏈上的不同物件。

先寫清主語：這跳該不該離開你的行程。再選入口。模型會換；call_id 和 Schema 應該先穩定。

延伸閱讀

• OpenAI Agents API 完整解析 Session、Tool Calling、Schema 怎麼接
• AI Agent 是什么？完整指南 執行時與 JSON 契約
• AI 为什么需要 JSON Schema Schema / Function Calling / Structured Output
• JSON Schema 与 Agent 工作流 把工具和狀態收成 Schema
• MCP Tool Schema vs Function Calling 工具 JSON 的协议边界
• JSONSort 本地工具箱 格式化、校驗、Diff
• 全部文章 更多 JSON 與 AI 開發筆記

更新紀錄： 2026-09-21 首次發布