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

預熱沙盒

在啟動智慧體工作階段前準備好工作區。

透過環境預熱,你可以在建立智慧體工作階段前,先建立由 OpenAI 代管的沙盒、安裝套件、載入檔案並執行設定指令。收到任務時,將準備好的環境附加到工作階段,即可啟動智慧體。

如果低延遲是核心需求,可以使用預熱功能。例如,報表應用程式可以在使用者選擇資料集時準備好所需的 Python 套件,程式開發工作流程也可以在使用者撰寫請求時先準備工作區。提早開始設定,可以縮短使用者的等待時間。

運作方式

環境是智慧體執行工具的工作區。工作階段則保存智慧體的設定和對話。透過預熱,你可以先單獨準備工作區,等到需要工作階段時再附加環境。

整個流程分為三個步驟:

  1. 建立環境。 提供任務所需的套件、檔案和設定指令。
  2. 等待環境就緒。 重複查詢環境,直到狀態變為 ready,也可以使用 webhook 接收通知。
  3. 啟動工作階段。 建立工作階段時傳入環境 ID。

你也可以在設定仍在進行時附加環境。智慧體要等到設定完成後才能存取工作區。

計費方式

預熱沙盒免費,附加前的容器用量也免費。預熱後尚未附加的沙盒會在 5 分鐘後到期。

將預熱的沙盒附加到工作階段後,即按標準容器費率計費。

準備報表工作區

這個範例會在啟動智慧體前安裝 pandas 並載入一個小型 CSV 檔案。智慧體接著會在準備好的工作區中計算總和。

本指南所需的最低 SDK 版本分別為 Python SDK 3.28.0、Node.js SDK 7.32.0、Java SDK 4.80.0 或 Ruby SDK 0.103.0。

1. 建立環境

將工作區設定傳送至 POST /v1/agents/environments:

from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "packages": {"python": ["pandas==2.2.3"]},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/amounts.csv",
                "data": "YW1vdW50CjEwCjIwCjMwCg==",
            }
        ],
        "setup_commands": [
            {
                "command": 'python -c "import pandas; print(pandas.__version__)"',
                "cwd": "/workspace",
            }
        ],
    }
)
environment_id = environment.id
print(environment_id)

SDK 範例會儲存回傳的 id,供後續步驟使用。如果使用 cURL,請將該 ID 存入 shell 變數:

ENVIRONMENT_ID="ccarenv_REPLACE_WITH_RETURNED_ID"

建立獨立環境時,請將 environment.type 設為 openai_hosted。

2. 確認環境是否就緒

使用步驟 1 儲存的 ID 查詢環境:

current = client.beta.agents.environments.retrieve(environment_id)
print(current.status)

設定期間,環境狀態為 pending。狀態變為 ready 時,表示工作區已準備好,可以將環境附加到工作階段。

環境就緒不代表智慧體已連線。即使尚未建立工作階段,環境也可以處於 ready 狀態。

如要避免輪詢,請透過專案的 webhook 端點訂閱下列事件:

  • agent.environment.ready
  • agent.environment.failed

如果在設定完成前就附加環境,請透過該工作階段的 agent.session.environment.ready 或 agent.session.environment.failed 事件追蹤設定狀態。你可以在建立工作階段時指定 "stream": true,從回應串流接收事件,也可以透過 GET /v1/agents/sessions/{session_id}/events 開啟事件串流。如需串流的詳細資訊,請參閱工作階段事件。

3. 附加環境並執行任務

建立工作階段時,請提供先前儲存的環境 ID、智慧體及其第一筆輸入:

stream = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra"},
    environment={"type": "openai_hosted", "environment_id": environment_id},
    input="Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.",
    stream=True,
)
with stream:
    for event in stream:
        print(event.model_dump_json())

常見錯誤

請根據錯誤訊息和環境目前的狀態選擇處理方式。

新建立的共用環境最多可附加到 128 個工作階段。你可以在多個工作階段中重複使用同一個環境,這些工作階段會共用工作區。較早建立的環境可能仍採用單一工作階段的生命週期。

