Skip to content

Commit 44088e9

Browse files
agataagata
authored
docs: add Cloudflare Workers transport guide (#511)
1 parent 3115177 commit 44088e9

File tree

9 files changed

+183
-0
lines changed

9 files changed

+183
-0
lines changed

‎docs/astro.config.mjs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -309,6 +309,14 @@ const sidebar = [
309309
zh: '将实时智能体连接到 Twilio',
310310
},
311311
},
312+
{
313+
label: 'Cloudflare Workers Transport',
314+
link: '/extensions/cloudflare',
315+
translations: {
316+
ja: 'Cloudflare Workers 用トランスポート',
317+
zh: 'Cloudflare Workers 传输',
318+
},
319+
},
312320
],
313321
},
314322
{

‎docs/src/content/docs/extensions/cloudflare.mdx‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: Realtime Agents on Cloudflare
3+
description: Connect your Agents SDK agents from Cloudflare Workers/workerd using a dedicated transport.
4+
---
5+
6+
import { Aside, Steps, Code } from '@astrojs/starlight/components';
7+
import cloudflareBasicExample from '../../../../../examples/docs/extensions/cloudflare-basic.ts?raw';
8+
9+
Cloudflare Workers and other workerd runtimes cannot open outbound WebSockets using the global
10+
`WebSocket` constructor. To simplify connecting Realtime Agents from these environments, the
11+
extensions package provides a dedicated transport that performs the `fetch()`-based upgrade
12+
internally.
13+
14+
<Aside type="caution">
15+
This adapter is still in beta. You may run into edge case issues or bugs.
16+
Please report any issues via [GitHub
17+
issues](https://github.com/openai/openai-agents-js/issues) and we'll fix
18+
quickly. For Node.js-style APIs in Workers, consider enabling `nodejs_compat`.
19+
</Aside>
20+
21+
## Setup
22+
23+
<Steps>
24+
25+
1. **Install the extensions package.**
26+
27+
```bash
28+
npm install @openai/agents-extensions
29+
```
30+
31+
2. **Create a transport and attach it to your session.**
32+
33+
<Code lang="typescript" code={cloudflareBasicExample} />
34+
35+
3. **Connect your `RealtimeSession`.**
36+
37+
```typescript
38+
await session.connect({ apiKey: 'your-openai-ephemeral-or-server-key' });
39+
```
40+
41+
</Steps>
42+
43+
## Notes
44+
45+
- The Cloudflare transport uses `fetch()` with `Upgrade: websocket` under the hood and skips
46+
waiting for a socket `open` event, matching the workerd APIs.
47+
- All `RealtimeSession` features (tools, guardrails, etc.) work as usual when using this transport.
48+
- Use `DEBUG=openai-agents*` to inspect detailed logs during development.

‎docs/src/content/docs/guides/troubleshooting.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ The OpenAI Agents SDK is supported on the following server environments:
1717
- The SDK current requires `nodejs_compat` to be enabled
1818
- 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.
1919
- Due to Cloudflare Workers' limited support for `AsyncLocalStorage` some traces might not be accurate
20+
- 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`).
2021
- **Browsers**:
2122
- Tracing is currently not supported in browsers
2223
- **v8 isolates**:

‎docs/src/content/docs/guides/voice-agents/transport.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ import customWebRTCTransportExample from '../../../../../../examples/docs/voice-
2424
import websocketSessionExample from '../../../../../../examples/docs/voice-agents/websocketSession.ts?raw';
2525
import transportEventsExample from '../../../../../../examples/docs/voice-agents/transportEvents.ts?raw';
2626
import thinClientExample from '../../../../../../examples/docs/voice-agents/thinClient.ts?raw';
27+
import cloudflareTransportExample from '../../../../../../examples/docs/extensions/cloudflare-basic.ts?raw';
2728

2829
## Default transport layers
2930

@@ -46,6 +47,12 @@ building a phone agent with Twilio.
4647

4748
Use any recording/playback library to handle the raw PCM16 audio bytes.
4849

50+
#### Cloudflare Workers (workerd) note
51+
52+
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.
53+
54+
<Code lang="typescript" code={cloudflareTransportExample} />
55+
4956
### Building your own transport mechanism
5057

5158
If you want to use a different speech-to-speech API or have your own custom transport mechanism, you

‎docs/src/content/docs/ja/extensions/cloudflare.mdx‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: Cloudflare Workers で Realtime Agent を使う
3+
description: Connect your Agents SDK agents from Cloudflare Workers/workerd using a dedicated transport.
4+
---
5+
6+
import { Aside, Steps, Code } from '@astrojs/starlight/components';
7+
import cloudflareBasicExample from '../../../../../../examples/docs/extensions/cloudflare-basic.ts?raw';
8+
9+
Cloudflare Workers やその他の workerd ランタイムでは、グローバルの `WebSocket` コンストラクターを使ってアウトバウンド WebSocket を開けません。こうした環境から Realtime Agent を簡単に接続できるようにするため、extensions パッケージでは内部で `fetch()` ベースのアップグレードを実行する専用トランスポートを提供しています。
10+
11+
<Aside type="caution">
12+
このアダプターはまだベータ版です。レアケースの問題やバグに遭遇する可能性があります。
13+
問題があれば [GitHub
14+
issues](https://github.com/openai/openai-agents-js/issues)
15+
に報告してください。すぐに対応します。Workers で Node.js 風 API が必要な場合は
16+
`nodejs_compat` の有効化を検討してください。
17+
</Aside>
18+
19+
## セットアップ
20+
21+
<Steps>
22+
23+
1. **extensions パッケージをインストールします。**
24+
25+
```bash
26+
npm install @openai/agents-extensions
27+
```
28+
29+
2. **トランスポートを作成し、セッションに設定します。**
30+
31+
<Code lang="typescript" code={cloudflareBasicExample} />
32+
33+
3. **`RealtimeSession` を接続します。**
34+
35+
```typescript
36+
await session.connect({ apiKey: 'your-openai-ephemeral-or-server-key' });
37+
```
38+
39+
</Steps>
40+
41+
## メモ
42+
43+
- Cloudflare 用トランスポートは内部で `fetch()` と `Upgrade: websocket` を使用し、ソケットの `open` イベントを待たずに workerd の API に合わせています。
44+
- このトランスポートを使っても、ツールやガードレールなど `RealtimeSession` の機能は通常どおり動作します。
45+
- 開発中に詳細なログを確認するには、`DEBUG=openai-agents*` を設定します。

‎docs/src/content/docs/ja/guides/voice-agents/transport.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ import customWebRTCTransportExample from '../../../../../../../examples/docs/voi
2424
import websocketSessionExample from '../../../../../../../examples/docs/voice-agents/websocketSession.ts?raw';
2525
import transportEventsExample from '../../../../../../../examples/docs/voice-agents/transportEvents.ts?raw';
2626
import thinClientExample from '../../../../../../../examples/docs/voice-agents/thinClient.ts?raw';
27+
import cloudflareTransportExample from '../../../../../../../examples/docs/extensions/cloudflare-basic.ts?raw';
2728

2829
## 既定のトランスポート層
2930

@@ -43,6 +44,12 @@ WebRTC の代わりに WebSocket 接続を使用するには、セッション
4344

4445
任意の録音/再生ライブラリを使用して、元の PCM16 オーディオバイトを処理できます。
4546

47+
#### Cloudflare Workers (workerd) に関する注意
48+
49+
Cloudflare Workers やその他の workerd ランタイムでは、グローバルの `WebSocket` コンストラクターを使ってアウトバウンド WebSocket を開けません。`fetch()` ベースのアップグレードを内部で行う extensions パッケージの Cloudflare トランスポートを使用してください。
50+
51+
<Code lang="typescript" code={cloudflareTransportExample} />
52+
4653
### 独自のトランスポート機構の構築
4754

4855
別の音声対音声 API を使用する場合や、独自のトランスポート機構が必要な場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTransportEventTypes` のイベントを発火して独自のものを作成できます。

‎docs/src/content/docs/zh/extensions/cloudflare.mdx‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: 在 Cloudflare Workers 上使用实时智能体
3+
description: Connect your Agents SDK agents from Cloudflare Workers/workerd using a dedicated transport.
4+
---
5+
6+
import { Aside, Steps, Code } from '@astrojs/starlight/components';
7+
import cloudflareBasicExample from '../../../../../../examples/docs/extensions/cloudflare-basic.ts?raw';
8+
9+
Cloudflare Workers 及其他 workerd 运行时无法使用全局 `WebSocket` 构造函数来发起出站 WebSocket。为便于在这些环境中连接 Realtime Agent，扩展包提供了一个专用传输层，会在内部执行基于 `fetch()` 的升级流程。
10+
11+
<Aside type="caution">
12+
此适配器仍处于测试版阶段，可能会遇到边缘场景或漏洞。 如有问题，请在 [GitHub
13+
issues](https://github.com/openai/openai-agents-js/issues)
14+
提交，我们会尽快处理。若需要在 Workers 中使用类似 Node.js 的 API，请考虑启用
15+
`nodejs_compat`。
16+
</Aside>
17+
18+
## 设置
19+
20+
<Steps>
21+
22+
1. **安装扩展包。**
23+
24+
```bash
25+
npm install @openai/agents-extensions
26+
```
27+
28+
2. **创建传输层并将其附加到会话。**
29+
30+
<Code lang="typescript" code={cloudflareBasicExample} />
31+
32+
3. **连接 `RealtimeSession`。**
33+
34+
```typescript
35+
await session.connect({ apiKey: 'your-openai-ephemeral-or-server-key' });
36+
```
37+
38+
</Steps>
39+
40+
## 说明
41+
42+
- Cloudflare 传输层在内部使用带有 `Upgrade: websocket` 的 `fetch()`，并跳过等待套接字的 `open` 事件，以符合 workerd 的 API。
43+
- 使用该传输层时，`RealtimeSession` 的功能（工具、护栏等）仍会照常运行。
44+
- 在开发过程中如需查看详细日志，请设置 `DEBUG=openai-agents*`。

‎docs/src/content/docs/zh/guides/voice-agents/transport.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ import customWebRTCTransportExample from '../../../../../../../examples/docs/voi
2424
import websocketSessionExample from '../../../../../../../examples/docs/voice-agents/websocketSession.ts?raw';
2525
import transportEventsExample from '../../../../../../../examples/docs/voice-agents/transportEvents.ts?raw';
2626
import thinClientExample from '../../../../../../../examples/docs/voice-agents/thinClient.ts?raw';
27+
import cloudflareTransportExample from '../../../../../../../examples/docs/extensions/cloudflare-basic.ts?raw';
2728

2829
## 默认传输层
2930

@@ -43,6 +44,12 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t
4344

4445
可使用任意录制/回放库处理原始 PCM16 音频字节。
4546

47+
#### Cloudflare Workers（workerd）注意事项
48+
49+
Cloudflare Workers 及其他 workerd 运行时无法通过全局 `WebSocket` 构造函数打开出站 WebSocket。请使用扩展包提供的 Cloudflare 传输层，它会在内部执行基于 `fetch()` 的升级。
50+
51+
<Code lang="typescript" code={cloudflareTransportExample} />
52+
4653
### 自定义传输机制
4754

4855
如果你想使用不同的语音到语音 API，或拥有自己的自定义传输机制，可通过实现 `RealtimeTransportLayer` 接口并触发 `RealtimeTransportEventTypes` 事件来创建。

‎examples/docs/extensions/cloudflare-basic.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import { CloudflareRealtimeTransportLayer } from '@openai/agents-extensions';
2+
import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
3+
4+
const agent = new RealtimeAgent({
5+
name: 'My Agent',
6+
});
7+
8+
// Create a transport that connects to OpenAI Realtime via Cloudflare/workerd's fetch-based upgrade.
9+
const cfTransport = new CloudflareRealtimeTransportLayer({
10+
url: 'wss://api.openai.com/v1/realtime?model=gpt-realtime',
11+
});
12+
13+
const session = new RealtimeSession(agent, {
14+
// Set your own transport.
15+
transport: cfTransport,
16+
});

0 commit comments

Comments
 (0)