OpenAI Agents API 是什麼？怎麼計費、何時該用

OpenAI Agents API 是 OpenAI 在 2026 年 9 月 10 日推出、進入公開測試的代理開發介面，一句話定位：把 Codex 代理框架放進 OpenAI 的託管服務裡，session 管理、工作編排、上下文壓縮與失敗恢復都交給 OpenAI，你的程式則提供工具、選擇執行環境，並派任務、收事件。代理可以在沙箱裡執行程式碼、編輯檔案、連接 MCP 伺服器並產出生成物。計費未見獨立月費，帳單由三條線組成：模型 token 費、內建工具費、沙箱容器費，費率全部沿用平台既定價格。這些定位與計費原則都寫在官方的 Agents API 總覽文件，規格與數字以 2026 年 9 月中旬的文件與定價頁為準，這類服務改版快，動手前建議回官方頁面對一次現值。

它解決的是自建代理最磨人的那一層。自己用 Responses API 或 Chat Completions 組 agent loop 的人都知道，模型呼叫本身不難，難的是迴圈要自己轉、狀態要自己存、上下文爆了要自己砍、工具呼叫失敗要自己重試。Agents API 把這層基礎設施收走，官方的說法直白：OpenAI 管理 session、編排、上下文壓縮與恢復，你的程式提供工具並選擇執行環境。對產品團隊來說，這等於把代理平台最重的基礎工程換成一次 API 整合：官方對照表把 Agents API、Agents SDK 與 Responses API 的整合投入列為低、中、高三檔，這條路是最低檔，但派任務、處理事件與函式工具仍是自家程式的責任。

時點本身就是訊號。前一世的 Assistants API 已經在 2026 年 8 月 26 日關閉，官方指定的接班者是 Responses API 與 Conversations API，而 Agents API 是同一週期裡誕生的新選項，走得更遠：不只給工具，連代理的執行框架一起託管。對正在評估「代理功能要不要自建」的團隊來說，這是決策地圖上全新的一格，也正是接下來各段要拆解的對象。

閱讀路線可以按角色調整。開發者與技術主管重點看名稱地圖、計費結構與導入評估三段，那是做架構決策需要的部位。行銷與內容工作者若在評估代理自動化，功能拆解與成本試算兩段會給你具體的數字感。還不清楚 AI Agent 與一般聊天式 AI 差別的讀者，建議先讀AI Agent 的運作原理與適用情境再回來，後面的內容會順很多。

重點先看

• 定位：Agents API 把 Codex 代理框架變成託管服務，適合長時間執行、需要保留進度的任務。官方對三條產品線的整合成本評比是低、中、高三檔，Agents API 最低。
• 時間軸：2025 年 3 月 11 日 Responses API 與 Agents SDK 編排框架登場，2026 年 8 月 26 日 Assistants API 關閉，2026 年 9 月 10 日 Agents API 進入公開測試。
• 計費三本帳：模型用量按所選模型的 token 費率、內建工具按標準工具費率（網頁搜尋每千次 10 美元起）、託管沙箱按容器費率（1 GB 容器每 20 分鐘 0.03 美元），未見額外的平台月費。
• 環境三選一：不開沙箱、開 OpenAI 託管沙箱、或把自家的機器、容器或雲端沙箱接上來，三種模式對應不同的控制權與資安邊界。
• 資料限制：官方文件載明目前僅支援美國資料居留，且不支援零資料保留（ZDR），自架沙箱也不改變這件事，採購前務必過法務這一關。
• 現在就能做：到平台後台開一把具備 agents 讀寫與 responses 寫入權限的 API 金鑰，跟著官方快速上手文件，用一次 session 建立、串流事件的流程驗證整條路。

Agents API 在解決什麼問題：把執行層整包外包

先拆「託管 Codex 代理框架」這幾個字。Codex 背後有一套讓代理穩定工作的執行框架：跑指令、改檔案、管理上下文。Agents API 等於把這套框架抽成一個 API 服務，官方架構文件給它的定義是：一個 OpenAI 託管的 Codex 實例，負責執行模型與工具迴圈，並維護代理的 session。想更認識 Codex 這個產品本身的讀者，可以搭配Codex 代理寫程式工具的完整解析。

