如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

Agents API

使用代管的 Codex 任務執行框架,建構可持續執行任務的雲端智慧體。

Agents API 由 OpenAI 代管,讓你的應用程式能使用 Codex 任務執行框架。

OpenAI 負責管理工作階段、協調任務執行、壓縮上下文,以及在中斷後復原。你的應用程式則負責提供工具,並為智慧體選擇執行環境。

智慧體可以在沙盒中執行程式碼、編輯檔案、連線至 MCP 伺服器,以及產出成品。

如需查閱端點、請求參數及回應欄位,請參閱 API 參考文件。

計費方式

模型用量依所選模型的 API 費率計費。OpenAI 工具依其標準費率計費,OpenAI 託管的沙盒則依標準容器費率計費。

試用範例

試試以下完整範例:

探索完整的應用程式範例:

核心概念

Agents API 有四個核心概念:

  • 智慧體: 定義智慧體使用的模型、遵循的指示,以及可使用的工具和 MCP 伺服器。
  • 環境: 選用的沙盒或電腦,智慧體可在其中存取檔案、載入技能及執行指令。
  • 工作階段: 可保留狀態的智慧體執行個體,負責處理任務並回應輸入。
  • 事件與項目: 傳送給智慧體的輸入,以及智慧體在工作階段中產生的輸出。

工作階段的完整流程

跟著快速入門指南,從 OpenAI 託管的沙盒開始:

  1. 建立工作階段。 設定智慧體後,OpenAI 會為它佈建環境。
  2. 指派任務。 環境就緒後,使用者的輸入會啟動一輪工作。
  3. 追蹤進度。 透過串流接收輸出,或使用 webhook 得知智慧體何時完成任務或需要輸入。
  4. 繼續工作或調整方向。 將另一項任務傳送至同一個工作階段,或在目前這一輪工作中引導智慧體。

使用 OpenAI 託管的工作階段時,你的應用程式負責傳送輸入及接收事件,OpenAI 則負責執行智慧體,並為它佈建及管理沙盒。如需瞭解設定方式與限制,請參閱環境選項。

你的應用程式啟動工作階段,並接收 Agents API 傳來的事件與輸出。OpenAI 執行代管的 Codex 任務執行框架,並為它佈建及管理沙盒。

代管的任務執行框架提供哪些功能?

代管的 Codex 任務執行框架支援以下功能:

  • 在沙盒中執行指令與程式碼。
  • 運用相關技能並遵循適用的指示。
  • 透過工具或 MCP 存取外部資料。
  • 在智慧體工作時引導它調整方向。
  • 摘要先前的工作內容,以管理上下文視窗。
  • 將工作拆解為子任務,並指派給子代理程式。
  • 從上次停下的地方繼續工作階段。

請參閱快速入門的先決條件,瞭解 API 金鑰所需的權限及 SDK 設定方式。建立工作階段時即可設定這些功能:

設定代管任務執行框架的功能
from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
        "tools": [
            {"type": "programmatic_tool_calling"},
            {
                "type": "mcp",
                "server_label": "openai_docs",
                "transport": {
                    "type": "http",
                    "server_url": "https://developers.openai.com/mcp",
                },
            },
            {"type": "web_search"},
        ],
        "multi_agent": {"enabled": True, "max_concurrent_subagents": 4},
    },
    environment={
        "type": "self_hosted",
        "workspace_directory": "/workspace",
        "capability_directories": ["/workspace/capabilities/skills"],
    },
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
                }
            ],
        }
    ],
)
print(session.id)

如需比較不同的執行環境,請參閱智慧體概覽。

如需瞭解以 Agents API 建構的 AWS 服務,請參閱 Bedrock Managed Agents。

Agents API 會保留工作階段的狀態,讓你在後續回合繼續先前的工作,無須重新建立對話上下文。不再需要工作階段或已發布的成品時,就可以將其刪除。 Agents API 目前僅支援在美國境內的資料駐留,且不支援零資料保留(ZDR)。即使選擇自行託管的沙盒,Agents API 仍不符合 ZDR 的適用條件。如需瞭解資料駐留與保留的詳細資訊,請參閱 OpenAI 平台的資料控管。