概覽

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 亦不支援零資料保留。如要了解資料控制的詳情，請參閱 Agents API 文件。