架構上只有三個角色。Harness 是 OpenAI 那端的框架實例，跑模型、跑工具迴圈、顧 session。Environment 是代理跑指令與操作檔案的地方，可以是遠端沙箱、你的筆電、Docker 容器，或 AWS Lambda 函數。Application server 則是你寫的程式，負責派任務、收事件、處理函式工具呼叫，如果環境自己管，還要負責環境的生命週期。三者用 API 與事件流串起來，責任邊界畫得很清楚，出問題時找碴的對象也明確。

自建派的人聽到「外包執行層」最想問的是：框架到底代管了哪些事？官方總覽列了七項：在沙箱裡執行指令與程式碼、套用相關技能與指示、透過工具或 MCP 連外部資料、在代理工作時中途導正它、把先前的工作做摘要以管理上下文視窗、把工作拆成子任務並派給子代理、從上次中斷的地方繼續 session。這串清單就是自建迴圈時你要自己寫、自己測、自己顧的清單，現在變成服務的一部分。

其中「上下文壓縮」值得展開，因為它是長任務的生死線。代理工作越久，累積的對話、工具結果與檔案內容越多，遲早會撞上模型的上下文視窗上限。自建的做法是手動截斷歷史或自己寫摘要邏輯，砍太狠代理失憶，砍太輕照樣爆框。託管框架把這件事變成內建行為：對先前工作做摘要以管理上下文視窗，並保留 session 讓任務可以從中斷點繼續。對會跑幾十分鐘甚至更久的任務來說，這兩項能力決定了它能不能真正交給雲端跑，而不是每半小時回來人工重開一次。

代價同樣明白。你對迴圈內部的直接控制變少，usage 紀錄是盡力而為（best-effort），未知時可能是 null，已記錄的數值也可能變動，帳單估算變成你自己的功課。官方也給了另一條路：Agents SDK 讓應用程式控制部署、儲存、核准與執行環境整合，重視這些控制點的團隊可以往那邊評估。託管與控制之間的取捨，後面導入評估段會給一組具體判準。

「長時間任務」講起來抽象，官方總覽直接列了五個完整範例應用，可以當需求檢核表用。事件回應代理：調查告警並請求核准恢復動作。Slack 機器人：用連上的工作場所工具調查請求。資料分析師：用唯讀 SQL 回答資料倉儲的問題。GitHub 議題調查員：重現回報的錯誤並把發現貼回 GitHub。文件審查員：用政策技能與專家代理審查文件。這五個案例涵蓋告警調查、工作場所工具、唯讀 SQL、錯誤重現與文件審查，其中事件回應代理會在恢復動作前請求核准，正是託管框架的甜蜜點。拿自己的需求跟這張表對照，重疊度高就值得認真評估。

名稱地圖：Agents API、Agents SDK 與 Responses API 的分工

OpenAI 的代理產品線名稱很容易讓人混淆，先把時間軸拉直。2025 年 3 月 11 日，OpenAI 發布 Responses API 與一組內建工具（網頁搜尋、檔案搜尋、電腦操作），同時推出 Agents SDK 編排框架，並宣布 Assistants API 的功能將逐步搬進更好用的 Responses API，預定 2026 年日落。接下來一年半是遷移期，Assistants API 在 2026 年 8 月 26 日正式關閉，官方汰役頁指定的替代品是 Responses API 與 Conversations API。

Agents API 則是 2026 年 9 月 10 日才在官方 changelog 上出現的條目：以託管 Codex 為核心的公開測試服務，用持久 session 跨回合延續工作、串流回報進度、接上你自己的工具與 MCP 伺服器，沙箱可以用 OpenAI 託管的，也可以從自家基礎設施或支援的供應商接入。所以今天講「OpenAI 的代理開發」其實有三條路：Agents API 走託管、Agents SDK 走自建框架、Responses API 走最原始的模型呼叫。官方的執行環境比較頁給過一張對照表，直接中文化如下。

↔ 左右捲動檢視完整表格

