概覽

Agents API 目前提供測試版。開發人員可透過它運用由 OpenAI 管理的 Codex 智慧體來建構應用程式。此智慧體能執行多步驟工作，並在同一個工作階段中持續運作。

你的應用程式負責提供任務、工具與設定。OpenAI 負責管理智慧體的工作階段，並協調其模型與工具的運作。

智慧體可以做什麼？

視其工具與執行環境而定，智慧體可以執行程式碼、編輯檔案、使用 MCP 連線，並為你的應用程式產生檔案。你可以在同一個工作階段中傳送其他指示，或接續執行另一項任務。

如需了解支援的功能與範例，請參閱 Agents API 概覽。

如何開始使用？

1. 在你的 OpenAI 平台專案中，為應用程式建立 API 金鑰。授予用於工作階段的 api.agents.read 與 api.agents.write 權限，以及用於模型請求的 api.responses.write 權限。

2. 依照快速入門指南設定智慧體、建立工作階段並提交任務。

3. 追蹤工作階段的事件，以查看進度與結果。若想繼續這項工作，請儲存工作階段 ID。

請將 API 金鑰保存在智慧體的沙箱之外。請求必須包含 OpenAI-Beta: agents=v1 標頭。OpenAI SDK 會自動加入此標頭。

我的智慧體需要沙箱嗎？

請選擇適合任務的環境：

• 無環境：智慧體只需回答問題或使用外部工具，不需要內建的 shell 指令或工作區檔案。

• OpenAI 託管的沙箱：智慧體需要執行指令碼或處理檔案，而你希望由 OpenAI 管理其沙箱。

• 自行託管的沙箱：你需要使用自己的基礎架構、軟體或私人網路。環境的生命週期由你的應用程式管理。

如需設定的詳細資訊，請參閱 Agents API 架構。

可以在哪裡查看工作階段？

開啟平台控制台中的記錄，選取「智慧體」，然後搜尋工作階段 ID。你可以檢視各回合、工具呼叫及子智慧體的活動。

可觀測性指南也說明了如何查看已記錄的 Token 用量。

如果事件串流中斷連線，該怎麼辦？

重試前，請先擷取現有工作階段及其中已儲存的項目。這有助於你在提交更多工作前，確認先前的執行情況。

回合完成並不代表每個工具都執行成功。請查看回報的結果。僅憑工作階段處於閒置狀態，無法判定任務已成功完成。

用量如何計費？

模型請求依所選模型的 API 費率計費。OpenAI 工具與 OpenAI 託管的沙箱，分別依適用的工具與容器費率計費。

如需目前費率，請參閱 API 定價。

工作階段的資料與檔案如何處理？

Agents API 會保留工作階段狀態，讓工作能在不同回合間持續進行。不再需要工作階段與已發布的產出內容時，你可以將其刪除。刪除工作階段前，請先儲存所有需要的檔案。

Agents API 目前僅支援美國的資料駐留。它不支援零資料保留，即使使用自行託管的沙箱也不例外。如需資料控管的詳細資訊，請參閱 Agents API 文件。