OpenAI Agents API 2026 完整解析：Agents API 如何讓 AI Agent 直接呼叫工具？JSON Schema、Tool Calling 與 Agent Workflow 資料結構詳解

閱讀前速覽

概念	一句話	落在哪
Agents API	OpenAI 託管的 Codex harness	sessions.create / agent
Tool Calling	模型提議工具名和參數	function_call / arguments
JSON Schema	能進循環的參數形狀	parameters / additionalProperties
Workflow	會話、回合、條目、交接	session / turn / items

先記住分工：你宣告 Agent、Tools、Environment；OpenAI 跑循環。副作用仍在宿主或沙箱，不在權重裡。

能調工具。調的不是模型自己

Agents API 公測後，一條 POST /v1/agents/sessions 就能拉起長期執行的 Agent：查訂單、讀倉庫、派 subagent。這些副作用是真的。

「直接呼叫」這個詞會把主語寫錯。模型不持有 MCP 連線，不 spawn 沙箱行程，也不自己打你的業務 API。它只產生可校驗的物件。真正執行的是託管 harness，以及你選的 Environment。

• 宣告：你在 agent.tools 裡放 function、MCP、web_search。
• 提議：模型發出 function_call，名字加參數物件。
• 執行：harness 調服務端工具、你的 function handler，或沙箱裡的命令。

若 Agent、Tool Calling、Function Calling 還糊成一個詞，先讀 AI Agent 完整指南。本文只談一件事：Agents API 怎樣把這條 JSON 鏈託管起來。

9 月 10 日公測交了什麼

OpenAI 的原文寫得很直：把驅動 Codex 和 ChatGPT for Work 的同一套 harness 交給開發者。模型側常見是 GPT-6 Astra 指南。你付的是 token 和工具用量，API 本身不加一層費。

• 託管循環：session、編排、恢復，不用自己寫 LangChain 膠水。
• 上下文壓縮：接近視窗上限時自動 compact，跨多個視窗續跑。
• Tool search + programmatic tool calling：按需載入工具定義，並行呼叫，只把相關結果回寫上下文。
• MCP / function / web_search：工具表可以混掛。
• Subagents：multi_agent.enabled，預設併發上限可設，文件常見值為 6。

OpenAI DevDay 2026 預測 寫過 Structured Outputs 和 Function Calling 的預測。公測落地的不是又一個 chat completion 包裝，而是 session 資源：Agent、Environment、Session、Events / Items。

JSON Tool Calling 才是同一條骨架

換了 API 名字，四跳沒變：

1. 宣告：agent.tools[] 給出 function Schema、MCP server、內建工具。
2. 提議：模型填工具名和參數。它不執行。
3. 門禁：harness 或你的 handler 校驗、做 allowlist、決定等不等待人。
4. 回寫：tool result 變成下一輪可見的 item。

一次 session 建立，官方形狀大致是這樣。下面用虛構訂單，不要把真實金鑰或內網地址貼進公共站點：

{
  "agent": {
    "model": "gpt-6-astra",
    "instructions": "Look up orders. Confirm before any refund.",
    "tools": [
      { "type": "programmatic_tool_calling" },
      {
        "type": "function",
        "name": "lookup_order",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" }
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      },
      {
        "type": "mcp",
        "server_label": "orders",
        "transport": {
          "type": "http",
          "server_url": "https://orders.example.com/mcp"
        }
      }
    ],
    "multi_agent": {
      "enabled": true,
      "max_concurrent_subagents": 3
    }
  },
  "environment": {
    "type": "hosted",
    "workspace_directory": "/workspace"
  },
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Look up order A-1042." }
      ]
    }
  ]
}

循環轉起來之後，模型發出的仍是一段物件，不是一段「請查一下訂單」的散文：

{
  "type": "function_call",
  "id": "call_3c91",
  "name": "lookup_order",
  "arguments": "{\"order_id\":\"A-1042\"}"
}

MCP 那一項只是另一張工具表的寫法，協議邊界見 MCP Tool Schema vs Function Calling。Coding Agent 在沙箱裡跑命令，形狀仍是 JSON，見 AI Coding Agent 與 JSON 呼叫鏈。

JSON Schema 才是門，不是「請輸出 JSON」

Agents API 不會因為託管了循環，就把寬 object 變安全。口徑見 AI 為什麼需要 JSON Schema：prompt 影響它填什麼；Schema 決定什麼能進執行。