面向	Agents API	Agents SDK	Responses API
適合場景	長時間執行、由 OpenAI 管理代理並保存進度的任務	在自家程式裡用自訂工具與工作流組代理	直接呼叫模型，或從零自建代理
代理跑在哪	OpenAI 託管的 Codex 框架	SDK 跑在你的應用程式內	你的應用程式，可選用託管編排
整合投入	低	中	高
管理方式	由 OpenAI 管理底層代理基礎設施	由應用程式控制部署、儲存、核准與執行環境整合	由應用程式直接呼叫模型或從零建立代理

選型時回到表格的情境欄：長時間執行且由 OpenAI 管理並保存進度的任務用 Agents API，在自家程式裡以自訂工具與工作流建立代理用 Agents SDK，直接呼叫模型或從零建立代理用 Responses API，三條路的整合投入對應低、中、高。三條路也不必單選：外部資料處理交給託管代理、核心交易邏輯留在自家迴圈，是可想像的分工。狀態管理的責任也跟著路線移動：Agents API 幫你保存 session 設定、回合與項目，SDK 路線的狀態在你家儲存與 SDK session 裡，Responses 路線則是手動管理歷史或對話狀態，這一格在遷移成本試算時常常被低估。

名稱地圖上還有一個容易踩到的地雷：Agent Builder，2025 年 10 月 DevDay 上以視覺化多代理工作流工具之姿登場，2026 年 6 月 3 日官方宣布汰役，預定 2026 年 11 月 30 日關閉，遷移指引指向 Agents SDK 與 ChatGPT Workspace Agents。ChatKit 在同一份公告裡則載明繼續提供。公告對它只有這一句，名稱相近但定位要另行查證，不宜放進同一個比較維度。一個產品從登場到宣布退場只活了八個月，這件事本身就是評估這條產品線時該記住的背景。

歷史包袱也要處理。檢視舊資料時先核對產品名稱與日期：Responses API 與 Agents SDK 於 2025 年 3 月 11 日發布，託管的 Agents API 到 2026 年 9 月 10 日才進入公開測試，凡寫在這個日期之前的「Agents API」字樣，指的不會是這個託管服務，名稱對映要自己重排一遍。

四個核心概念與一個 session 的生命週期

官方總覽把 Agents API 收斂成四個概念。Agent 是模型、指示、工具與 MCP 伺服器的組合，定義這個代理是誰、能做什麼。Environment 是選配的沙箱或機器，代理在裡面碰檔案、載入技能、跑指令。Session 是代理的一個持久執行實例，承接任務與輸入。Events 與 items 則是送進代理的輸入與過程中產出的內容。設定面的四個旋鈕也一目了然：模型決定誰做事，指示決定怎麼做，工具決定能做什麼，推理與輸出設定決定想多深、答成什麼樣。

一個 session 從頭到尾走四步。建立 session 時設定代理，OpenAI 同步供應它的環境。送進第一個任務，使用者輸入會在環境就緒後啟動一輪工作。接著追進度，用串流或 webhook 得知代理何時完成、何時需要你。之後繼續派任務給同一個 session，或在工作進行中下指導棋。官方 session 文件對「回合（turn）」的定義很精確：閒置 session 收到訊息會開新回合，進行中收到訊息則是轉向（steer）那個回合，回合非同步執行。

串流打開後會看到一串很有節奏的事件：環境連線建立、回合建立、回合進行中、項目加入、輸出文字的增量片段、回合完成、session 回到閒置。這串事件流在 session 閒置時保持開啟，排隊中的工作不會漏接。把它映射到產品介面上，使用者看到的就是「代理正在讀檔案、正在跑指令、正在寫結論」的即時進度條，體驗設計的原料都在這裡。

判斷回合結果要看事件，不能只看閒置狀態。官方列出的三種結局是 completed、failed、cancelled，文件特別提醒兩件事：session 閒置不代表回合成功，回合完成也不代表每個工具都成功，輸出內容仍要檢查。這兩句話寫進你的錯誤處理，能少踩很多坑。session 若在等函式結果或環境連線，回頭查 required_actions 就知道下一步該做什麼。

