Agents API 是什麼？功能、費用與導入指南

Agents API 是 OpenAI 提供的 AI 代理服務介面，讓開發者把能使用工具、處理檔案、連續執行任務的 AI，接進自己的網站、App 或公司系統。OpenAI 負責管理背後的 Codex 任務執行流程；你的程式負責交辦工作、提供資料與工具，並接收結果。

例如，你想在公司後台放一個「製作行銷月報」按鈕。按下後，AI 取得指定資料、執行計算、找出異常，再產出報告檔案，這就是可以用 Agents API 設計的工作流程。它的價值，在於讓一段需要多個步驟的工作，能在產品裡持續推進。

不過，資料連接、執行權限、費用控制與成果驗收，仍需要團隊設計。下面從它的運作方式開始，說明與 Responses API、Agents SDK 的差別，再用月報案例拆解導入步驟。本文討論的是 OpenAI 的特定產品，其他公司的同名服務需另外比較。

---

Agents API 是什麼？把 AI 的工作能力接進產品

API 是供程式使用的介面。使用者在網站上按按鈕，或向聊天機器人提出需求，背後的程式就能透過 API 把任務交出去，再把結果顯示在自己的產品裡。使用者不必親自操作開發者介面。

Agents API 的核心是 OpenAI 管理的 Codex harness。Harness 在這裡可以理解為「讓模型持續工作的執行系統」：它負責模型與工具之間的循環、保存工作紀錄、協調任務，以及整理過長的上下文。這是 OpenAI 對 Agents API 的正式定位。

把模型想成能分析問題的人，harness 就像他工作的流程與工具環境。模型判斷下一步要查什麼，系統負責安排呼叫、接回結果，讓模型接著處理。單純換一個更強的模型，不會自動補齊這些工作流程。

這個比喻也有界線：AI 的判斷可能出錯，執行系統不能保證每個工具都成功。企業仍要定義哪些結果算完成，以及什麼情況要交回人處理。若想先理解代理如何拆解目標，可搭配Agentic AI 的運作與應用。

對企業而言，Agents API 適合評估的問題是：「我們能否把一段需要理解、查詢、處理與修正的工作，整合成產品能力？」它可以用於文件審閱、資料分析、客服草稿或程式調查，實際能做多少，取決於模型、工具、資料與權限的組合。

---

Agents API、Agents SDK、Responses API 差在哪？

這三個名稱最容易混在一起。它們都能參與 AI 代理開發，主要差別是：誰管理代理的執行流程，以及你的程式需要掌握多少細節。OpenAI 的 Agent 執行方式比較，也以這個分工區分三者。

Agents API 讓 OpenAI 管理 Codex harness 與持續的工作 session。你可以把心力放在任務、資料、工具與產品體驗上，但仍要做好外部系統整合、權限與成果保存。

Agents SDK 是協助開發代理的程式函式庫。它的 runner 可以處理模型與工具循環、代理交接等工作，執行位置與應用整合由開發者掌握。SDK 也有 session 與追蹤能力，不能把它理解成「所有事情都要從零自己寫」。詳見 Agents SDK 文件。

Responses API 提供更直接的模型回應介面，也支援工具與對話狀態等能力。如果你只要辨識文件、摘要一段文字，或需要自己控制整合流程，它仍然是可用選項。把它說成「只能一問一答」，會低估它的功能。

例如，一個固定把客服來信分成五種類別的功能，可能直接呼叫模型就足夠；一個需要反覆查訂單、閱讀政策、追問缺件的客服助理，才更值得評估完整代理流程。這是依工作型態提出的選擇方向，實際開發量還要看現有系統。

Agents API 與 Codex 也有關係：前者開放由 OpenAI 管理的 Codex harness 給程式使用。你不應據此推定，自己在 Codex 桌面應用裡的對話、外掛、檔案或帳號設定，會自動出現在新建的 API session；這些資源都要依 API 的配置方式接入。

---

它怎麼運作？先看設定、工作紀錄與執行環境

理解 Agents API 不需要先背完整規格，但要分清楚三件事：Agent 保存工作設定，Session 保存這次工作的脈絡，Environment 提供執行程式與處理檔案的位置。把它們混為一談，之後就容易誤判記憶、隔離與保存方式。

Agent 是可重用的工作設定

Agent 的設定包含模型、指令、可用工具與輸出要求。你可以為「行銷分析助理」設定工作原則，例如只分析提供的期間、數字必須能追到資料、不把相關性寫成因果。

