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

OpenAI 託管沙盒

無需管理運算資源,即可執行程式碼並建立可下載的檔案。

OpenAI 託管沙盒為智慧體提供配備 Python、Node.js 和命令列工具的 Linux 工作區。OpenAI 負責佈建沙盒並建立連線,應用程式則負責提供任務並擷取結果。如果需要使用自己的映像檔、運算資源或私有網路,請選擇自行託管的沙盒。

如果任務需要透過瀏覽器與網站互動,請參閱電腦。

如要在建立工作階段前準備好工作區,請參閱預熱沙盒。

設定沙盒

在建立工作階段的請求中,將 environment.type 設為 openai_hosted。只需加入工作負載所需的設定。沙盒的工作目錄是 /workspace。

使用 container_size 和 network 指定任務所需的資源和網路存取權。如果使用環境範本,未指定的設定會沿用範本中的值。

準備套件和檔案

使用下列設定,在沙盒中備妥相依套件和輸入檔案:

  • packages:如要安裝 Python 套件、系統套件或全域 npm 套件,請分別在 python、system 或 npm 清單中列出套件。視需要指定固定版本,例如 pandas==2.2.3。
  • files:使用 Files API 的檔案 ID 或直接內嵌 base64 編碼的內容來提供輸入檔案。

執行初始化指令

使用 setup_commands,在智慧體啟動前依序執行 shell 指令。例如,[{ "command": "mkdir -p reports" }] 會建立一個目錄。每個指令都可以設定自己的 cwd,預設值為 /workspace。

沙盒會先準備好套件和輸入檔案,再執行初始化指令。你可以使用初始化指令檢查所需的相依套件或檔案。如果初始化指令的結束狀態碼不為零,智慧體就不會啟動。

設定環境變數

使用 env 設定值為字串的環境變數。智慧體產生的程式碼可以讀取這些值。

如需使用機密資料,請使用保管庫憑證,讓實際值保留在沙盒外。系統會拒絕使用執行環境保留的名稱,包括 PATH、CODEX_* 和 OPENAI_API_KEY。

選擇容器規格

建立工作階段時,設定 environment.container_size 即可選擇沙盒可用的 CPU 和記憶體資源。預設值為 medium。

規格 vCPU 記憶體
small 1 1 GB
medium 2 4 GB
large 4 16 GB

例如,在 POST /v1/agents/sessions 請求中加入下列環境設定,即可選用 small 規格:

{
  "environment": {
    "type": "openai_hosted",
    "container_size": "small"
  }
}

傳回的工作階段會在 environment.container_size 中顯示所選規格。這項設定僅適用於 OpenAI 託管沙盒。

控制網路存取

network.access 行為
enabled 允許對外連線。除非沿用範本的網路政策,否則這是預設設定。
disabled 封鎖對外連線。
restricted 只允許連線到 allowed_domains 中列出的主機。

限制模式接受 1 至 100 個必須完全相符的主機名稱,例如 api.example.com。請勿包含萬用字元、通訊協定、路徑或連接埠。子網域和重新導向的目的地主機都必須個別列出。目前,託管的 stdio MCP 伺服器需要將網路存取設為 enabled,詳見 stdio MCP 的需求。

新增技能和外掛程式

使用 skills、plugins 和 capability_directories 新增技能和外掛程式。

在多個工作階段中重複使用設定

設定 environment_template_id 即可重複使用已儲存的設定。未指定的設定會沿用範本中的值。即使覆寫網路設定,也不能擴大範本政策允許的存取範圍。範本只會儲存設定,不會儲存執行中的工作區。

確認初始化是否成功

收到建立工作階段的回應,表示初始化已開始。如要查詢狀態,請呼叫 GET /v1/agents/environments/{environment_id},其中的環境 ID 使用工作階段的 environment.id。

狀態 處理方式
provisioning 初始化正在進行,請稍候。
connected 初始化成功。你可以在執行中的沙盒內新增或列出檔案。
failed 查看 environment.error 欄位。這個欄位位於 agent.session.environment.failed 事件中。

請等到狀態變為 connected,再於執行中的沙盒內新增或列出檔案。

檔案與生命週期

每個工作階段都有獨立的工作區。只要沙盒仍存在,檔案就會在各回合之間保留。回合完成時,系統會將 /workspace/outputs 下的檔案發布為不可變更的成品。沙盒到期後,這些副本仍可下載。

如需瞭解如何上傳與下載檔案、操作執行中沙盒內的檔案,以及適用的路徑規則和限制,請參閱檔案與成品。刪除工作階段前,請先儲存所需的輸出檔案。

沙盒到期時間

已連線的沙盒會收到維持連線的訊號,回合之間也會收到。如果連續一小時沒有任何活動,也沒有收到維持連線的訊號,系統就可能刪除沙盒。此逾時時間無法調整。

使用完畢後,請刪除工作階段,要求系統清理沙盒。如果在初始化或任務執行尚未結束時,刪除請求傳回 409,請稍候再試,並限制重試次數。關閉事件串流不會取消任務。

定價

OpenAI 託管沙盒按標準容器費率計費。模型用量依所選模型的 API 費率另行計費。

範例:建立報告

提供一份包含 10、20 和 30 的 CSV 檔案給智慧體。智慧體會執行 Python 計算總和,並將結果寫入 /workspace/outputs/summary.json。

在應用程式的終端中設定 OPENAI_API_KEY,具體步驟請參閱快速入門的先決條件。請將這把金鑰保留在沙盒外。請確認你使用的 OpenAI SDK 版本包含 Beta 版 Agents API。

建立 summary.json
from openai import OpenAI

client = OpenAI()
stream = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra"},
    environment={
        "type": "openai_hosted",
        "network": {"access": "disabled"},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/amounts.csv",
                "data": "YW1vdW50CjEwCjIwCjMwCg==",
            }
        ],
    },
    input="Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.",
    stream=True,
)

with stream.with_result_collection():
    for event in stream:
        print(event.model_dump_json())
    result = stream.get_final_result()

client.beta.agents.sessions.artifacts.for_result(result).download(
    "/workspace/outputs/summary.json", to="summary.json"
)

files 中以 base64 編碼的值包含 CSV 輸入資料。程式碼會印出工作階段事件。請儲存 session.id,這個值來自 agent.session.created 事件。收到 agent.session.turn.completed 事件後,請列出成品,找出 summary.json 並下載該檔案。檔案內容應如下所示:

{ "total": 60 }

回合完成並不代表每個工具都執行成功。如果任務失敗,或事件串流在任務完成前就已結束,請檢查已儲存的工作階段項目。使用完畢後,請刪除工作階段。

疑難排解

問題 檢查事項
初始化失敗 檢查環境初始化失敗事件,修正套件、輸入檔案或初始化指令的錯誤後,再建立新的工作階段。
沙盒發出的請求遭封鎖 檢查 network 設定,以及請求經重新導向後連線到的所有主機。
無法操作執行中沙盒內的檔案 確認沙盒狀態為 connected。如果沙盒已到期,請建立新的工作階段並重新提供輸入資料。
查詢狀態或列出檔案的請求傳回 5xx 逐次延長重試間隔,並設定停止重試的期限。如果錯誤持續發生,請保留請求 ID。