代理設定本身可以拋棄式也可以保存。建立 session 時直接帶入設定，用完即丟。或先用 agents 資源存一個代理，之後每個 session 用 agent_id 引用同一組設定。官方設定文件對兩者的分工講得很白：session 放對話與工作，保存的代理放可重用的設定。團隊協作時把指示與工具清單版本化在保存的代理上，比散落在各處的程式碼好管理，改版也有單一事實源。

功能拆解：環境、多代理、工具與觀測

環境三選一：不開沙箱、託管沙箱、自架沙箱

Environment 的第一個選項是不開。environment.type 設成 none，適合回答問題、用工具接外部服務但不跑指令、不碰本機檔案的代理。這個模式下 harness 仍可直接呼叫遠端 MCP 工具，函式工具則由你的程式接住每次呼叫再回傳結果。有得有失：內建的 Bash 與 apply-patch 工具、工作區檔案、執行器 MCP 都用不了。純問答與查資料的場景，從這裡起步少了容器費這本帳，等到任務真的需要碰檔案或跑程式再升級環境。

第二個選項是 OpenAI 託管沙箱。官方託管沙箱文件給它的是一個預裝 Python、Node.js 與命令列工具的 Linux 工作區，每個 session 有各自的工作區，檔案在沙箱存活期間跨回合保存。設定項目相當務實：packages 可以指定 Python、系統或全域 npm 套件並鎖版本，例如 pandas==2.2.3。setup_commands 在代理開工前跑前置指令。files 用 Files API 或 base64 餵輸入檔案。env 設字串環境變數，但 PATH、CODEX_ 開頭與 OPENAI_API_KEY 這些執行期保留名稱會被拒絕。

執行順序與失敗處理也定義清楚：套件與輸入檔案會在設定指令之前備妥，設定指令回傳非零值會直接阻止代理啟動，等於內建一道前置檢查。環境狀態用 environment 端點查，provisioning 代表設定進行中，connected 代表就緒，失敗時從 agent.session.environment.failed 事件裡的 environment.error 讀原因。要在 connected 之後才對 live 檔案做新增或列表，太早動作只會撞到還沒準備好的工作區。

網路出站是資安審查的重點，託管沙箱給三段開關：enabled 放行（預設）、disabled 全擋、restricted 只允許清單上的主機。restricted 模式接受 1 到 100 個精確主機名稱，不收萬用字元、通訊協定、路徑或連接埠，子網域與轉址目的地都要各自列名。要留意託管的 stdio MCP 伺服器目前要求 enabled 的網路設定，用 restricted 清單時這條路走不通，需要 stdio 型 MCP 的任務要另想辦法。

檔案生命週期同樣有明確規則：回合完成時，/workspace/outputs 下的檔案會發布成不可變的生成物，沙箱過期後仍可下載。沙箱在活動與 keep-alive 停止一小時後可能被刪除，這個逾時不可設定，所以該存的輸出要即時帶走，把沙箱當永久儲存會摔得很痛。

第三個選項是自架沙箱，對應需要自家基礎設施、私有網路或特定軟體的場景，環境可以是筆電、容器或遠端沙箱。連線機制在官方自架文件裡講得很具體：你在環境裡跑 codex exec-server 這個執行器，它用環境 ID 和一把受限 API 金鑰向 API 註冊，再經 WebSocket 收命令、回結果，連線全程對外發起，掉線會自動重連。防火牆要放行兩個目的地：api.openai.com 供註冊，codex-cloud-environments.chatgpt.com 供命令往來。金鑰設計有個乾淨的細節：代理產生的程式碼看得到這把環境金鑰，但它只能連接環境，無法授權任何其他 API 操作，應用程式主金鑰則永遠不要放進沙箱。環境金鑰要在平台後台的 Agents 分頁單獨建立，隸屬於跟 session 相同的組織、專案與帳號，其他權限全部設成無。

自架環境的維運責任在你這端，官方的建議值得抄下來：按使用者或工作負載隔離環境，因為共用環境的代理看得到同樣的檔案、憑證與資源。備妥代理需要的檔案與相依套件、管理連線生命週期、在停止運算前協調好還在排隊的工作並確認沒有執行中的事項，這些是自架路線的隱藏成本，換到的是自家基礎設施、私有網路與自訂軟體的選擇權。