錯誤或現象 處理方式
嘗試附加已到期的環境。 建立新環境並使用新的環境 ID。未使用的環境會在 5 分鐘後到期。使用已到期環境的 ID 重試也無法還原其工作區。
404:找不到環境。 確認環境 ID 是否正確,並使用與建立環境時相同的組織、專案和身分。如果環境已到期或已無法使用,請建立新環境。
409:共用環境已達工作階段數量上限。 一個共用環境最多可附加到 128 個工作階段。請重複使用現有的工作階段,或為額外的工作階段建立另一個環境。

使用已儲存的環境範本

如果多個任務需要相同的套件和設定,可以將環境設定儲存為範本,之後每次建立預熱環境時傳入範本 ID 即可:

from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "environment_template_id": "envtmpl_REPLACE_WITH_TEMPLATE_ID",
    }
)
print(environment.id)

為電腦操作預熱沙盒

若要執行瀏覽器任務,請在工作階段開始前準備好代管的瀏覽器和虛擬顯示器。建立環境時,請加入 desktop.enabled 設定:

from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "desktop": {"enabled": True},
    }
)
print(environment.id)

建立工作階段時,請傳入先前儲存的環境 ID 以附加環境,並為智慧體提供 computer_use 工具。工作階段會使用該環境中儲存的桌面設定。如需瞭解如何設定工具及核准瀏覽器來源,請參閱電腦。

列出你的環境

使用 GET /v1/agents/environments 查詢以你的身分在目前組織和專案中建立且仍有效的環境:

environments = client.beta.agents.environments.list(limit=20, order="desc")
for item in environments.data:
    print(item.model_dump_json())

清單會列出尚未附加以及已附加到工作階段的環境,狀態包括 pending、ready、connected、disconnected 或 suspended。失敗、已到期、已刪除或已終止的環境不會列入清單。清單中的環境可能已附加到一或多個工作階段。

結果預設由新到舊排列。如果 has_more 為真,請將 after 設為上一個回應中的 last_id,以取得下一頁結果。limit 可設為 1 到 100,預設為 20。order 可設為 asc 或 desc。

環境的有效期限與重複使用

  • 多個工作階段可以共用同一個環境。 建立各個工作階段時,請傳入相同的 environment_id。這些工作階段會共用執行中的工作區,包括檔案、程序、已安裝的套件和環境設定。每個工作階段各自保留對話記錄。其他已附加的工作階段都能看到工作區的變更,因此如果任務需要各自獨立的工作區,請分別建立環境。一個共用環境最多可附加到 128 個工作階段。此行為適用於新建立的獨立環境,較早建立的環境則保留原有的生命週期。
  • 未使用的環境會到期。 如果環境一直未附加到工作階段,就會在 5 分鐘後到期。請在接近任務預計開始的時間再預熱環境。
  • 使用與建立環境時相同的身分。 查詢、列出或附加環境時,必須使用與建立環境時相同的組織、專案和已驗證身分。同一身分的不同 API 金鑰都能存取相同的環境,輪替金鑰後也一樣。
  • 共用環境閒置後會停止運算。 首次將環境附加到工作階段時,系統會開始計算 20 分鐘的閒置期限。任何已附加工作階段中的活動,或透過環境檔案 API 進行的操作,都會延長期限。只要還有待處理的工作或仍在進行的回合,系統就不會因閒置而停止運算。因閒置而停止運算時,環境可能會進入 suspended 狀態,而非直接到期。此時系統會保留檢查點 7 天。暫停期間,運算會停止,但共用工作區仍會保留。刪除工作階段只會將該工作階段從環境中移除,共用工作區及其檢查點都會保留。API 未提供可單獨刪除環境的端點。

安全地重試建立環境的請求

建立環境時,可以在請求中加入 Idempotency-Key 標頭。如果請求逾時或回應遺失,請使用相同的冪等鍵和相同的請求本文重試,以免多建立一個環境。

只要原本的環境仍可使用,重試請求完成時就會回傳該環境的 ID 和目前狀態。在冪等鍵保留期間,如果環境仍在建立中、建立結果尚不確定、環境已無法使用,或重試的參數與原請求不同,使用該鍵重試可能會收到 409。發生這些衝突時,系統不會建立替代環境。冪等鍵會保留 24 小時,超過這段時間後,使用相同的鍵可能會建立新環境。如果你的目的是建立新環境,請使用新的冪等鍵。