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

架構

瞭解任務執行框架、環境與應用程式伺服器。

OpenAI 負責運作智慧體的任務執行框架。你的應用程式將任務傳給框架,並接收結果。當智慧體需要運算資源或檔案時,再加入環境。

架構元件

  • 任務執行框架: 由 OpenAI 代管的 Codex 執行個體,負責在迴圈中呼叫模型與工具,並維護智慧體的工作階段。
  • 環境: 智慧體執行指令、執行程式碼及處理檔案的地方。環境可以是遠端沙盒、你的筆記型電腦、Docker 容器或 AWS Lambda 函式。
  • 應用程式伺服器: 你用來將智慧體連接到產品的程式碼,負責提交任務、接收事件及處理函式工具呼叫。如果環境由你提供,這段程式碼也負責管理環境的生命週期。

先選用任務所需的元件。任務執行框架可以在沒有環境的情況下運作,而你的應用程式可以透過串流或 webhook 接收進度更新。

先從不設定環境開始

如果智慧體的任務是回答問題,或透過工具存取外部服務,就可能不需要專屬的運算資源或檔案。將 environment.type 設為 none。以下片段僅示範環境設定。建立工作階段時,還需要指定智慧體並提供初始輸入:

{
  "environment": {
    "type": "none"
  }
}

你的應用程式將輸入傳送到工作階段。任務執行框架會呼叫模型、使用已設定的工具,並傳回結果。OpenAI 會維護這個工作階段,供後續任務使用。

任務執行框架可以直接呼叫遠端 MCP 工具。若使用函式工具,則由你的程式碼接收每次呼叫、執行對應的函式,並傳回結果。

如果沒有環境,就無法使用內建的 Bash 和 apply-patch 工具、工作區檔案,以及執行器提供的 MCP 伺服器。

在沒有沙盒的情況下,應用程式提供函式工具或虛擬 shell,而 Agents API 可以呼叫遠端 MCP 伺服器。此架構沒有執行器或內建 shell。

圖中的虛擬執行環境是選用元件,可透過應用程式的函式工具提供檔案和 shell 指令。

加入由 OpenAI 代管的環境

當智慧體需要執行指令碼、編輯檔案或建立成品時,請將 environment.type 設為 openai_hosted。OpenAI 會為這個工作階段建立並管理沙盒。

你負責設定智慧體所需的套件、檔案及網路存取權限。任務執行框架會直接在沙盒中執行指令。你的應用程式則繼續傳送任務、接收事件,並處理所有函式工具呼叫。

應用程式啟動工作階段並接收來自 Agents API 的事件。Agents API 負責運作代管的 Codex 任務執行框架,將工具呼叫傳送至沙盒並接收結果。只有使用自行託管的沙盒時,才由應用程式控制運算資源。

虛線箭頭僅適用於下節說明的情況,也就是由你自行管理環境時。

如需瞭解設定選項,請參閱由 OpenAI 代管的環境。

連接自有環境

當智慧體需要使用你的基礎架構、私有網路或自訂軟體時,請使用 environment.type: "self_hosted"。

你的程式碼會啟動環境,並將執行器連接到工作階段。執行器會依照任務執行框架的要求執行指令和工具。你的應用程式負責管理連線及環境的生命週期,無需逐一轉送指令。

你負責配置資源、重新連線、關閉環境,以及保存所有需要保留的檔案。這些工作可由應用程式伺服器或 webhook 處理常式管理。

應用程式建立自行託管的工作階段、啟動運算資源並連接執行器。應用程式會接收事件,並在停止運算資源前檢查該回合的執行結果。

停止運算資源前,請協調好新進任務的處理方式,並確認沒有任何工作仍待執行或尚未執行完畢。

如需瞭解設定和關閉環境的相關要求,請參閱連接沙盒和沙盒生命週期。

接收進度更新與結果

無論採用哪種環境設定,都可以使用以下任一方式,也可以兩者並用:

  • 串流: 在智慧體執行任務時接收詳細事件,例如可在產品中顯示的輸出內容。
  • Webhook: 無需持續開啟串流,即可在工作階段狀態變更時收到通知。你的處理常式可以擷取結果、執行函式工具,或管理自行託管的環境。

函式工具需要處理常式來接收呼叫並傳回結果。如果處理常式無法使用,智慧體可能會一直等待結果。負責處理事件或管理生命週期的處理常式若發生錯誤,也可能中斷進度更新或環境管理作業。

如需瞭解整合細節,請參閱工作階段事件和 Webhook。