多代理協作：子代理與並行

把 multi_agent.enabled 打開，主代理就能把任務派給子代理。官方多代理文件的描述是：每個子代理有自己的上下文，可彼此並行，主代理協調並合併結果。工具不用自己宣告，框架會供應建立、傳訊、等待與中斷子代理的工具組，max_concurrent_subagents 可以限制並行數。給每個子任務一個清楚的問題與預期產出，是官方反覆強調的使用紀律。

什麼時候該派子代理，官方給的判準是任務獨立性：分頭審不同文件、分頭查不同故障原因，這類互不依賴的工作適合並行。短任務與有相依關係的步驟留在主代理，會編輯同一批檔案的代理則必須協調彼此的變更。這條界線畫錯，輕則浪費 token，重則兩個代理改同一個檔案互相覆蓋，併發的好處直接變成災難。

工具與 MCP：三種接外部能力的方式

代理取用外部能力有三條路。內建服務工具直接開，例如網頁搜尋（web_search）。MCP 伺服器用一個 mcp 工具設定掛上，指定 server_label 與傳輸方式即可，官方自己的文件站就提供 MCP 端點當範例。函式工具則把控制權留在你手上：框架把呼叫事件丟給你的程式，你執行完回傳結果，代理等著繼續。再加上程式化工具呼叫（programmatic tool calling），工具協作的形態算齊。對 MCP 協定本身不熟的讀者，先看MCP 如何讓 AI 串接外部工具與資料。

實務上這幾種工具可以搭配使用。查公開資訊開網頁搜尋、連內部知識庫掛 MCP、動自家業務系統走函式工具，而官方總覽的範例代理本身，就同時掛了網頁搜尋、MCP 與程式化工具呼叫。要留意的只有成本與可用性：每種工具的計費規則不同（後面計費段展開），而函式工具的處理器沒回應時，代理會停在那裡等結果，你的服務可用性設計要跟上，不然代理的穩定性被你的服務拖累。

進度與觀測：事件流、webhook 與後台

追蹤進度有兩條互補的路。串流（streaming）即時收到代理工作中的細部事件，適合把過程顯示給使用者看。Webhook 則在 session 狀態變化時收到簽名的 HTTP POST，不必一直開著事件流，官方支援的事件涵蓋建立、需要動作、處理中、閒置與失敗五種，其中需要動作的事件會標明是函式呼叫還是環境連線，你的處理器再回頭查細節。背景工作排程用 webhook，前台體驗用串流，兩者可以並存。

事後稽核靠平台後台與用量紀錄。官方用量與觀測文件指的路是：到平台後台的 logs 頁切到 Agents 分頁，用 session ID 就能檢視回合、工具呼叫與子代理。Turn 資源會附上盡力而為的 usage 欄位與 subagent_id，可用來把指令歸因到特定子代理，把殼層指令的執行者找出來。兩個限制要先知道：usage 可能是 null，不代表用量為零。詳細的追蹤（trace）取得與外部追蹤匯出不在公開測試 API 的範圍內，企業級觀測管線要另想辦法或等後續開放。

錯誤處理與可靠性：把官方的提醒當規格看

託管不代表免操心，官方文件裡散落的可靠性提醒，集起來就是一份錯誤處理規格。失敗事件有家族：turn 層級的 failed 與 cancelled、session 層級的 failed、環境層級的 environment.failed，以及通用 error。串流邏輯至少要對這五種做分岔，判斷是重試、回報還是放棄，把它們全部當成普通事件印出 log，故障排除時會沒有施力點。

你的程式自己也是失敗點。官方架構文件點名兩種情況：函式工具的處理器不在時，代理會停在原地等結果。事件或生命週期處理器出錯，會中斷進度更新或環境管理。換句話說，代理系統的可用性是你的服務與託管框架的乘積，應用程式端的處理器同樣需要監控與備援，這種跨邊界故障要在設計期就想好降級路徑。

清理階段也有規則。任務結束刪 session，官方把刪除定義為請求沙箱清理的動作。刪除時收到 409 代表設定或執行還在收尾，等一下再重試，並限制重試次數。關掉事件流不會取消任務，這點跟直覺相反，使用者關掉進度頁面後任務仍會繼續，後續的進度與結果要回到 session 追蹤。

