콘텐츠로 이동

Twilio용 음성 에이전트

Twilio는 통화의 원문 오디오를 WebSocket 서버로 전송하는 Media Streams API를 제공합니다. 이 구성을 사용하면 음성 에이전트 개요에 소개된 음성 에이전트를 Twilio에 연결할 수 있습니다. 기본 Realtime Session 전송 계층을 websocket 모드로 사용하여 Twilio에서 수신한 이벤트를 Realtime Session에 연결할 수 있습니다. 다만, 전화 통화는 웹 기반 대화보다 본질적으로 지연 시간이 길기 때문에 올바른 오디오 형식을 설정하고 인터럽션(중단 처리) 타이밍을 직접 조정해야 합니다.

설정을 더 쉽게 할 수 있도록, 인터럽션(중단 처리)과 오디오 전달을 포함하여 Twilio 연결을 처리하는 전용 전송 계층을 만들었습니다.

  1. Twilio 계정과 Twilio 전화번호가 있는지 확인합니다.

  2. Twilio의 요청을 인증하는 서버를 설정합니다.

    로컬에서 개발하는 경우, Twilio가 로컬 서버에 접근할 수 있도록 ngrok 또는 Cloudflare Tunnel과 같은 로컬 터널을 구성해야 합니다. 서버는 전송 계층을 생성하거나 OpenAI에 연결하기 전에 수신 통화 웹훅과 WebSocket 업그레이드 요청 모두에서 X-Twilio-Signature를 검증해야 합니다. 공식 Twilio 요청 검증 도구, 계정의 기본 Auth Token, 그리고 미리 설정한 공개 URL을 사용하세요. 요청의 Host 헤더나 전달 헤더에서 해당 URL을 도출해서는 안 됩니다. TwilioRealtimeTransportLayer는 이미 인증된 WebSocket을 전달받으며, 어댑터는 HTTP 요청을 인증하지 않습니다.

  3. 확장 패키지를 설치하여 Twilio 어댑터를 설치합니다:

    터미널 창
    npm install @openai/agents-extensions
  4. 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 transport
    transport: twilioTransport,
    });
  5. 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을 사용하는 방법에 관한 자세한 내용은 음성 에이전트 개요를 참고하세요.

  1. 속도가 핵심입니다.

    Twilio에서 필요한 모든 이벤트와 오디오를 수신하려면, 인증된 WebSocket 연결을 사용할 수 있게 되는 즉시 TwilioRealtimeTransportLayer 인스턴스를 생성하고 바로 이어서 session.connect()를 호출해야 합니다.

  2. Twilio 원문 이벤트에 접근합니다.

    Twilio가 전송하는 원문 이벤트에 접근하려면 RealtimeSession 인스턴스의 transport_event 이벤트를 수신하면 됩니다. Twilio의 모든 이벤트는 twilio_message 유형이며, 원문 이벤트 데이터가 담긴 message 속성을 포함합니다.

  3. 디버그 로그를 확인합니다.

    문제가 발생하여 현재 상황에 대한 더 자세한 정보가 필요할 때가 있습니다. 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 문서를 참고하세요.