전송 방식
세션이 실행되는 위치와 원문 미디어 또는 이벤트를 제어해야 하는 범위에 따라 전송 방식을 선택하세요.
| 시나리오 | 권장 전송 방식 | 이유 |
|---|---|---|
| 브라우저 음성 대 음성 앱 | OpenAIRealtimeWebRTC | 가장 간편한 방식입니다. SDK가 마이크 캡처, 재생, WebRTC 연결을 관리합니다. |
| 서버 측 Realtime 제어 기능을 사용하는 브라우저 오디오 | 앱이 소유하는 WebRTC 오디오와 서버 측 RealtimeSession | 브라우저가 오디오를 전달하는 동안 Realtime 이벤트, 도구, 비즈니스 로직을 애플리케이션 서버에 유지합니다. |
| React Native 모바일 앱 | 네이티브 WebRTC를 기반으로 앱이 소유하는 RealtimeTransportLayer | SDK는 React Native 패키지 조건을 제공하고, 앱은 네이티브 WebRTC, 권한, 오디오 라우팅, 수명 주기를 관리합니다. |
| 서버 측 음성 루프 또는 사용자 정의 오디오 파이프라인 | OpenAIRealtimeWebSocket | 오디오 캡처/재생을 이미 제어하고 있으며 이벤트에 직접 접근하려는 경우에 적합합니다. |
| SIP 또는 전화 통신 브리지 | OpenAIRealtimeSIP | callId를 사용해 기존 SIP 기반 Realtime 통화에 RealtimeSession을 연결합니다. |
| Cloudflare Workers / workerd | Cloudflare 확장 전송 방식 | workerd는 전역 WebSocket 생성자로 아웃바운드 WebSocket 연결을 열 수 없습니다. |
| Twilio의 공급자별 전화 통화 흐름 | Twilio 확장 전송 방식 | Twilio 오디오 전달과 인터럽션(중단 처리) 동작을 처리합니다. |
기본 전송 계층
섹션 제목: “기본 전송 계층”브라우저의 기본 선택인 WebRTC
섹션 제목: “브라우저의 기본 선택인 WebRTC”기본 브라우저 전송 방식은 WebRTC를 사용합니다. 마이크에서 오디오를 캡처하고 자동으로 재생하므로 빠른 시작에서는 임시 토큰과 session.connect(...)만으로 연결할 수 있습니다.
이 방식에서 session.connect()는 오디오 전송이 시작되기 전에 instructions와 tools가 적용되도록, 초기 세션 설정이 session.updated로 확인될 때까지 기다린 후 완료되도록 시도합니다. 확인 응답이 도착하지 않는 경우를 대비한 타임아웃 대체 동작도 있습니다.
자체 미디어 스트림이나 오디오 요소를 사용하려면 세션을 생성할 때 OpenAIRealtimeWebRTC 인스턴스를 제공하세요.
import { RealtimeAgent, RealtimeSession, OpenAIRealtimeWebRTC,} from '@openai/agents/realtime';
const agent = new RealtimeAgent({ name: 'Greeter', instructions: 'Greet the user with cheer and answer questions.',});
async function main() { // Keep a handle on the stream you pass in. The transport does not stop a caller-supplied // stream on close(), so your application owns it and is responsible for ending it. const mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true, });
const transport = new OpenAIRealtimeWebRTC({ mediaStream, audioElement: document.createElement('audio'), });
const customSession = new RealtimeSession(agent, { transport });
// Later, once the application is actually done with the microphone, release it. Leaving this // out keeps the microphone indicator on even after the session closes. // mediaStream.getTracks().forEach((track) => track.stop());}OpenAIRealtimeWebRTC에 전달한 mediaStream의 소유권은 애플리케이션에 유지됩니다. 전송 계층을 닫아도 해당 스트림의 트랙은 중지되지 않으므로 레벨 미터, 녹음기 또는 재연결에 계속 사용할 수 있습니다. 애플리케이션에서 스트림 사용을 실제로 마쳤을 때 트랙의 stop()을 호출하세요. 전송 계층이 기본 마이크를 직접 연 경우에는 close()가 SDK 소유 트랙을 중지합니다.
더 낮은 수준의 사용자 정의를 위해 OpenAIRealtimeWebRTC는 changePeerConnection도 지원합니다. 이를 사용하면 오퍼가 생성되기 전에 새로 생성된 RTCPeerConnection을 검사하거나 교체할 수 있습니다.
내장 브라우저 전송 계층은 브라우저 측 RealtimeSession이 Realtime 이벤트를 사용해 세션을 설정하고 제어하므로 데이터 채널을 생성합니다. 애플리케이션에서 이러한 이벤트와 제어 기능을 애플리케이션 서버에 유지해야 한다면, 브라우저 측 피어 연결 사용자 정의를 접근 제어 경계로 간주하지 말고 아래의 서버 측 제어 패턴을 사용하세요.
Azure OpenAI의 GA 프로토콜 사용
섹션 제목: “Azure OpenAI의 GA 프로토콜 사용”내장 Realtime 전송 계층은 GA 프로토콜로 전송합니다. 사용자 정의 URL을 설정해도 세션 업데이트가 Azure의 레거시 프리뷰 형식으로 변환되지는 않습니다. 더 이상 사용되지 않는 지역별 realtimertc 엔드포인트는 session.type, output_modalities와 같은 GA 필드를 거부하여 서버가 동일한 업데이트에 포함된 instructions와 tools를 적용하지 못하게 할 수 있습니다.
Azure WebRTC를 사용하려면 Microsoft의 GA WebRTC 설정 가이드를 따르세요.
- 애플리케이션 서버가 Azure 리소스의
/openai/v1/realtime/client_secrets엔드포인트에서 임시 클라이언트 토큰을 가져오도록 하세요. Azure 리소스 자격 증명은 서버에 보관하세요. RealtimeSession생성자의model옵션을 Azure 배포 이름으로 설정하세요.RealtimeAgent에 instructions와 실행 가능한 도구를 정의하세요.- 임시 토큰을
apiKey로, 리소스의https://<resource>.openai.azure.com/openai/v1/realtime/callsURL을 연결 URL로session.connect()에 전달하세요. SDK는 에이전트 설정을 전송 계층으로 전달합니다.initialSessionConfig는 전송 계층 수준의 옵션이며,RealtimeSession.connect()의 옵션이 아닙니다.
Azure에서 발급한 임시 토큰이 ek_로 시작하지 않으면 브라우저 전송 계층의 키 접두사 검사 때문에 useInsecureApiKey: true를 설정한 명시적 OpenAIRealtimeWebRTC 인스턴스가 필요합니다. 이 옵션은 접두사 검사만 비활성화합니다. 브라우저 코드에는 계속 임시 토큰을 전달하고, 장기 유효 리소스 자격 증명은 절대로 전달하지 마세요.
GA를 사용할 때는 session.type을 제거하지 마세요. GA에는 이 필드가 필수입니다. 엔드포인트와 프로토콜의 차이점은 Microsoft의 프리뷰에서 GA로의 마이그레이션 가이드를 참고하세요.
서버 측 제어 기능을 사용하는 브라우저 오디오
섹션 제목: “서버 측 제어 기능을 사용하는 브라우저 오디오”일부 애플리케이션은 브라우저에서 마이크 캡처와 오디오 재생을 수행하면서 Realtime 이벤트, 도구, 비즈니스 로직은 애플리케이션 서버에 유지해야 합니다. 이 아키텍처는 Realtime API의 통합 WebRTC 인터페이스와 서버 측 제어 기능을 결합합니다.
- 브라우저는 표준 WebRTC API로 오디오 전용 피어 연결을 생성하고 SDP 오퍼를 애플리케이션 서버로 전송합니다. 브라우저는 SDK의 내장 WebRTC 전송 계층을 사용하거나 Realtime 데이터 채널을 생성하지 않습니다.
- 애플리케이션 서버는 사용자를 인증하고, 자체 SDP 정책을 적용한 뒤, 표준 API 키를 사용해 오퍼와 서버 소유 세션 설정을
/v1/realtime/calls로 전송합니다. - 애플리케이션 서버는 SDP 응답을 검증하고 응답의
Location헤더에서 통화 ID를 읽습니다. - 애플리케이션 서버는 WebSocket 전송 계층을 사용하는 서버 측
RealtimeSession을 생성하고, 이벤트 리스너를 등록하고, 통화 ID를session.connect(...)에 전달한 후 초기session.updated이벤트를 기다립니다. - 애플리케이션 서버는 SDP 응답을 브라우저에 반환합니다. 브라우저는 이 응답을 원격 설명으로 설정하고, 오디오는 브라우저와 Realtime API 사이에서 직접 전송됩니다.
- 애플리케이션 서버는 Realtime 이벤트와 도구를 처리합니다. 브라우저에 상태 업데이트가 필요하면 애플리케이션 서버는 원문 Realtime 이벤트 스트림을 전달하는 대신 허용 목록에 있는 애플리케이션 이벤트로 변환해 전달합니다.
오디오 전용 브라우저 피어 연결, 서버에서 강제 적용하는 SDP 정책, 사이드밴드 RealtimeSession, 브라우저용으로 변환된 이벤트, 정리 동작을 포함한 전체 애플리케이션은 realtime-server-controlled 코드 예제를 참고하세요.
React Native의 앱 소유 전송 계층 사용
섹션 제목: “React Native의 앱 소유 전송 계층 사용”@openai/agents-core와 @openai/agents-realtime은 Metro가 Node.js 내장 모듈 없이도 이식 가능한 SDK shim을 해석할 수 있도록 React Native 패키지 조건을 제공합니다. 내장 OpenAIRealtimeWebRTC는 브라우저 WebRTC 전역 객체와 DOM 오디오 요소에 의존하므로 여전히 브라우저용 전송 계층입니다. React Native에서는 앱이 네이티브 WebRTC 구현을 설치하고 관리한 다음, 사용자 정의 RealtimeTransportLayer를 통해 RealtimeSession에 연결하세요.
examples/realtime-react-native의 Expo 개발 빌드 코드 예제는 앱이 소유하는 react-native-webrtc 전송 계층, 마이크 권한, 오디오 라우팅, 서버 측 임시 토큰 엔드포인트를 보여 줍니다. react-native-webrtc에 네이티브 코드가 포함되어 있으므로 Expo Go는 지원되지 않습니다. 표준 OpenAI API 키는 서버에 보관하고, 모바일 앱에는 유효 기간이 짧은 임시 클라이언트 토큰만 전달하세요.
서버의 기본 선택인 WebSocket
섹션 제목: “서버의 기본 선택인 WebSocket”WebRTC 대신 WebSocket 연결을 사용하려면 세션을 생성할 때 transport: 'websocket' 또는 OpenAIRealtimeWebSocket 인스턴스를 전달하세요. 이 방식은 서버 측 사용 사례, 전화 통신 브리지, 사용자 정의 오디오 파이프라인에 적합합니다.
WebSocket 방식에서 session.connect()는 소켓이 열리고 초기 설정이 전송되면 완료됩니다. 이에 해당하는 session.updated 이벤트는 조금 늦게 도착할 수 있으므로, connect()가 완료되었다고 해서 해당 업데이트에 대한 응답이 이미 돌아왔다고 가정하지 마세요.
import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
const agent = new RealtimeAgent({ name: 'Greeter', instructions: 'Greet the user with cheer and answer questions.',});
const myRecordedArrayBuffer = new ArrayBuffer(0);
const wsSession = new RealtimeSession(agent, { transport: 'websocket', model: 'gpt-realtime-2.1',});await wsSession.connect({ apiKey: process.env.OPENAI_API_KEY! });
wsSession.on('audio', (event) => { // event.data is a chunk of PCM16 audio});
wsSession.sendAudio(myRecordedArrayBuffer);원문 PCM16 오디오 바이트를 처리하려면 원하는 녹음/재생 라이브러리를 사용하세요.
고급 통합을 위해 OpenAIRealtimeWebSocket은 자체 소켓 구현을 제공할 수 있는 createWebSocket()을 지원하며, 사용자 정의 커넥터가 소켓을 연결 상태로 전환하는 역할을 맡는 경우에는 skipOpenEventListeners를 지원합니다. @openai/agents-extensions의 Cloudflare 전송 계층은 이러한 훅을 기반으로 구현되어 있습니다.
통화 공급자 및 전화 통신 브리지용 SIP
섹션 제목: “통화 공급자 및 전화 통신 브리지용 SIP”기존 SIP 기반 Realtime 통화에 RealtimeSession을 연결하려면 OpenAIRealtimeSIP를 사용하세요. 이는 SIP를 인식하는 경량 전송 계층입니다. 오디오는 SIP 통화 자체에서 처리하며, SDK 세션은 callId로 연결합니다.
OpenAIRealtimeSIP.buildInitialConfig()로 초기 세션 설정을 생성해 수신 통화를 수락하세요. 이렇게 하면 SIP 초대와 이후 SDK 세션이 동일한 기본값에서 시작됩니다.OpenAIRealtimeSIP전송 계층을 사용하는RealtimeSession을 연결하고, 공급자 웹훅에서 발급한callId로 접속하세요.- 공급자별 미디어 전달이나 이벤트 브리징이 필요하면 Twilio 확장과 같은 통합 전송 계층을 사용하세요.
import OpenAI from 'openai';import { OpenAIRealtimeSIP, RealtimeAgent, RealtimeSession, type RealtimeSessionOptions,} from '@openai/agents/realtime';
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY!, webhookSecret: process.env.OPENAI_WEBHOOK_SECRET!,});
const agent = new RealtimeAgent({ name: 'Receptionist', instructions: 'Welcome the caller, answer scheduling questions, and hand off if the caller requests a human.',});
const sessionOptions: Partial<RealtimeSessionOptions> = { model: 'gpt-realtime-2.1', config: { audio: { input: { turnDetection: { type: 'semantic_vad', interruptResponse: true }, }, }, },};
export async function acceptIncomingCall(callId: string): Promise<void> { const initialConfig = await OpenAIRealtimeSIP.buildInitialConfig( agent, sessionOptions, ); await openai.realtime.calls.accept(callId, initialConfig);}
export async function attachRealtimeSession( callId: string,): Promise<RealtimeSession> { const session = new RealtimeSession(agent, { transport: new OpenAIRealtimeSIP(), ...sessionOptions, });
session.on('history_added', (item) => { console.log('Realtime update:', item.type); });
await session.connect({ apiKey: process.env.OPENAI_API_KEY!, callId, });
return session;}Cloudflare Workers 및 workerd
섹션 제목: “Cloudflare Workers 및 workerd”Cloudflare Workers와 기타 workerd 런타임은 전역 WebSocket 생성자를 사용해 아웃바운드 WebSocket 연결을 열 수 없습니다. 내부적으로 fetch() 기반 업그레이드를 수행하는 확장 패키지의 Cloudflare 전송 계층을 사용하세요.
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-2.1',});
const session = new RealtimeSession(agent, { // Set your own transport. transport: cfTransport,});전체 설정 방법은 Cloudflare용 음성 에이전트를 참고하세요.
Twilio 전화 통화
섹션 제목: “Twilio 전화 통화”원문 WebSocket 또는 @openai/agents-extensions의 전용 Twilio 전송 계층을 사용해 RealtimeSession을 Twilio에 연결할 수 있습니다. SDK가 Twilio Media Streams의 인터럽션(중단 처리) 타이밍과 오디오 전달을 처리하도록 하려면 전용 전송 계층을 기본으로 선택하는 편이 좋습니다.
전체 설정 방법은 Twilio용 음성 에이전트를 참고하세요.
자체 전송 계층 사용
섹션 제목: “자체 전송 계층 사용”다른 음성 대 음성 API를 사용하거나 자체적인 사용자 정의 전송 메커니즘이 있다면 RealtimeTransportLayer 인터페이스를 구현하고 RealtimeTransportEventTypes 이벤트를 직접 발생시킬 수 있습니다.
필요에 따른 원문 Realtime 이벤트 접근
섹션 제목: “필요에 따른 원문 Realtime 이벤트 접근”기반 Realtime API에 더 직접적으로 접근하려면 두 가지 옵션이 있습니다.
옵션 1 - 전송 계층 접근
섹션 제목: “옵션 1 - 전송 계층 접근”RealtimeSession의 모든 기능을 계속 활용하려면 session.transport를 통해 전송 계층에 접근할 수 있습니다.
전송 계층은 수신하는 모든 이벤트를 * 이벤트로 발생시키며, sendEvent()로 원문 이벤트를 보낼 수 있습니다. * 리스너는 현재 SDK 스키마가 알지 못하는 필드까지 포함하여, 파싱된 원본 JSON 페이로드의 구조화된 복제본을 받습니다. 이름이 지정된 이벤트 리스너와 파생 이벤트 리스너는 계속 검증되고 정규화된 이벤트 객체를 받습니다. 이는 session.update, response.create, response.cancel과 같은 저수준 작업을 위한 우회 수단입니다.
import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
const agent = new RealtimeAgent({ name: 'Greeter', instructions: 'Greet the user with cheer and answer questions.',});
const session = new RealtimeSession(agent, { model: 'gpt-realtime-2.1',});
session.transport.on('*', (event) => { // Event received from the underlying Realtime transport});
// Send any valid client event, for example, to trigger a new responsesession.transport.sendEvent({ type: 'response.create', // ...});옵션 2 - 전송 계층만 사용
섹션 제목: “옵션 2 - 전송 계층만 사용”자동 도구 실행, 가드레일 또는 로컬 기록 관리가 필요하지 않다면, 전송 계층을 연결과 인터럽션(중단 처리)만 관리하는 “경량” 클라이언트로 사용할 수도 있습니다.
import { OpenAIRealtimeWebRTC } from '@openai/agents/realtime';
const client = new OpenAIRealtimeWebRTC();const audioBuffer = new ArrayBuffer(0);
await client.connect({ apiKey: '<api key>', model: 'gpt-realtime-2.1', initialSessionConfig: { instructions: 'Speak like a pirate', outputModalities: ['audio'], audio: { input: { format: 'pcm16', }, output: { format: 'pcm16', voice: 'ash', }, }, },});
// Listen for audio when you manage playback yourselfclient.on('audio', (newAudio) => {});
client.sendAudio(audioBuffer);