環境層有一個明確的逾時條件要放進監控：託管沙箱在活動與 keep-alive 停止一小時後可能被刪，逾時不可設定。自架環境的停止時機雖由自己掌握，官方也要求在停止運算前協調好排隊中的工作並確認沒有執行中的事項。這個數字不顯眼，但對成本與任務存活率的影響比多數參數都大。

帳務核對的紀律也要一併建立。回合與 session 資源上的 usage 是盡力而為，數字可能晚到也可能修正，官方明講這些紀錄不是最終帳單。務實的做法是把 usage 當趨勢指標用：看單位任務的 token 曲線、快取命中比率的變化、子代理佔比，再定期跟平台帳單對總數，兩邊對不上的月份就是回頭查設定或任務形態的時候。把帳務核對當成上線後的例行工作，而不是出事才做的鑑識。

計費結構：三本帳各自獨立

計費是這類服務最容易失準的部位，先給結構再給數字。官方總覽的計費段落只有三句話：模型用量按所選模型的 API 費率、OpenAI 工具按標準工具費率、託管沙箱按標準容器費率。換句話說，目前未見為 Agents API 另立的平台月費，帳單是三本帳加總，而每本帳的費率都跟平台其他介面共用，查官方定價頁就能對帳。

第一本帳是模型 token 費，價格隨模型差異極大。以 2026 年 9 月定價頁的標準費率為準，每百萬 token 計價：gpt-6-astra 輸入 10 美元、快取輸入 1 美元、輸出 50 美元。gpt-5.6-sol 輸入 4 美元、輸出 20 美元。gpt-5.6-terra 輸入 2 美元、輸出 12 美元。gpt-5.6-luna 輸入 0.2 美元、輸出 1.2 美元。長上下文另有費率，例如 astra 的長上下文輸入 20 美元、輸出 75 美元。對模型規格有興趣的讀者可以搭配GPT-6 Astra 的實力與費用解析。要留意 gpt-5.6-sol 目前是促銷價，官方標注至少適用到 2026 年 11 月 21 日，長約採購要把這個日期放進去。

三本帳之一：模型 token 費的兩個細節

推理 token 按輸出計價，代理想得越深、帳單越厚。完成一個任務的過程裡，模型可能被呼叫多次，每次都依模型 token 費率與快取規則計價。輸入端的組成也很肥：代理指示、工具定義、對話歷史、使用者輸入、檔案影像與工具結果全算輸入，其中對話歷史與工具結果會隨回合累積，長任務要特別把這一項算進去。

模型選擇因此是第一個成本槓桿，四個型號的價差拉得很開：同樣的 token 量，astra 的輸入單價是 luna 的五十倍，輸出單價超過四十倍。換模型等於直接改寫模型帳的費率：導入時以實際任務的用量乘上對應費率估算，價差才會落在具體數字上。不同型號的用量形態是否相同，要用試點任務實測來回答。

快取輸入按快取費率計（大約原價一折），但官方用量文件提醒三件事：維持 session 不保證快取命中，命中取決於前綴匹配與模型的快取規則。快取輸入仍要計費，快取命中率高不等於總成本省下來。部分模型另有寫入快取的費用，而 Agents API 的 usage 欄位沒有分開揭露這個計數，精確對帳時會差一段。提高命中的實務做法官方也有給：指示與工具定義保持穩定，把新的任務細節放進後續訊息，讓前綴有機會重用。

三本帳之二：工具費

網頁搜尋每千次呼叫 10 美元，搜尋內容 token 併入模型費率計價。非推理模型用的搜尋預覽版是每千次 25 美元，但搜尋內容 token 免費，兩種定價邏輯不同，換模型時要重算，不是誰貴誰便宜的直觀題。檔案搜尋的呼叫費是每千次 2.5 美元（官方註明此費率適用於 Responses API），儲存每天每 GB 0.1 美元、首 GB 免費。還有兩個小字但重要的註解：gpt-4o-mini 與 gpt-4.1-mini 搭配非預覽版搜尋時，每次呼叫固定計 8,000 個輸入 token。GB 在官方定義裡是二進位 GB（GiB），儲存量換算時別用十進位硬算。

