For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主要導覽

OpenAI 託管的沙盒

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

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

設定沙盒

environment.type 設為 openai_hosted,並僅加入工作負載 所需的設定。工作目錄為 /workspace

  • packages:使用 pythonsystemnpm 清單,安裝 Python 套件、系統套件或全域 npm 套件。視需要固定版本,例如 pandas==2.2.3
  • setup_commands:在智慧體啟動前,依序執行 Shell 指令,例如 [{ "command": "mkdir -p reports" }]。每個指令都可個別選擇設定 cwd,預設為 /workspace
  • files:透過 Files API ID 或內嵌 base64 內容提供輸入檔案
  • env:設定值為字串的環境變數。執行階段保留的名稱,包括 PATHCODEX_*OPENAI_API_KEY,均不接受使用。
  • skillspluginscapability_directories:加入技能外掛程式
  • environment_template_id:在不同工作階段中重複使用已儲存的組態。未指定的設定會繼承範本;覆寫網路設定時,不得擴大範本政策允許的範圍。

系統會在執行設定指令前備妥套件和輸入檔案。若設定程序的結束狀態碼非零, 智慧體就不會啟動。可使用設定指令檢查必要的 相依套件或檔案。範本儲存的是組態,而非執行中的工作區。

控制網路存取

network.access行為
enabled允許對外存取。除非繼承範本政策,否則此為預設行為。
disabled封鎖對外存取。
restricted僅允許存取 allowed_domains 中列出的主機。

受限模式接受 1–100 個精確的主機名稱,例如 api.example.com。 請勿包含萬用字元、通訊協定、路徑或連接埠。子網域和重新導向 目的地都需要各自列為獨立項目。託管的 stdio MCP 伺服器目前要求 將存取設為 enabled;請參閱 stdio MCP 需求

確認設定成功

收到建立工作階段的回應,代表設定程序已開始。請使用工作階段的 environment.id 呼叫 GET /v1/agents/environments/{environment_id} 以取得狀態: provisioning 代表設定程序正在執行;connected 代表設定成功。 若狀態為 failed,請讀取 agent.session.environment.failed 事件中的 environment.error。 請等到狀態為 connected 後,再新增或列出即時檔案。

檔案與存續時間

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

如需瞭解上傳、 路徑規則、即時檔案操作、下載及限制,請參閱檔案與產出物。 刪除工作階段前,請先儲存需要保留的輸出。

沙盒到期

已連線的沙盒會收到連線維持訊號,回合之間也不例外。如果活動和 連線維持訊號都停止一小時,沙盒就可能遭到刪除。此逾時時間 無法設定。

使用完畢後,請刪除工作階段,以要求清理沙盒。如果設定或執行程序仍在完成中, 刪除要求因而傳回 409,請等待後重試,並限制 嘗試次數。關閉事件串流不會取消任務。

定價

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

範例:建立報告

提供包含 102030 的 CSV 給智慧體。智慧體會執行 Python 計算 總和,並寫入 /workspace/outputs/summary.json

請依照快速入門的先決條件, 在應用程式的終端中設定 OPENAI_API_KEY。 請將此金鑰保留在沙盒外。請使用包含 Beta 版 Agents API 的 OpenAI SDK 版本。

建立 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:
    for event in stream:
        print(event.model_dump_json())

files 中的 base64 值包含 CSV 輸入資料。程式碼會印出工作階段事件。 請儲存 agent.session.created 中的 session.id。收到 agent.session.turn.completed 後, 列出產出物,找到 summary.json, 然後下載該檔案。其內容應為:

{ "total": 60 }

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

疑難排解

問題檢查項目
設定失敗檢查環境失敗事件,並修正套件、輸入檔案或設定指令的錯誤,再建立另一個工作階段。
沙盒要求遭到封鎖檢查 network 及透過重新導向存取的所有主機。
即時檔案操作失敗確認沙盒狀態為 connected。如果已到期,請建立新的工作階段,並再次提供輸入資料。
狀態或檔案清單要求傳回 5xx逐步延長等待時間後重試,並設定截止時間。如果錯誤持續發生,請保留要求 ID。