DigitalOcean

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

運作方式

DigitalOcean 的 Managed Agents Runtime Services (M.A.R.S.) 使用 codex-agentapi 映像檔啟動 Firecracker microVM。此映像檔包含 Codex，並會啟動執行器，由執行器向外連線至 Agents API。

選擇 由 webhook 管理 的佈建方式，即可根據 OpenAI 事件啟動或恢復沙盒；或選擇 由應用程式管理 的佈建方式，從應用程式控制沙盒。如需互動式快速入門，可選用 DigitalOcean CLI 流程。如需瞭解連線與復原行為，請參閱沙盒生命週期。

開始之前

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

若使用 webhook 控制器或 Python 應用程式，請設定 DIGITALOCEAN_TOKEN，並安裝支援非同步操作的 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 會建立這兩項資源，讓你從終端與智慧體互動。它會直接佈建沙盒，不需要 webhook 控制器。

安裝包含 harness-runtime 的 doctl 測試版，然後進行身分驗證：

doctl auth init

將此資訊清單儲存為 agents.yaml：

12345678910111213141516name: openai-codex-session
agent: codex-agentapi
config:
  agent:
    model: gpt-5.6-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 agents.yaml

此指令預設最多等待 300 秒，直到資源就緒。請儲存工作階段詳細資料中的 OpenAI 工作階段 ID 和 DigitalOcean 工作階段 ID，然後附加至工作階段：

doctl harness-runtime launch openai-codex-session

請智慧體將 hello 寫入 /workspace/hello.txt，再讀取其內容。按下 Ctrl+D 即可中斷附加而不刪除工作階段，執行相同的 launch 指令則可重新附加。完成後，請依照清理步驟操作。

由應用程式管理

當應用程式負責建立工作階段及佈建沙盒時，請採用此方式。首先建立 OpenAI 工作階段：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import 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);

1
2
3
4
5
6
7
8
9
10
11
12from openai import OpenAI

client = OpenAI()

session = 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"},
)
print(session.to_json())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{
			Model:        openai.String("gpt-6-astra"),
			Instructions: openai.String("You are a helpful coding assistant. Write clean code and verify that it works."),
		},
		Environment: openai.EnvironmentParamUnion{
			OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace"},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions(
                            "You are a helpful coding assistant. Write clean code and verify"
                                + " that it works.")
                        .build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .build())
                .build());
System.out.println(result);

1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"

client = OpenAI::Client.new
result = 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"
  }
)
puts result

依照連線沙盒中的說明，儲存 session.id 和環境 ID。將這份僅包含沙盒設定的資訊清單儲存為 sandbox.yaml；智慧體組態已傳送至 OpenAI：

12345678agent: 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. 使用 DIGITALOCEAN_TOKEN 建立 pydo.aio.Client，並呼叫 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 註冊。

參考資料

• 閱讀 DigitalOcean 沙盒設定
• 閱讀 DigitalOcean Python SDK
• 閱讀 DigitalOcean CLI 測試版