三本帳之三：託管沙箱的容器費

容器費按規格與時間計：1 GB 容器每 20 分鐘 0.03 美元，4 GB 是 0.12 美元，16 GB 是 0.48 美元，64 GB 是 1.92 美元。符合資格的容器 session 以分鐘計費、每次最低收 5 分鐘。這本帳跟模型帳是平行時空：代理思考一小時不開沙箱不收容器費，開著沙箱發呆照樣跳表。短任務批次跑的場景，把任務排緊、用完就刪 session，容器費可以壓得很低，反過來掛一整天的閒置沙箱就是純浪費。

成本怎麼估：一筆試算走完整流程

官方用量文件給的成本觀念是：一個任務可能包含多次模型呼叫，估成本要把完成任務所需的全部呼叫加總，子代理與重試都要算進去，再加上工具、沙箱運算與第三方服務的費用。這句話翻成白話：代理的成本單位是「任務」不是「請求」，單次呼叫的成本直覺蓋不住整個任務的帳。

用一個具體情境試算一遍，數字全部來自上一段引的費率。假設一個資料整理任務用 gpt-5.6-terra，過程包含 6 次模型呼叫，每次平均輸入 40,000 token，其中 30,000 命中快取，輸出每次 2,000 token，並開一個 1 GB 託管沙箱跑 40 分鐘，期間呼叫網頁搜尋 3 次。模型帳：未快取輸入共 60,000 token，乘上每百萬 2 美元是 0.12 美元。快取輸入 180,000 token，乘上每百萬 0.2 美元是 0.036 美元。輸出 12,000 token，乘上每百萬 12 美元是 0.144 美元。小計約 0.30 美元。工具帳：3 次搜尋是 0.03 美元。容器帳：40 分鐘是兩個 20 分鐘單位，0.06 美元。三本帳合計約 0.39 美元。

同一個任務換 gpt-6-astra 跑，模型帳會變成：未快取輸入 0.60 美元、快取輸入 0.18 美元、輸出 0.60 美元，小計約 1.38 美元，是 terra 的四倍多。用意只在示範估價方法，模型評比是另一回事：先把任務的呼叫次數、每次的輸入輸出規模、工具次數、沙箱時長四個變數量出來，再乘上費率表，數字自己會說話。真實導入前，用小流量跑一週真實任務記錄這四個變數，比任何估算都可靠。

費率結構還有兩個背景知識。定價頁上同型號另有 Batch 與 Flex 費率表（約標準價五折）與 Fast mode（約兩倍），Fast mode 是 2026 年 7 月 30 日從 priority processing 改名而來，這些屬於平台級費率結構。Agents API 的 session 是互動式服務，文件未將它列入批次類端點，離線批次需求要另行確認適用性。還有一項加價規則：2026 年 3 月 5 日後發布且支援資料居留的模型，走區域處理端點會加收一成，多區域部署的團隊記得把這項放進試算表。

導入評估：五個要先回答的問題

功能與計費都清楚了，決策剩五個問題。第一，任務形態對不對？官方對 Agents API 的定位是長時間執行、需要保存進度的任務。一問一答的客服、單次摘要、固定流程的自動化，在官方對照表裡更接近「直接呼叫模型」的場景，可先評估 Responses API 是否已經夠用。判斷的參考很簡單：這個任務需要多步驟、需要中途回報、需要在中斷後續跑嗎？三個都否，代理框架的必要性就值得再多問一輪。

第二，資料邊界能不能過？官方總覽載明兩個硬限制：目前僅支援美國資料居留，且不支援零資料保留（ZDR），自架沙箱也不會讓這兩項改變。對台灣的企業來說，這代表要走內部法務與資安審查：任務資料能不能出境美國、個資法與產業法規的約束、以及合約面對零保留要求時的處理方式。這關過不了，後面都不用談。過得了，也要把資料分級寫進任務設計。敏感等級高的內容走函式工具時要記得：處理雖然留在自家，結果仍要回傳給代理，會進到服務的資料邊界內，這部分要依美國資料居留與無 ZDR 的限制一併審查，只把公開級資料交給託管代理。

