> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 内运行它。它形如：
```bash theme={"system"} theme={null}
CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
codex exec-server \
--remote '' \
--environment-id ''
```
`--remote` 与 `--environment-id` 的值是该会话特有的，请从对话框复制，而不要照抄本页。
### 启动 Sandbox
当前仅支持 v2 区域，详见[区域说明](/docs/sandbox/overview#区域)。
接下来，用 PPIO CLI 从 `openai-agents-api-executor` 模板启动一个 Sandbox。该模板提供了会话所要连接的自托管环境。
```bash theme={"system"} theme={null}
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** 命令：
```bash theme={"system"} theme={null}
CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
codex exec-server \
--remote '' \
--environment-id ''
```
`--remote` 与 `--environment-id` 是你创建的会话特有的 —— 从它的 **Connect environment** 对话框复制这两个值。`CODEX_API_KEY` 是前置条件中创建的 OpenAI Agent Environment 的 API key。
你可以在 PPIO Sandbox 内运行该命令，例如通过 CLI 后台执行：
```bash theme={"system"} theme={null}
ppio sandbox exec -b \
-e CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
-- codex exec-server --remote '' --environment-id ''
```
### 确认连接
会话现已接通。在会话页面向 Agent 发送一条消息，让它报告自己的运行时环境，例如：
```text theme={"system"} theme={null}
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`](https://github.com/PPIO/openai-agents-api-executor)，为你管理会话与沙箱之间的关系。
与“应用托管”相比，这里无需手动创建沙箱，也没有 `codex exec-server` 注册步骤 —— 会话在运行时自动连接到 PPIO 托管的环境。
### 前置条件
#### 克隆 executor 仓库
克隆 executor 仓库，其中包含你后续要部署的 webhook 控制器与客户端：
```bash theme={"system"} theme={null}
git clone git@github.com:PPIO/openai-agents-api-executor.git
```
#### 环境变量
从仓库的 [`.env.example`](https://github.com/PPIO/openai-agents-api-executor/blob/main/.env.example) 创建一个 `.env` 文件，然后填写下列变量：
```bash theme={"system"} theme={null}
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：
```bash theme={"system"} theme={null}
npm run webhook:client -- --create-agent
```
它会打印新的 Agent ID：
```json theme={"system"} theme={null}
{"agent_id":"agent_1c0960ecfe5e41bb8d289525a2446c72d2d44445f38647ff92"}
```
将该 ID 填入 `.env` 的 `OPENAI_AGENT_ID`。传入 `--instructions` 与 `--model` 可给 Agent 指定角色；`--update-agent ` 则原位编辑它们，从而保留 Agent ID，无需重新部署。
### 获取 Webhook URL
部署控制器，它接收 OpenAI webhook，并为每个会话启动或恢复一个 worker 沙箱：
```bash theme={"system"} theme={null}
npm run webhook:deploy
```
它会打印控制器沙箱暴露的 webhook URL：
```text theme={"system"} theme={null}
Reusing controller sandbox
Webhook: https://8000-.cn-beijing-1.sandbox.ppio.com/webhook
Controller log: /app/controller.log (inside )
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`，然后重新部署，让控制器读取它：
```bash theme={"system"} theme={null}
npm run webhook:deploy
```
### 发送输入
通过客户端向 Agent 发送消息，客户端与运行在 worker 沙箱中的 Agent 通信：
```bash theme={"system"} theme={null}
npm run webhook:client -- --input "Check the runtime environment on my machine."
```
Agent 会检查工作区并回报环境。如果配置正确，它会描述**沙箱内**的环境 —— 这确认了会话通过 PPIO 托管的 worker 执行，你无需创建或注册任何自己的沙箱。
输出的第一行是会话 ID；将其通过 `--session-id` 传回即可在同一工作区继续：
```bash theme={"system"} theme={null}
npm run webhook:client -- --session-id "$SESSION_ID" --input "Read it again."
```