openai · seratch · Sep 26, 2025 · Sep 25, 2025
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -309,6 +309,14 @@ const sidebar = [
           zh: '将实时智能体连接到 Twilio',
         },
       },
+      {
+        label: 'Cloudflare Workers Transport',
+        link: '/extensions/cloudflare',
+        translations: {
+          ja: 'Cloudflare Workers 用トランスポート',
+          zh: 'Cloudflare Workers 传输',
+        },
+      },
     ],
   },
   {

diff --git a/docs/src/content/docs/extensions/cloudflare.mdx b/docs/src/content/docs/extensions/cloudflare.mdx
@@ -0,0 +1,48 @@
+---
+title: Realtime Agents on Cloudflare
+description: Connect your Agents SDK agents from Cloudflare Workers/workerd using a dedicated transport.
+---
+
+import { Aside, Steps, Code } from '@astrojs/starlight/components';
+import cloudflareBasicExample from '../../../../../examples/docs/extensions/cloudflare-basic.ts?raw';
+
+Cloudflare Workers and other workerd runtimes cannot open outbound WebSockets using the global
+`WebSocket` constructor. To simplify connecting Realtime Agents from these environments, the
+extensions package provides a dedicated transport that performs the `fetch()`-based upgrade
+internally.
+
+<Aside type="caution">
+  This adapter is still in beta. You may run into edge case issues or bugs.
+  Please report any issues via [GitHub
+  issues](https://github.com/openai/openai-agents-js/issues) and we'll fix
+  quickly. For Node.js-style APIs in Workers, consider enabling `nodejs_compat`.
+</Aside>
+
+## Setup
+
+<Steps>
+
+1. **Install the extensions package.**
+
+   ```bash
+   npm install @openai/agents-extensions
+   ```
+
+2. **Create a transport and attach it to your session.**
+
+   <Code lang="typescript" code={cloudflareBasicExample} />
+
+3. **Connect your `RealtimeSession`.**
+
+   ```typescript
+   await session.connect({ apiKey: 'your-openai-ephemeral-or-server-key' });
+   ```
+
+</Steps>
+
+## Notes
+
+- The Cloudflare transport uses `fetch()` with `Upgrade: websocket` under the hood and skips
+  waiting for a socket `open` event, matching the workerd APIs.
+- All `RealtimeSession` features (tools, guardrails, etc.) work as usual when using this transport.
+- Use `DEBUG=openai-agents*` to inspect detailed logs during development.
diff --git a/docs/src/content/docs/guides/troubleshooting.mdx b/docs/src/content/docs/guides/troubleshooting.mdx
@@ -17,6 +17,7 @@ The OpenAI Agents SDK is supported on the following server environments:
   - The SDK current requires `nodejs_compat` to be enabled
   - Traces need to be manually flushed at the end of the request. [See the tracing guide](/openai-agents-js/guides/tracing#export-loop-lifecycle) for more details.
   - Due to Cloudflare Workers' limited support for `AsyncLocalStorage` some traces might not be accurate
+  - Outbound WebSocket connections must use a fetch-based upgrade (not the global `WebSocket` constructor). For Realtime, use the Cloudflare transport in `@openai/agents-extensions` (`CloudflareRealtimeTransportLayer`).
 - **Browsers**:
   - Tracing is currently not supported in browsers
 - **v8 isolates**:

diff --git a/docs/src/content/docs/guides/voice-agents/transport.mdx b/docs/src/content/docs/guides/voice-agents/transport.mdx
@@ -24,6 +24,7 @@ import customWebRTCTransportExample from '../../../../../../examples/docs/voice-
 import websocketSessionExample from '../../../../../../examples/docs/voice-agents/websocketSession.ts?raw';
 import transportEventsExample from '../../../../../../examples/docs/voice-agents/transportEvents.ts?raw';
 import thinClientExample from '../../../../../../examples/docs/voice-agents/thinClient.ts?raw';
+import cloudflareTransportExample from '../../../../../../examples/docs/extensions/cloudflare-basic.ts?raw';
 
 ## Default transport layers
 
@@ -46,6 +47,12 @@ building a phone agent with Twilio.
 
 Use any recording/playback library to handle the raw PCM16 audio bytes.
 
+#### Cloudflare Workers (workerd) note
+
+Cloudflare Workers and other workerd runtimes cannot open outbound WebSockets using the global `WebSocket` constructor. Use the Cloudflare transport from the extensions package, which performs the `fetch()`-based upgrade internally.
+
+<Code lang="typescript" code={cloudflareTransportExample} />
+
 ### Building your own transport mechanism
 
 If you want to use a different speech-to-speech API or have your own custom transport mechanism, you

diff --git a/docs/src/content/docs/ja/extensions/cloudflare.mdx b/docs/src/content/docs/ja/extensions/cloudflare.mdx
@@ -0,0 +1,45 @@
+---
+title: Cloudflare Workers で Realtime Agent を使う
+description: Connect your Agents SDK agents from Cloudflare Workers/workerd using a dedicated transport.
+---
+
+import { Aside, Steps, Code } from '@astrojs/starlight/components';
+import cloudflareBasicExample from '../../../../../../examples/docs/extensions/cloudflare-basic.ts?raw';
+
+Cloudflare Workers やその他の workerd ランタイムでは、グローバルの `WebSocket` コンストラクターを使ってアウトバウンド WebSocket を開けません。こうした環境から Realtime Agent を簡単に接続できるようにするため、extensions パッケージでは内部で `fetch()` ベースのアップグレードを実行する専用トランスポートを提供しています。
+
+<Aside type="caution">
+  このアダプターはまだベータ版です。レアケースの問題やバグに遭遇する可能性があります。
+  問題があれば [GitHub
+  issues](https://github.com/openai/openai-agents-js/issues)
+  に報告してください。すぐに対応します。Workers で Node.js 風 API が必要な場合は
+  `nodejs_compat` の有効化を検討してください。
+</Aside>
+
+## セットアップ
+
+<Steps>
+
+1. **extensions パッケージをインストールします。**
+
+   ```bash
+   npm install @openai/agents-extensions
+   ```
+
+2. **トランスポートを作成し、セッションに設定します。**
+
+   <Code lang="typescript" code={cloudflareBasicExample} />
+
+3. **`RealtimeSession` を接続します。**
+
+   ```typescript
+   await session.connect({ apiKey: 'your-openai-ephemeral-or-server-key' });
+   ```
+
+</Steps>
+
+## メモ
+
+- Cloudflare 用トランスポートは内部で `fetch()` と `Upgrade: websocket` を使用し、ソケットの `open` イベントを待たずに workerd の API に合わせています。
+- このトランスポートを使っても、ツールやガードレールなど `RealtimeSession` の機能は通常どおり動作します。
+- 開発中に詳細なログを確認するには、`DEBUG=openai-agents*` を設定します。
diff --git a/docs/src/content/docs/ja/guides/voice-agents/transport.mdx b/docs/src/content/docs/ja/guides/voice-agents/transport.mdx
@@ -24,6 +24,7 @@ import customWebRTCTransportExample from '../../../../../../../examples/docs/voi
 import websocketSessionExample from '../../../../../../../examples/docs/voice-agents/websocketSession.ts?raw';
 import transportEventsExample from '../../../../../../../examples/docs/voice-agents/transportEvents.ts?raw';
 import thinClientExample from '../../../../../../../examples/docs/voice-agents/thinClient.ts?raw';
+import cloudflareTransportExample from '../../../../../../../examples/docs/extensions/cloudflare-basic.ts?raw';
 
 ## 既定のトランスポート層
 
@@ -43,6 +44,12 @@ WebRTC の代わりに WebSocket 接続を使用するには、セッション
 
 任意の録音/再生ライブラリを使用して、元の PCM16 オーディオバイトを処理できます。
 
+#### Cloudflare Workers (workerd) に関する注意
+
+Cloudflare Workers やその他の workerd ランタイムでは、グローバルの `WebSocket` コンストラクターを使ってアウトバウンド WebSocket を開けません。`fetch()` ベースのアップグレードを内部で行う extensions パッケージの Cloudflare トランスポートを使用してください。
+
+<Code lang="typescript" code={cloudflareTransportExample} />
+
 ### 独自のトランスポート機構の構築
 
 別の音声対音声 API を使用する場合や、独自のトランスポート機構が必要な場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTransportEventTypes` のイベントを発火して独自のものを作成できます。

diff --git a/docs/src/content/docs/zh/extensions/cloudflare.mdx b/docs/src/content/docs/zh/extensions/cloudflare.mdx
@@ -0,0 +1,44 @@
+---
+title: 在 Cloudflare Workers 上使用实时智能体
+description: Connect your Agents SDK agents from Cloudflare Workers/workerd using a dedicated transport.
+---
+
+import { Aside, Steps, Code } from '@astrojs/starlight/components';
+import cloudflareBasicExample from '../../../../../../examples/docs/extensions/cloudflare-basic.ts?raw';
+
+Cloudflare Workers 及其他 workerd 运行时无法使用全局 `WebSocket` 构造函数来发起出站 WebSocket。为便于在这些环境中连接 Realtime Agent，扩展包提供了一个专用传输层，会在内部执行基于 `fetch()` 的升级流程。
+
+<Aside type="caution">
+  此适配器仍处于测试版阶段，可能会遇到边缘场景或漏洞。 如有问题，请在 [GitHub
+  issues](https://github.com/openai/openai-agents-js/issues)
+  提交，我们会尽快处理。若需要在 Workers 中使用类似 Node.js 的 API，请考虑启用
+  `nodejs_compat`。
+</Aside>
+
+## 设置
+
+<Steps>
+
+1. **安装扩展包。**
+
+   ```bash
+   npm install @openai/agents-extensions
+   ```
+
+2. **创建传输层并将其附加到会话。**
+
+   <Code lang="typescript" code={cloudflareBasicExample} />
+
+3. **连接 `RealtimeSession`。**
+
+   ```typescript
+   await session.connect({ apiKey: 'your-openai-ephemeral-or-server-key' });
+   ```
+
+</Steps>
+
+## 说明
+
+- Cloudflare 传输层在内部使用带有 `Upgrade: websocket` 的 `fetch()`，并跳过等待套接字的 `open` 事件，以符合 workerd 的 API。
+- 使用该传输层时，`RealtimeSession` 的功能（工具、护栏等）仍会照常运行。
+- 在开发过程中如需查看详细日志，请设置 `DEBUG=openai-agents*`。
diff --git a/docs/src/content/docs/zh/guides/voice-agents/transport.mdx b/docs/src/content/docs/zh/guides/voice-agents/transport.mdx
@@ -24,6 +24,7 @@ import customWebRTCTransportExample from '../../../../../../../examples/docs/voi
 import websocketSessionExample from '../../../../../../../examples/docs/voice-agents/websocketSession.ts?raw';
 import transportEventsExample from '../../../../../../../examples/docs/voice-agents/transportEvents.ts?raw';
 import thinClientExample from '../../../../../../../examples/docs/voice-agents/thinClient.ts?raw';
+import cloudflareTransportExample from '../../../../../../../examples/docs/extensions/cloudflare-basic.ts?raw';
 
 ## 默认传输层
 
@@ -43,6 +44,12 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t
 
 可使用任意录制/回放库处理原始 PCM16 音频字节。
 
+#### Cloudflare Workers（workerd）注意事项
+
+Cloudflare Workers 及其他 workerd 运行时无法通过全局 `WebSocket` 构造函数打开出站 WebSocket。请使用扩展包提供的 Cloudflare 传输层，它会在内部执行基于 `fetch()` 的升级。
+
+<Code lang="typescript" code={cloudflareTransportExample} />
+
 ### 自定义传输机制
 
 如果你想使用不同的语音到语音 API，或拥有自己的自定义传输机制，可通过实现 `RealtimeTransportLayer` 接口并触发 `RealtimeTransportEventTypes` 事件来创建。

diff --git a/examples/docs/extensions/cloudflare-basic.ts b/examples/docs/extensions/cloudflare-basic.ts
@@ -0,0 +1,16 @@
+import { CloudflareRealtimeTransportLayer } from '@openai/agents-extensions';
+import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
+
+const agent = new RealtimeAgent({
+  name: 'My Agent',
+});
+
+// Create a transport that connects to OpenAI Realtime via Cloudflare/workerd's fetch-based upgrade.
+const cfTransport = new CloudflareRealtimeTransportLayer({
+  url: 'wss://api.openai.com/v1/realtime?model=gpt-realtime',
+});
+
+const session = new RealtimeSession(agent, {
+  // Set your own transport.
+  transport: cfTransport,
+});