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

DigitalOcean

將 DigitalOcean 沙盒連接至 Agents API 工作階段。

請參閱 OpenAI Cookbook 中由應用程式管理和透過 webhook 管理沙盒的範例。

運作方式

DigitalOcean 的 Managed Agents Runtime Services(M.A.R.S.)使用 codex-agentapi 映像檔啟動 Firecracker 微型虛擬機器。映像檔內含 Codex,並會啟動執行器,由執行器主動連線至 Agents API。

若要根據 OpenAI 事件啟動或恢復沙盒,請選擇 透過 webhook 管理 的佈建方式。若要從應用程式控制沙盒,請選擇 由應用程式管理 的佈建方式。若想透過互動式操作快速入門,也可以使用 DigitalOcean CLI 流程。如需瞭解沙盒如何建立連線及從故障中復原,請參閱沙盒生命週期。

DigitalOcean Managed Agents 目前處於公開預覽階段。如需取得存取權和設定服務的說明,請參閱 DigitalOcean 文件。

開始前的準備

你需要一個已啟用沙盒且可存取 codex-agentapi 的 DigitalOcean 帳戶,以及一個可存取 Agents API 的 OpenAI 專案。

應用程式或 CLI 請使用 OPENAI_API_KEY。將 OPENAI_EXECUTOR_API_KEY 設為環境金鑰。只將環境金鑰傳入沙盒,並將它設為 CODEX_API_KEY 的值。

若使用 webhook 控制器或 Python 應用程式,請設定 DIGITALOCEAN_TOKEN,並安裝 0.41.0 以上版本的 PyDo SDK,安裝時請包含非同步支援(pydo[aio])。使用 OpenAI SDK 傳送 Agents API 請求。只有採用 CLI 流程時才需要安裝 CLI。

透過 webhook 管理

  1. 建立並儲存可重複使用的智慧體,並將其 ID 儲存為 OPENAI_AGENT_ID。在 DigitalOcean App Platform 上部署 HTTPS webhook 控制器,並為控制器設定此 ID、用於讀取工作階段的 OPENAI_API_KEY、DIGITALOCEAN_TOKEN 和 OPENAI_EXECUTOR_API_KEY。
  2. 在 OpenAI 專案中註冊控制器的 /webhook 端點。啟用 agent.session.action_required 和 agent.session.failed 事件,將簽章密鑰儲存為 OPENAI_WEBHOOK_SECRET,然後重新部署控制器。
  3. 依照執行工作階段的步驟操作,使用相同的 OPENAI_AGENT_ID,並將 /workspace 設為工作目錄。開啟事件串流並傳送輸入。當 OpenAI 要求 environment_connection 時,控制器會驗證簽章、取得目前的工作階段,並檢查該工作階段的智慧體 ID 和待執行動作。控制器會在 DigitalOcean 中查找 mars-{session_id}。若找到已暫停的沙盒,就恢復該沙盒;否則,若沒有運作中的沙盒,就建立一個。
  4. 收到 agent.session.failed 事件時,請重新取得工作階段。只有在工作階段目前的狀態仍為 failed 時,才刪除其沙盒。

映像檔會將執行器連接至工作階段的環境。應用程式透過 Agents API 傳送輸入並以串流方式接收結果,控制器則負責佈建沙盒及重新連線。請讓同一個工作階段的佈建作業依序執行,以處理重複或同時送達的事件。如需瞭解控制器的要求,請參閱透過 webhook 管理沙盒生命週期的指南。

試用 DigitalOcean CLI

CLI 會建立工作階段和沙盒,讓你從終端與智慧體互動。CLI 會直接佈建沙盒,無需 webhook 控制器。

請安裝 1.170.0 以上版本的 doctl。這些版本包含 harness-runtime。接著執行以下指令進行身分驗證:

doctl auth init

將以下資訊清單儲存為 environment.yaml:

