OpenAI Agents API

OpenAI Agents API 让应用通过 OpenAI 托管的接口调用 Codex harness。OpenAI 负责管理会话、任务编排以及上下文压缩和恢复；应用只需要提供工具，并指定 Agent 使用的执行环境。 Agent 可以运行在 PPIO Sandbox 中，在沙箱里执行命令、修改文件、连接 MCP 服务器并生成文件。完整的 API 说明请参阅官方 Agents API 文档。下面介绍两种接入方式：自己创建并管理 Sandbox，或使用 webhook 控制器自动为 Session 创建和恢复 Sandbox。

应用托管

前置条件

OpenAI Agent Environment —— 在 Environments 标签页创建一个，并将其 API key 保存为 OPENAI_ENVIRONMENT_KEY。
PPIO Sandbox —— 安装 SDK 或 CLI，然后在环境中设置 PPIO_API_KEY。

创建 Agent

前往 Agents 页面创建一个新 Agent。你的应用将通过 Agents API 调用这个 Agent。给 Agent 命名并填写描述，然后在 Model 下选择一个模型。模型和推理设置可以按需选择。

启动会话

在 Sessions 标签页启动一个新会话。执行模式选择 Self-hosted —— 这告诉 OpenAI 连接到你自行托管、管理的环境，也就是 PPIO Sandbox。选择你刚创建的 Agent，并设置工作目录（默认 /workspace）。该目录必须在你的 Sandbox 内存在。

连接环境

会话创建后，打开它并点击 Connect environment。对话框会引导你把自托管环境连接到会话，开头就是稍后要运行的代码块。保存对话框中的 Connect an environment 命令 —— 稍后你会在“运行 Executor”一节里于 Sandbox 内运行它。它形如：

CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
  codex exec-server \
    --remote '<remote_url>' \
    --environment-id '<environment_id>'

--remote 与 --environment-id 的值是该会话特有的，请从对话框复制，而不要照抄本页。

启动 Sandbox

当前仅支持 v2 区域，详见区域说明。

接下来，用 PPIO CLI 从 openai-agents-api-executor 模板启动一个 Sandbox。该模板提供了会话所要连接的自托管环境。

ppio sandbox create openai-agents-api-executor --long-running --timeout 720h -d

默认情况下 Sandbox 最多存活一小时。--long-running 解除该上限，让 Sandbox 可以按你设置的 --timeout 存活 —— 这里是 720 小时（30 天），这样会话可以一直连接到同一环境，而无需重建。

Sandbox 的文件系统与沙箱绑定，会随沙箱一起销毁。如果你希望代码与数据在沙箱之外留存、并可被其他 Agent 读取，请用 Git 管理代码，或挂载 Volume 将数据保存在沙箱之外并在多个沙箱间共享。

运行 Executor

在 Sandbox 内启动 Codex executor，指向你的会话。这就是你在“连接环境”一节里保存的 Connect an environment 命令：

CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
  codex exec-server \
    --remote '<remote_url>' \
    --environment-id '<environment_id>'

--remote 与 --environment-id 是你创建的会话特有的 —— 从它的 Connect environment 对话框复制这两个值。CODEX_API_KEY 是前置条件中创建的 OpenAI Agent Environment 的 API key。你可以在 PPIO Sandbox 内运行该命令，例如通过 CLI 后台执行：

ppio sandbox exec <sandbox_id> -b \
  -e CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
  -- codex exec-server --remote '<remote_url>' --environment-id '<environment_id>'

确认连接

会话现已接通。在会话页面向 Agent 发送一条消息，让它报告自己的运行时环境，例如：

Check the runtime environment on my machine.

Agent 会检查工作区并回报。如果配置正确，它会描述你的 Sandbox 内的环境，而非你的本机 —— 例如下面的 Debian GNU/Linux 12 (Bookworm)、内核 Linux 6.1.158、x86_64 —— 这确认了会话是通过你启动的 PPIO Sandbox 执行的。

Webhook 托管

PPIO Sandbox 遵循 OpenAI 的最佳实践，提供了一个长时间运行的控制器 openai-agents-api-executor，为你管理会话与沙箱之间的关系。与“应用托管”相比，这里无需手动创建沙箱，也没有 codex exec-server 注册步骤 —— 会话在运行时自动连接到 PPIO 托管的环境。

前置条件

克隆 executor 仓库

克隆 executor 仓库，其中包含你后续要部署的 webhook 控制器与客户端：

git clone git@github.com:PPIO/openai-agents-api-executor.git

环境变量

从仓库的 .env.example 创建一个 .env 文件，然后填写下列变量：

cp .env.example .env

