本指南使用 Cloudflare 提供的参考 Worker,通过 webhook 管理沙盒的创建和分配。
请参阅 OpenAI Cookbook 中由应用管理和通过 webhook 管理沙盒的示例。
- 您的应用创建 Agents API 会话并发送输入。
- OpenAI 将会话 webhook 发送到您 Cloudflare 账户中的 Worker。
- 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。
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 设置步骤,在您的 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:
1
2
3
4
5
6
7
8// Replace the illustrative IDs and URLs below with your own resource values.
const response = await fetch(
"https://worker.example.com".replace(/\/+$/, "") + "/health",
{ method: "GET" }
);
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.text());
1
2
3
4
5
6
7# 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())
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24// Replace the illustrative IDs and URLs below with your own resource values.
import (
"io"
"net/http"
"os"
"strings"
)
endpoint := strings.TrimRight("https://worker.example.com", "/") + "/health"
request, err := http.NewRequest("GET", endpoint, nil)
if err != nil {
panic(err)
}
response, err := http.DefaultClient.Do(request)
if err != nil {
panic(err)
}
defer response.Body.Close()
if response.StatusCode/100 != 2 {
panic(response.Status)
}
if _, err := io.Copy(os.Stdout, response.Body); err != nil {
panic(err)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15// Replace the illustrative IDs and URLs below with your own resource values.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
String endpoint = "https://worker.example.com".replaceAll("/+$", "") + "/health";
var request =
HttpRequest.newBuilder(URI.create(endpoint))
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() / 100 != 2)
throw new IllegalStateException("Request failed: " + response.statusCode());
System.out.println(response.body());
1
2
3
4
5
6
7
8
9
10# Replace the illustrative IDs and URLs below with your own resource values.
require "uri"
require "net/http"
uri = URI("https://worker.example.com".sub(%r{/+\z}, "") + "/health")
request = Net::HTTP::Get.new(uri)
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
raise "Request failed: #{response.code}" unless response.is_a?(Net::HTTPSuccess)
puts response.body
1curl --fail-with-body "$WORKER_URL/health"
响应应同时包含 "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 重新连接执行器。仅重新连接执行器不会恢复之前容器中的文件。
Cloudflare 的基础 Worker 应用使用 @openai/agents-api TypeScript SDK 创建会话、发送初始和后续输入,并清理资源。调用其 POST /demo 端点即可运行这一流程。
此应用也通过 webhook 管理沙盒的创建和分配。即使您的应用在 Worker 中运行,也无需由应用直接创建和分配沙盒。
当应用不再需要沙盒时,请调用参考 Worker 中需要身份验证的清理端点:
1
2
3
4
5
6
7
8// Replace the illustrative IDs and URLs below with your own resource values.
const response = await fetch("https://worker.example.com/executors/sess_123", {
method: "DELETE",
headers: { Authorization: `Bearer ${process.env.EXECUTOR_CLIENT_SECRET}` },
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.text());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17# 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())
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26// Replace the illustrative IDs and URLs below with your own resource values.
import (
"io"
"net/http"
"net/url"
"os"
"strings"
)
endpoint := strings.TrimRight("https://worker.example.com", "/") + "/executors/" + url.PathEscape("sess_123")
request, err := http.NewRequest("DELETE", endpoint, nil)
if err != nil {
panic(err)
}
request.Header.Set("Authorization", "Bearer "+os.Getenv("EXECUTOR_CLIENT_SECRET"))
response, err := http.DefaultClient.Do(request)
if err != nil {
panic(err)
}
defer response.Body.Close()
if response.StatusCode/100 != 2 {
panic(response.Status)
}
if _, err := io.Copy(os.Stdout, response.Body); err != nil {
panic(err)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21// Replace the illustrative IDs and URLs below with your own resource values.
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
String endpoint =
"https://worker.example.com".replaceAll("/+$", "")
+ "/executors/"
+ URLEncoder.encode("sess_123", StandardCharsets.UTF_8).replace("+", "%20");
var request =
HttpRequest.newBuilder(URI.create(endpoint))
.header("Authorization", "Bearer " + System.getenv("EXECUTOR_CLIENT_SECRET"))
.method("DELETE", HttpRequest.BodyPublishers.noBody())
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() / 100 != 2)
throw new IllegalStateException("Request failed: " + response.statusCode());
System.out.println(response.body());
1
2
3
4
5
6
7
8
9
10
11# Replace the illustrative IDs and URLs below with your own resource values.
require "uri"
require "net/http"
uri = URI("https://worker.example.com".sub(%r{/+\z}, "") + "/executors/" + URI.encode_www_form_component("sess_123").gsub("+", "%20"))
request = Net::HTTP::Delete.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("EXECUTOR_CLIENT_SECRET")}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
raise "Request failed: #{response.code}" unless response.is_a?(Net::HTTPSuccess)
puts response.body
1
2
3
4curl --fail-with-body \
--request DELETE \
--header "Authorization: Bearer $EXECUTOR_CLIENT_SECRET" \
"$WORKER_URL/executors/$SESSION_ID"
请单独删除 Agents API 会话。删除会话不会触发 webhook,因此要立即清理资源,您需要执行这两项操作。释放容器前,请先取回所需的文件。
要直接控制沙盒的创建和分配,请使用 Cloudflare Sandbox SDK,参照由应用管理沙盒生命周期的步骤和执行器连接说明操作。每个会话只使用一个控制器来创建和分配沙盒。