DigitalOcean

请参阅 OpenAI Cookbook 中的应用管理和 webhook 管理示例。

工作原理

DigitalOcean 的 Managed Agents Runtime Services (M.A.R.S.) 使用 codex-agentapi 镜像启动 Firecracker 微型虚拟机。该镜像包含 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 测试版