如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

Cloudflare

将 Cloudflare Containers 连接到 Agents API 会话。

本指南使用 Cloudflare 提供的参考 Worker,通过 webhook 管理沙盒的创建和分配。

请参阅 OpenAI Cookbook 中由应用管理和通过 webhook 管理沙盒的示例。

工作原理

  1. 您的应用创建 Agents API 会话并发送输入。
  2. OpenAI 将会话 webhook 发送到您 Cloudflare 账户中的 Worker。
  3. Worker 启动或重新连接该会话专用的容器,容器中运行着 codex exec-server。执行器主动向 OpenAI 建立出站连接,以便智能体运行命令和操作文件。

您的应用调用 Agents API,参考 Worker 负责创建和分配沙盒。有关如何建立和恢复连接,请参阅沙盒生命周期。

开始之前

您需要一个有权使用 Cloudflare Containers 的 Cloudflare 账户。应用发送请求时使用 OPENAI_API_KEY。将 OPENAI_EXECUTOR_API_KEY 设为环境密钥,并且只将这个密钥作为 CODEX_API_KEY 传入容器。

创建智能体,并将其 ID 保存为 OPENAI_AGENT_ID。请在您的应用和参考 Worker 中使用同一个智能体 ID。

部署参考 Worker

Cloudflare 的参考 Worker 包含 webhook 处理程序、容器镜像、部署配置和清理端点。

为清理端点生成密钥,并将其保存为 EXECUTOR_CLIENT_SECRET:

openssl rand -hex 32

在您的 Cloudflare 账户中部署 Worker:

部署到 Cloudflare

按提示输入以下值:

变量 值
OPENAI_API_KEY Worker 用于获取会话状态的密钥
OPENAI_EXECUTOR_API_KEY 作为 CODEX_API_KEY 传给执行器的环境密钥
OPENAI_AGENT_ID 此 Worker 所服务的智能体 ID
OPENAI_WEBHOOK_SECRET 首次部署时填写 pending-webhook-registration
EXECUTOR_CLIENT_SECRET 为清理端点生成的密钥

将部署后的 Worker URL 保存为 WORKER_URL。

注册 webhook

按照 webhook 设置步骤,在您的 OpenAI 项目中注册 $WORKER_URL/webhook。启用 Cloudflare 参考集成列出的以下事件:

  • agent.session.created
  • agent.session.action_required
  • agent.session.in_progress
  • agent.session.idle
  • agent.session.failed

将 OPENAI_WEBHOOK_SECRET 的值替换为 OpenAI 返回的签名密钥,然后部署新版本的 Worker。请检查 Worker 的配置。以下示例使用标准 HTTP 客户端调用 Worker:

检查 Worker 的健康状态
# Replace the illustrative IDs and URLs below with your own resource values.
import urllib.request

url = "https://worker.example.com".rstrip("/") + "/health"
request = urllib.request.Request(url, method="GET")
with urllib.request.urlopen(request) as response:
    print(response.read().decode())

响应应同时包含 "configured": true 和 "webhook_configured": true。

当会话要求执行 environment_connection 操作时,表示需要重新连接离线的执行器。仅凭空闲事件无法判断能否安全关闭执行器,详见生命周期行为。

运行会话

按照运行会话的步骤操作,使用您应用的 OPENAI_API_KEY,并确保 OPENAI_AGENT_ID 与 Worker 中配置的值相同。创建一个自托管会话,让智能体写入并读取 /workspace/hello.txt。

Worker 收到会话 webhook 后,会连接沙盒执行器。您的应用通过 Agents API 以流式方式接收智能体的输出。

将会话 ID 保存为 SESSION_ID。要继续对话,请先打开会话事件流,再发送后续输入。如果执行器离线,新的输入会触发环境连接请求,会话将等待 Worker 重新连接执行器。仅重新连接执行器不会恢复之前容器中的文件。

在 Worker 中运行您的应用

Cloudflare 的基础 Worker 应用使用 @openai/agents-api TypeScript SDK 创建会话、发送初始和后续输入,并清理资源。调用其 POST /demo 端点即可运行这一流程。

此应用也通过 webhook 管理沙盒的创建和分配。即使您的应用在 Worker 中运行,也无需由应用直接创建和分配沙盒。

清理资源

当应用不再需要沙盒时,请调用参考 Worker 中需要身份验证的清理端点:

清理 Worker 沙盒
# Replace the illustrative IDs and URLs below with your own resource values.
import os
from urllib.parse import quote
import urllib.request

url = (
    "https://worker.example.com".rstrip("/")
    + "/executors/"
    + quote("sess_123", safe="")
)
request = urllib.request.Request(
    url,
    method="DELETE",
    headers={"Authorization": "Bearer " + os.environ["EXECUTOR_CLIENT_SECRET"]},
)
with urllib.request.urlopen(request) as response:
    print(response.read().decode())

请单独删除 Agents API 会话。删除会话不会触发 webhook,因此要立即清理资源,您需要执行这两项操作。释放容器前,请先取回所需的文件。

进阶:由应用管理沙盒的创建和分配

要直接控制沙盒的创建和分配,请使用 Cloudflare Sandbox SDK,参照由应用管理沙盒生命周期的步骤和执行器连接说明操作。每个会话只使用一个控制器来创建和分配沙盒。

参考资料