PPIO Sandbox —— 安装 SDK 或 CLI，然后在环境中设置 PPIO_API_KEY。
OpenAI 应用密钥 —— 在 API keys 页面创建一个，然后将其设置为 OPENAI_API_KEY。该密钥需要 api.agents.read、api.agents.write 与 api.responses.write 三个作用域；它保留在你的应用中，绝不进入沙箱。
OpenAI Agent Environment —— 在 Environments 标签页创建一个，其余权限全部设为 None，并将其 API key 保存为 OPENAI_EXECUTOR_API_KEY。这是唯一会进入沙箱的密钥。
Agent ID —— 把 OPENAI_AGENT_ID 设置为“创建 Agent”一节里 --create-agent 打印的 ID。控制器只服务于该 Agent，并忽略属于其他 Agent 的会话。
Webhook 签名密钥 —— 设置 OPENAI_WEBHOOK_SECRET，该值在“注册 Webhook”一节中获得。首次部署先留空，之后填入并重新部署。

创建 Agent

创建控制器将要服务的 Agent：

npm run webhook:client -- --create-agent <name>

它会打印新的 Agent ID：

{"agent_id":"agent_1c0960ecfe5e41bb8d289525a2446c72d2d44445f38647ff92"}

将该 ID 填入 .env 的 OPENAI_AGENT_ID。传入 --instructions 与 --model 可给 Agent 指定角色；--update-agent <id> 则原位编辑它们，从而保留 Agent ID，无需重新部署。

获取 Webhook URL

部署控制器，它接收 OpenAI webhook，并为每个会话启动或恢复一个 worker 沙箱：

npm run webhook:deploy

它会打印控制器沙箱暴露的 webhook URL：

Reusing controller sandbox <sandbox_id>

Webhook: https://8000-<sandbox_id>.cn-beijing-1.sandbox.ppio.com/webhook
Controller log: /app/controller.log (inside <sandbox_id>)

Next: register that URL in the OpenAI platform under the project that owns
OPENAI_API_KEY, for these events:
  - agent.session.action_required
  - agent.session.failed
Then put the signing secret in OPENAI_WEBHOOK_SECRET and redeploy.

Until then the controller answers 503 "Webhook not configured".

控制器的沙箱 ID 保存于 .controller.json。重新运行 webhook:deploy 会重新连接到同一控制器，并用新的环境变量重启它。若该沙箱已不存在，则会创建一个新的，URL 随之改变，因此需更新在 OpenAI 平台注册的 webhook 以匹配。

注册 Webhook

在 OpenAI 平台打开 Project settings → Webhooks，添加一个指向上述 URL 的 webhook。订阅以下两个事件：

agent.session.action_required
agent.session.failed

请在拥有 OPENAI_API_KEY 的项目中注册 —— 注册到同一组织下其他项目的 webhook 不会被投递。

重新部署控制器

将签名密钥以 OPENAI_WEBHOOK_SECRET 填入 .env，然后重新部署，让控制器读取它：

npm run webhook:deploy

发送输入

通过客户端向 Agent 发送消息，客户端与运行在 worker 沙箱中的 Agent 通信：

npm run webhook:client -- --input "Check the runtime environment on my machine."

Agent 会检查工作区并回报环境。如果配置正确，它会描述沙箱内的环境 —— 这确认了会话通过 PPIO 托管的 worker 执行，你无需创建或注册任何自己的沙箱。

输出的第一行是会话 ID；将其通过 --session-id 传回即可在同一工作区继续：

npm run webhook:client -- --session-id "$SESSION_ID" --input "Read it again."

产品简介

快速开始

最佳实践

Sandbox

Template

Snapshot

文件系统

Secret

Volume

工具集成

CLI 功能

旧版归档

应用托管

前置条件

创建 Agent

启动会话

连接环境

启动 Sandbox

运行 Executor

确认连接

Webhook 托管

前置条件

克隆 executor 仓库

环境变量

创建 Agent

获取 Webhook URL

注册 Webhook

重新部署控制器

发送输入

​应用托管

​前置条件

​创建 Agent

​启动会话

​连接环境

​启动 Sandbox

​运行 Executor

​确认连接

​Webhook 托管

​前置条件

​克隆 executor 仓库

​环境变量

​创建 Agent

​获取 Webhook URL

​注册 Webhook

​重新部署控制器

​发送输入

应用托管

前置条件

创建 Agent

启动会话

连接环境

启动 Sandbox

运行 Executor

确认连接

Webhook 托管

前置条件

克隆 executor 仓库

环境变量

创建 Agent

获取 Webhook URL

注册 Webhook

重新部署控制器

发送输入