Twilio용 음성 에이전트
Twilio는 통화의 원문 오디오를 WebSocket 서버로 전송하는 Media Streams API를 제공합니다. 이 구성을 사용하면 음성 에이전트 개요에 소개된 음성 에이전트를 Twilio에 연결할 수 있습니다. 기본 Realtime Session 전송 계층을 websocket 모드로 사용하여 Twilio에서 수신한 이벤트를 Realtime Session에 연결할 수 있습니다. 다만, 전화 통화는 웹 기반 대화보다 본질적으로 지연 시간이 길기 때문에 올바른 오디오 형식을 설정하고 인터럽션(중단 처리) 타이밍을 직접 조정해야 합니다.
설정을 더 쉽게 할 수 있도록, 인터럽션(중단 처리)과 오디오 전달을 포함하여 Twilio 연결을 처리하는 전용 전송 계층을 만들었습니다.
-
Twilio 계정과 Twilio 전화번호가 있는지 확인합니다.
-
Twilio의 요청을 인증하는 서버를 설정합니다.
로컬에서 개발하는 경우, Twilio가 로컬 서버에 접근할 수 있도록
ngrok또는 Cloudflare Tunnel과 같은 로컬 터널을 구성해야 합니다. 서버는 전송 계층을 생성하거나 OpenAI에 연결하기 전에 수신 통화 웹훅과 WebSocket 업그레이드 요청 모두에서X-Twilio-Signature를 검증해야 합니다. 공식 Twilio 요청 검증 도구, 계정의 기본 Auth Token, 그리고 미리 설정한 공개 URL을 사용하세요. 요청의 Host 헤더나 전달 헤더에서 해당 URL을 도출해서는 안 됩니다.TwilioRealtimeTransportLayer는 이미 인증된 WebSocket을 전달받으며, 어댑터는 HTTP 요청을 인증하지 않습니다. -
확장 패키지를 설치하여 Twilio 어댑터를 설치합니다:
터미널 창 npm install @openai/agents-extensions -
RealtimeSession에 연결할 어댑터와 모델을 가져옵니다:import { TwilioRealtimeTransportLayer } from '@openai/agents-extensions';import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';const agent = new RealtimeAgent({name: 'My Agent',});// Authenticate the HTTP webhook and WebSocket upgrade in your server first.// Create a new transport mechanism that will bridge the connection between Twilio and// the OpenAI Realtime API.const twilioTransport = new TwilioRealtimeTransportLayer({twilioWebSocket: websocketConnection,});const session = new RealtimeSession(agent, {// set your own transporttransport: twilioTransport,}); -
RealtimeSession을 Twilio에 연결합니다:import type { RealtimeSession } from '@openai/agents/realtime';// Connect only after the server has authenticated the Twilio WebSocket upgrade.async function connectAuthenticatedSession(session: RealtimeSession,apiKey: string,) {await session.connect({ apiKey });}
도구 호출, 가드레일 등을 포함하여 RealtimeSession에서 기대하는 모든 이벤트와 동작이 정상적으로 작동합니다. 음성 에이전트에서 RealtimeSession을 사용하는 방법에 관한 자세한 내용은 음성 에이전트 개요를 참고하세요.
팁 및 고려 사항
섹션 제목: “팁 및 고려 사항”-
속도가 핵심입니다.
Twilio에서 필요한 모든 이벤트와 오디오를 수신하려면, 인증된 WebSocket 연결을 사용할 수 있게 되는 즉시
TwilioRealtimeTransportLayer인스턴스를 생성하고 바로 이어서session.connect()를 호출해야 합니다. -
Twilio 원문 이벤트에 접근합니다.
Twilio가 전송하는 원문 이벤트에 접근하려면
RealtimeSession인스턴스의transport_event이벤트를 수신하면 됩니다. Twilio의 모든 이벤트는twilio_message유형이며, 원문 이벤트 데이터가 담긴message속성을 포함합니다. -
디버그 로그를 확인합니다.
문제가 발생하여 현재 상황에 대한 더 자세한 정보가 필요할 때가 있습니다.
DEBUG=openai-agents*환경 변수를 사용하면 Agents SDK의 모든 디버그 로그가 표시됩니다. 또는DEBUG=openai-agents:extensions:twilio*를 사용하여 Twilio 어댑터의 디버그 로그만 활성화할 수 있습니다.
전체 서버 코드 예제
섹션 제목: “전체 서버 코드 예제”실행 가능한 Twilio 코드 예제에는 인증 기능이 포함된 Fastify 라우트와 Realtime 세션 설정이 포함되어 있습니다. 해당 README에는 필수 서버 측 설정인 OPENAI_API_KEY, TWILIO_AUTH_TOKEN, TWILIO_PUBLIC_BASE_URL이 설명되어 있습니다. 공개 기본 URL은 경로 접두사, 쿼리 문자열, 프래그먼트가 없는 HTTPS 오리진입니다. 터널의 공개 오리진이 변경되면 해당 설정을 업데이트하세요.
서버는 Realtime 연결을 열기 전에 서명이 유효하지 않은 통화 및 업그레이드 요청을 거부합니다. Twilio Media Stream URL은 wss://를 사용하며 쿼리 매개변수를 지원하지 않습니다. 사용자 지정 매개변수에 대해서는 Twilio Stream 문서를 참고하세요.