请参阅 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 管理
- 创建并存储智能体,将其 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 控制器。
安装 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}
- 创建
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。