同一份設定可以用在不同 session。依 Agent 配置文件，各 session 有自己的對話與工作；共用 Agent 設定，不等於自動共用所有客戶的工作紀錄。

Session 是能繼續交辦的工作紀錄

Session 可以理解為一次持續的合作。你先請助理製作月報，收到後補充「請把自然搜尋與廣告拆開」，便能在同一個 session 接著做，不必每次重新建立整段對話。

其中一輪工作稱為 turn。當 session 閒置時，新訊息會開始下一輪；當它正在工作時，新訊息可以引導目前這一輪。程式可以透過串流接收過程，也能用 webhook 接收狀態通知。詳見 Session 的執行與延續方式。

長任務也會碰到上下文長度限制。系統可以整理前面的資訊，讓工作繼續，但不應把它理解成無限、逐字且永不遺漏的記憶。對結果重要的資料、條件與成品，應有可重新讀取的保存方式；這也與上下文工程的問題相連。

Environment 決定程式與檔案在哪裡處理

如果任務需要跑 Python、整理 CSV 或輸出報告，就要提供適合的執行環境。OpenAI 文件列出三種選擇；這裡的「環境」指工具與程式工作的地方，不等於模型部署位置。

最容易誤解的是自架環境。你可以讓程式在自己的基礎設施工作，但 Agents API 架構文件說明，harness 仍由 OpenAI 執行。自架環境不代表整套服務離線運作，也不代表模型已經搬進公司內部。

自架還多了維運責任：算力如何啟動、連線中斷如何恢復、檔案如何保存，以及何時關機，都需要處理。若使用自己的電腦作為執行環境，電腦關機後也不能期待原本的程式繼續跑。詳見 自架環境說明。

---

用行銷月報看懂 Agents API 的工作流程

假設一家公司的後台，要提供「上傳資料後產生月報」的功能。以下是教學用的流程設計，並非特定客戶的實測成果。先從已匯出的 CSV 開始，也比較容易確認數字是否正確。

第一步：把任務與驗收標準說清楚

「幫我做月報」太寬。更完整的需求可以是：比較指定兩個月的流量與轉換，列出變動最大的頁面，附計算方法，最後交付一份 HTML 報告；缺資料時先列出缺口。

例如，若匯入的資料只有網站流量，助理就不能直接推定營收變化。把成功條件寫清楚，能讓後續驗收有依據，也避免產出一份看似完整、實際混入猜測的報告。

第二步：提供資料與合適的工具

開發者可以把輸入檔提供給 OpenAI-hosted 環境，或透過已授權工具讀取資料。託管環境可配置 Python、Node.js、套件與網路存取，讓代理執行資料清理和計算。功能與設定方式見 OpenAI-hosted sandbox 文件。

若只需要兩份月報 CSV，就先提供這兩份檔案，不必一開始開放公司所有資料庫。之後要改成自動取數，再評估資料來源、使用者身分、查詢範圍與供應商費用。

第三步：接收進度，處理中途需要的資訊

任務開始後，代理可能先檢查欄位，再計算差異、整理重點。如果發現兩份資料的日期範圍不一致，應回報問題；如果需要執行由公司提供的函式，應用程式必須處理呼叫並回傳結果。

因此，前台除了顯示「正在產生」，也應能呈現需要補件、工具失敗與完成等狀態。Webhook 可以通知程式狀態變化，但詳細的待辦參數仍可能需要再讀取 session。可參考 Session webhook 文件。

第四步：驗證並保存真正的成品

月報產出後，驗收不只看文字是否通順。還要核對期間、分母、加總方式、資料缺漏與檔案能否開啟，並把最終檔存到公司自己的儲存空間。涉及對外分享時，再確認收件對象與版本。

OpenAI-hosted 環境可將指定輸出目錄中的檔案保存為 artifacts，供程式下載。這讓你的產品能交付真正的報告檔案；至於放哪個位置、如何列出與下載，應依 檔案與 artifacts 文件實作。

---

---

接上 MCP、Skills 與多代理，能增加哪些能力？

前面的月報案例只靠檔案與程式，就可以開始。當需求擴大到即時查詢、多份文件或不同專業分工時，才需要進一步設計工具與代理。這些能力的分工不同，不能只靠安裝一個外掛就全部補齊。

MCP 與函式工具，負責接到真正的資料與操作