name: openai-codex-session
agent: codex-agentapi
config:
  agent:
    model: gpt-6.1-sol
    instructions: Work from the files in /workspace.
  environment:
    type: self_hosted
    workspace_directory: /workspace
egress:
  - api.openai.com
  - codex-cloud-environments.chatgpt.com
env:
  CODEX_ENVIRONMENT_ID: ${ENV_ID}
secrets:
  CODEX_API_KEY: ${OPENAI_EXECUTOR_API_KEY}

config 區塊是傳給 OpenAI 的工作階段建立請求。CLI 使用 OPENAI_API_KEY 驗證該請求,根據回應填入 ${ENV_ID} 的值,並且只將環境金鑰傳入沙盒。請勿將已代入實際值的資訊清單寫入日誌或納入版本控制。請將工具需要連線的所有目的地加入 egress。

建立工作階段和沙盒:

doctl harness-runtime create --spec environment.yaml

此指令會等待工作階段和沙盒就緒,預設最多等待 300 秒。請記下工作階段詳細資料中的 OpenAI 工作階段 ID 和 DigitalOcean 工作階段 ID,然後連接至工作階段:

doctl harness-runtime launch openai-codex-session

請智慧體將 hello 寫入 /workspace/hello.txt,然後讀回檔案內容。按 Ctrl+D 可中斷連線並保留工作階段。執行相同的 launch 指令即可重新連線。完成後請依照清理步驟移除資源。

由應用程式管理

如果由應用程式負責建立工作階段和佈建沙盒,請採用此流程。先建立 OpenAI 工作階段:

建立自架工作階段
import OpenAI from "openai";
const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "You are a helpful coding assistant. Write clean code and verify that it works.",
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
  },
});

console.log(session);

儲存 session.id 和環境 ID,具體步驟請參閱連接沙盒。將下列沙盒專用資訊清單儲存為 sandbox.yaml。智慧體設定已在建立工作階段時傳送給 OpenAI。

agent: codex-agentapi
egress:
  - api.openai.com
  - codex-cloud-environments.chatgpt.com
env:
  CODEX_ENVIRONMENT_ID: ${ENV_ID}
secrets:
  CODEX_API_KEY: ${OPENAI_EXECUTOR_API_KEY}
  1. 建立 pydo.aio.Client 時使用 DIGITALOCEAN_TOKEN,然後呼叫 client.agents.create_session。將 params.openai_session_id 設為 OpenAI 工作階段 ID,將 body.manifest 設為 sandbox.yaml 的內容,並在 body.variables 中將 ENV_ID 和 OPENAI_EXECUTOR_API_KEY 分別對應到各自的值。儲存 DigitalOcean 傳回的 session_id。
  2. 開啟事件串流並傳送輸入,請智慧體寫入並讀取 /workspace/hello.txt。系統會等到執行器連線後才處理輸入。確認已收到連線事件且一輪互動已完成,並檢查智慧體的輸出,查看是否有工具執行失敗。
  3. 使用 workspace_download 取得檔案,路徑請使用相對路徑 hello.txt。你可以保留工作階段和沙盒以繼續互動,或清理資源。

請在應用程式中為設定和執行作業分別設定逾時上限,並處理連線失敗的情況。對於由應用程式或 CLI 直接管理的工作階段,請勿加掛負責佈建沙盒的 webhook 處理常式。

清理資源

先儲存所需檔案,再刪除 OpenAI 工作階段並銷毀 DigitalOcean 沙盒。刪除工作階段不會觸發 webhook,因此兩項作業都必須執行,並在清理失敗時回報錯誤。

若使用 PyDo,請呼叫 client.agents.destroy_session 並傳入 DigitalOcean 工作階段 ID。若使用 CLI,請傳入該 ID 或沙盒名稱:

doctl harness-runtime remove openai-codex-session

刪除 webhook 控制器前,請先在 OpenAI 取消註冊該 webhook。

參考資料