如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .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,并安装支持异步操作的 PyDo SDK 0.41.0 或更高版本(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 控制器。

安装 doctl 1.170.0 或更高版本。这些版本包含 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,具体步骤请参阅连接沙盒。智能体配置已发送给 OpenAI,请将以下仅用于沙盒的清单保存为 sandbox.yaml:

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。

参考资料