MCP 可以讓代理連接外部工具，例如查詢文件或訂單。Agents API 可由 OpenAI 端連接可達的遠端 MCP，也能讓連接發生在 session 的環境中；私有網路能否連到，要依實際連接位置判斷。詳見 MCP 連接方式。

另一種做法是函式工具：模型提出要呼叫哪個功能，你的程式執行後回傳結果。例如公司自己提供「取得指定月份報表」的函式，真正的資料權限與商業規則仍由後端檢查。

兩者都需要有真正的資料來源，並完成認證與授權。若想理解「公司 API」與「提供給 AI 的 MCP 工具」如何合作，可以延伸閱讀MCP vs API 的差異與使用情境。

Skills 與 Plugins，讓工作方法可以重用

Skill 可以保存一套可重用的工作指引，例如分析月報的步驟、品牌格式與檢查規則；Plugin 則能把 skills、MCP 設定或兩者一起打包。你可以把它理解為工作方法與工具配置的組合。

這些能力要依環境載入，不能假設桌面上已安裝的項目會自動出現在 API 裡。Plugin 文件也提醒，更新外掛檔案或模板後，既有 session 不會自動重新載入工具，要用新 session 驗證更新。

多代理適合拆開獨立工作，但仍要協調

你可以讓一個子代理分析自然搜尋，另一個分析廣告，再由主代理整合。這類能各自完成、最後再合併的工作，較適合分工；必須先等前一步結果才能做的步驟，則未必適合平行處理。

子代理各有上下文，但在使用環境時會共用檔案系統。如果兩個代理都修改同一份報告，仍可能互相影響。應事先分配輸出檔案或修改範圍；增加代理數也不保證更快或更省。

工具支援還有差異：OpenAI 的 多代理文件目前說明，子代理可繼承 MCP、網路搜尋等設定，但不支援 function tools。設計前要核對工作需要的工具，不能直接假設主代理有的，子代理都能用。

---

Agents API 費用怎麼算？先拆開四層成本

Agents API 的成本不能只看「送出幾次任務」。一個月報任務可能包含多次模型推理、工具呼叫與程式執行；同一任務補充資料後再重做，也可能增加用量。

依 Agents API 計費說明，模型依所選模型的 API 費率計費，OpenAI 工具與託管 sandbox 依適用費率計算。規劃時可以把總成本拆成以下四層：

1. 模型用量：輸入、輸出、上下文與推理等依模型規則計算的 token 成本。
2. 工具與資料：OpenAI 工具，以及另外串接的搜尋、分析或公司外部服務費用。
3. 執行與儲存：託管容器，或自架算力、檔案保存、網路與相關基礎設施。
4. 開發與維運：串接、監控、測試、錯誤處理，以及人工檢查與修訂的時間。

具體單價與計費單位應以 OpenAI API 價格頁和使用的第三方服務為準。自架可以改變算力與維運的分配方式，但不會消除模型 API 費用。

要判斷值不值得，最好固定一組代表性任務，記錄完成率、總費用、等待時間與人工修改量。若報告便宜卻需要花很久重做，實際成本可能仍高；反過來，單次費用較高也不必然代表整體沒有價值。

OpenAI 提供 session、turn 等層級的用量資料。計算多代理成本時，要確認統計是否已包含子代理，避免再加一次。用量可能尚未完整回報，缺值不等於零，也不能當成最終帳單；第三方服務與維運成本仍要另計。詳見 可觀測性與用量文件。

---

---

企業導入前，要釐清的資料、權限與保存限制

當代理能讀文件、執行程式或改動外部系統，產品設計就要回答：它能看到哪些資料、能做哪些動作、出了問題如何追查。這些條件應在試用階段就確認，才不會做到最後才發現無法接正式資料。

不用於訓練，與不保存資料是不同條件

OpenAI 的 API 資料原則是，除非主動選擇分享，否則不將 API 資料用於訓練模型。但這不代表服務完全不保存資料：濫用監測紀錄、應用狀態與各功能的保存方式，仍須分別查看。來源：OpenAI 資料控制說明。

Agents API 會保存 session 狀態，方便後續延續工作；它目前不支援 Zero Data Retention（ZDR，零資料保留），資料駐留支援也目前限於美國。選擇 self-hosted sandbox 不會讓 Agents API 因此符合 ZDR。

因此，如果公司要求資料必須保存在指定地區，或必須採零資料保留，應先核對服務是否符合內部條件。自架環境本身不足以回答這個問題；可參考 Agents API 的資料限制與公司核准的資料政策。

權限必須由後端執行，不能只寫在提示裡

