請參閱 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 管理
- 建立並儲存可重複使用的智慧體,並將其 ID 儲存為
OPENAI_AGENT_ID。在 DigitalOcean App Platform 上部署 HTTPS webhook 控制器,並為控制器設定此 ID、用於讀取工作階段的OPENAI_API_KEY、DIGITALOCEAN_TOKEN和OPENAI_EXECUTOR_API_KEY。 - 在 OpenAI 專案中註冊控制器的
/webhook端點。啟用agent.session.action_required和agent.session.failed事件,將簽章密鑰儲存為OPENAI_WEBHOOK_SECRET,然後重新部署控制器。 - 依照執行工作階段的步驟操作,使用相同的
OPENAI_AGENT_ID,並將/workspace設為工作目錄。開啟事件串流並傳送輸入。當 OpenAI 要求environment_connection時,控制器會驗證簽章、取得目前的工作階段,並檢查該工作階段的智慧體 ID 和待執行動作。控制器會在 DigitalOcean 中查找mars-{session_id}。若找到已暫停的沙盒,就恢復該沙盒;否則,若沒有運作中的沙盒,就建立一個。 - 收到
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}
- 建立
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。 - 開啟事件串流並傳送輸入,請智慧體寫入並讀取
/workspace/hello.txt。系統會等到執行器連線後才處理輸入。確認已收到連線事件且一輪互動已完成,並檢查智慧體的輸出,查看是否有工具執行失敗。 - 使用
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。