{
  "name": "lookup_order",
  "description": "Look up an order by ID",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "pattern": "^[A-Z]-\\d{4}$"
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

一份能擋事的 function Schema 至少要有四件事：

• 收緊類型：order_id 用 pattern，不要裸 string。
• 列舉金額與動作：退款、改狀態必須 enum。
• 關掉多餘鍵：additionalProperties: false。寬物件等於多開一扇門。
• 確認欄位由宿主寫：模型可以提議 create_refund，不能自己把 allowed: true 寫進狀態。

把工具和工作流收成倉庫裡的 Schema，而不是聊天紀錄裡的約定。流程怎麼串，見 JSON Schema 與 AI Agent 工作流。

Agent Workflow 是四類物件，不是一段 prompt 鏈

官方把 Agents API 收成四個概念。工程上它們都是 JSON：

• Agent：模型、instructions、tools、MCP。這是能力表。
• Environment：hosted / self_hosted 沙箱，檔案、命令、skills 住在這裡。
• Session：可續跑的實例。狀態保存在服務端，不必自己拼 history。
• Events / Items：輸入、tool call、tool result、subagent 協調動作。

一筆可審計的工作流，看起來應該像物件，而不是最後一句「已經辦好了」：

{
  "session_id": "sess_9f2a",
  "turn": 2,
  "items": [
    { "type": "function_call", "name": "lookup_order", "id": "call_3c91" },
    { "type": "function_call_result", "call_id": "call_3c91", "status": "paid" }
  ],
  "state": {
    "order_id": "A-1042",
    "status": "paid"
  },
  "next": {
    "tool": "create_refund",
    "allowed": false,
    "reason": "missing_confirmation"
  }
}

Subagent 有自己的上下文。主 Agent 用 create / message / wait / interrupt 這類 item 協調。預設併發要設上限；不設上限，帳單和副作用都會扇出。

和 Responses API、Agents SDK 差在誰跑循環

不是誰更聰明，而是編排住在哪：

選 API 之前先選主語：你要不要自己持有循環。完整對比下一篇再寫。本篇只要求你看懂：換入口，JSON 呼叫鏈還在。

你該檢查物件，不是「Agent 已完成」

Session 跑完之後，審的不是最後一句自然語言。審的是軌跡。

• 把 agent.tools、function_call、function_call_result 格式化，看名字和參數是不是你以為的那一下。
• 用 JSONPath 提取 抽出 name、arguments、server_url，不要靠眼睛掃散文。
• 和上週能過的 session 軌跡 JSON Diff。循環漂了，先看工具表和參數形狀，再怪模型。
• compact 之後的摘要也要能對上關鍵欄位。壓縮丟了 order_id，下一跳就會填錯。
• 訂單、會話、內網 MCP 地址不要貼進公共格式化站。JSONSort 在瀏覽器本地跑，適合看這些物件。

軌跡能重建，session 才能復盤。這是 Agents API 能進生產的前提，不是錦上添花。

常見誤區

• 以為 Agents API 讓模型自己執行了工具。執行權在 harness 和 Environment。
• 把寬 object 交給託管循環。託管不等於門禁。
• 打開 multi_agent 卻不設併發上限。subagent 會扇出 token 和副作用。
• 把 Session 當成又一次 chat completion。狀態、恢復、compact 都是一等物件。
• 用 prompt 代替 Schema。口徑必須能校驗。
• 把 hosted sandbox 當成 Zero Data Retention。官方寫明：自建沙箱也不讓 Agents API 變成 ZDR。

FAQ

Agents API 是讓模型直接呼叫工具嗎？

是讓模型直接發出工具 JSON。執行仍在託管 harness、你的 function handler 或沙箱。沒有 tools[]，它調不了任何東西。

和 Responses API 比，我該從哪開始？

要 OpenAI 幫你跑長期循環、壓上下文、派 subagent，用 Agents API。要自己控每一步模型呼叫，用 Responses API。要循環留在自己行程裡，用 Agents SDK。

JSON Schema 在 Agents API 裡還需要嗎？

需要。託管循環只負責編排。function 參數、MCP inputSchema、狀態物件仍然要收緊。寬 Schema 加上自動循環，等於把門開得更大。

Session、Turn、Item 有什麼差別？

Session 是可續跑的實例。Turn 是一次使用者輸入啟動的工作。Item 是這一段裡的輸入、tool call、結果或 subagent 協調動作。審計看 item，不要只看最後一句。

能不能讓 Agent 直接碰生產庫或生產退款？

不要把生產副作用交給第一跳。讓它在隔離環境和收緊 Schema 裡起草，確認欄位由宿主寫。金鑰和放行仍是人的戰略門。

結論

Agents API 讓 Agent「直接呼叫工具」——這句話只對一半。它對的是你不再手寫循環；錯的是主語。主語是 harness，謂語是執行，賓語是模型填出來的 JSON。

從今天起，少爭論它「會不會自己做」。先把 Agent、Tools、Session items 和 Schema 寫進倉庫。模型會換；這條 JSON Tool Calling 鏈應該先穩定。

延伸閱讀

• AI Agent 是什麼？完整指南 執行時、Tool Calling 與 JSON 契約
• JSON Schema 與 AI Agent 工作流 把工具和狀態收成 Schema
• MCP Tool Schema vs Function Calling 工具 JSON 的協議邊界
• AI 為什麼需要 JSON Schema Schema / Function Calling / Structured Output
• OpenAI DevDay 2026 預測 Structured Outputs 與 Agent 的舊口徑
• JSONSort 本地工具箱 格式化、校驗、Diff
• 全部文章 更多 JSON 與 AI 開發筆記

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