「只查自己的客戶資料」可以寫進指令，但後端也必須真的驗證身分與資料範圍。否則，模型即使平常遵守指令，系統仍可能存在越權入口。收件人、退款金額或可修改欄位等，也應由程式檢查。

憑證同樣要分開管理。OpenAI 提供 Vault 來保存從 OpenAI 端連接 MCP 所需的憑證，讓代理使用工具時不必取得秘密值；但它有適用的連接範圍，不是所有環境憑證都能直接套用。詳見 Vault 文件。

初次導入可以先做查詢與草稿，再逐步開放修改。寄信、退款、發布或刪除等操作，應設計明確的允許範圍、必要確認與結果讀回。這是應用設計建議，不能只靠「代理會自己判斷」作為控制方式。

工作紀錄保存，不等於執行環境永久存在

Session、執行環境與成品檔案有不同生命週期。OpenAI-hosted 環境中的輸出，可以在一輪工作完成後保存為不可變 artifact；已保存的 artifact 能在環境過期後下載，但刪除 session 前仍要先保存需要的成品。

自架環境的檔案，則需要用自己的儲存方式取回與保存。更換一台執行主機，不會因為沿用 session 就自動恢復原本磁碟內容。這個分別在 檔案保存文件中有明確說明。

清理也要分開處理。對 self-hosted 而言，刪除 session 不等於關閉自己租用的算力；如果忽略主機生命週期，工作結束後仍可能繼續產生基礎設施費用。詳見 Sandbox 生命週期。

---

顯示完成或連線中斷時，應該怎麼判斷？

這是把代理放進正式產品時，很容易漏掉的一環。一輪工作結束，不等於所有工具都成功；session 閒置，也不等於報告已經做好。OpenAI 的 快速開始文件特別提醒，要檢查 turn 的結果與代理實際回報。

回到月報案例，代理可能成功分析流量，卻沒讀到轉換檔案，最後產出一份附缺件說明的報告。系統可以正常結束這輪工作，但你的產品仍應顯示「缺少轉換資料」，而非直接標示所有分析成功。

如果串流斷線，也不要立刻整個重送。串流不會自動重播所有錯過的事件，應先讀取 session 與保存的 items，確認工作做到哪裡，再恢復畫面或決定下一步。詳見 中斷後的恢復方式。

尤其是有外部影響的操作：信可能已經寄出，只是結果還沒成功傳回。如果直接再寄一次，就會重複執行。函式工具文件建議保存呼叫與結果；結果不明時，先確認實際狀態，再決定是否重跑。

因此，正式產品最好同時保留工作狀態、工具執行結果與可驗收成品。這些紀錄能讓團隊知道是資料缺件、工具故障、模型判斷有誤，還是單純畫面沒有更新，而不必把所有問題都當成「AI 壞了」。

---

第一次導入 Agents API，從一個可驗收的任務開始

對非工程背景的主管，第一步可以先寫一張工作單：輸入有哪些、要交付什麼、允許哪些動作，以及遇到缺件時怎麼做。工程團隊再依這張工作單，選模型、工具、執行環境與資料存取方式。

開發者的起點是 OpenAI Platform 專案與 application API key。官方快速開始列出 Agents 的讀取／寫入權限，以及模型推理所需權限；SDK 範例使用 beta.agents。直接呼叫 REST 時另有 beta header 要求，應以 Agents API 快速開始的現行設定為準。

先用沒有機密資訊的小型檔案測試，建立 session、送出任務、接收進度，再實際打開輸出檔。確認工具與結果正確後，才加入正式資料來源、多代理或對外操作。這能把每次新增能力帶來的問題縮小到容易定位的範圍。

如果工作只是固定格式轉換或按規則同步資料，也可以先評估既有程式流程。需要辨識情境、跨工具查詢、處理例外並持續修正的任務，才更能發揮代理的彈性。以下是依工作特徵整理的判斷方式。

正式擴大前，至少驗收四種情況：正常資料能完成、缺件能說清楚、工具出錯能回報、連線中斷不會重複產生外部操作。若需要更深入理解背後的工作系統，可以延伸閱讀Harness Engineering 的概念與做法。

---

先讓一件工作穩定完成，再擴大應用

Agents API 提供的是一個能接進產品、持續處理任務的代理執行服務。對企業最實用的起點，是選一件資料範圍清楚、成果容易檢查的工作，讓團隊先量到實際成本與完成品質，再決定是否擴大。