第三，控制權要不要留？把迴圈交給託管框架，換到的是低整合成本，付出的是對執行細節的直接控制。需要自訂核准流程、把狀態留在自家資料庫、對執行環境有合規要求的團隊，Agents SDK 把部署、儲存、核准與執行環境整合的控制權交給應用程式。折衷方案也存在：Agents API 跑外部任務、敏感邏輯留在自家服務，用函式工具當橋，兩邊各取所需。判斷時可以拿環境三選一當籌碼盤點：能用 none 模式解決的場景，控制權的讓渡其實很小，需要 openai_hosted 沙箱的場景才開始認真考慮資料與執行邊界，走到 self_hosted 則是把執行環境放到自家基礎設施，但 session、編排、上下文壓縮與恢復仍由 OpenAI 管理。

第四，成本治理怎麼做？代理的成本特性是變異大：同一個任務，呼叫次數、推理深度、重試次數都會讓帳單浮動，而 usage 又是盡力而為的紀錄，不能當最終帳單看。可操作的做法包括：為任務選擇夠用的模型、把指示與工具定義保持穩定以提高快取命中、限制子代理並行數、沙箱用完即刪、保留實際任務的用量紀錄並按任務檢視。上量之前先用試點任務把單位成本量出來，報價與預算才有依據。

第五，觀測與錯誤處理是否備妥？usage 是盡力而為的紀錄，公開測試 API 尚不提供追蹤取回與外部追蹤匯出，回合完成也不保證每個工具都成功，團隊需要有人檢查代理輸出、處理失敗與取消事件。代理導入也不是純 API 串接，工具設計、資料準備與流程重塑都要人力承接，想看相關職務的工作樣貌，可以參考FDE 前線部署工程師的工作內容；團隊若沒有這類人力，先從一個小場景試點，或把外部支援納入評估。

五問過完，還要對產品線的變動節奏保持自覺。Agents API 本身是公開測試：請求要帶 OpenAI-Beta: agents=v1 表頭、追蹤匯出尚未開放。往前看，Agent Builder 從登場到宣布退場只活了八個月，Evals 平台也在 2026 年 6 月宣布汰役。這段不是唱衰：把「介面會變」當成設計輸入，把對 Agents API 的依賴收斂在薄薄的整合層，業務邏輯與資料留在自己手裡，正式環境的關鍵路徑等穩定版再上，是比較穩健的節奏。

上手路徑：跑起第一個 session

實際動工的前置很輕。到平台後台建立一把應用程式 API 金鑰，授予 api.agents.read 與 api.agents.write 供 session 操作，加上 api.responses.write 供模型推理，這組權限組合是官方快速上手文件明列的最低要求。金鑰放環境變數，永遠不要帶進代理的沙箱。用 cURL 直呼 API 時記得補上 OpenAI-Beta: agents=v1 表頭，官方 SDK 會自動加。

官方 quickstart 的第一個練習設計得很好：讓代理在託管沙箱裡寫一支 tree.py，執行它，把目錄樹印回來。這一題會走完建立 session、串流事件、看見沙箱執行的完整循環，OpenAI 同時管理代理、對話與沙箱。Python、JavaScript、Go、Java、Ruby 五種語言的範例都在文件上，挑熟悉的抄即可，跑通的判定就是事件流裡出現回合完成與沙箱裡實際執行過的輸出。

跑完之後養成兩個習慣。其一，把 session ID 存進你自己的對話狀態，後續追問與檢視都靠它。其二，任務結束就刪 session，官方文件把刪除視為請求沙箱清理的動作，刪除時收到 409 就等一下再重試，並限制重試次數。關掉事件流不會取消任務，這點跟直覺相反，要特別記。

下一步的擴充路線圖：先把環境從託管沙箱換成 none 觀察成本變化，再掛一個 MCP 伺服器試內部資料，然後開 multi_agent 試子代理並行，過程中在後台 logs 的 Agents 分頁對照每次的回合與 usage。走完這一圈，你對託管代理的四個概念與三本帳會有手感，屆時再回頭看導入評估那五個問題，答案會具體得多。

常見問題