Cloudflare Workers 전송

Cloudflare Workers 및 기타 workerd 런타임에서는 전역 WebSocket 생성자를 사용해 외부로 나가는 WebSocket 을 열 수 없습니다. 이러한 환경에서 실시간 에이전트를 더 쉽게 연결할 수 있도록, extensions 패키지는 내부적으로 fetch() 기반 업그레이드를 수행하는 전용 전송을 제공합니다.

주의

이 어댑터는 아직 베타입니다. 일부 엣지 케이스 이슈나 버그를 겪을 수 있습니다. 문제가 있다면 GitHub issues로 보고해 주세요. 빠르게 수정하겠습니다. Workers 에서 Node.js 스타일 API 가 필요하다면 nodejs_compat 활성화를 고려하세요.

설정

1. extensions 패키지를 설치합니다.

   npm install @openai/agents-extensions

2. 전송을 생성하고 세션에 연결합니다.

   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,
   });

3. RealtimeSession을(를) 연결합니다.

   await session.connect({ apiKey: 'your-openai-ephemeral-or-server-key' });

참고

• Cloudflare 전송은 내부적으로 Upgrade: websocket 헤더와 함께 fetch()를 사용하며, workerd API와 동일하게 소켓 open 이벤트 대기를 건너뜁니다
• 이 전송을 사용할 때도 모든 RealtimeSession 기능(tools, guardrails 등)이 그대로 동작합니다
• 개발 중 자세한 로그를 확인하려면 DEBUG=openai-agents*를 사용하세요