콘텐츠로 이동

Twilio용 음성 에이전트

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

설정 환경을 개선하기 위해 인터럽션(중단 처리) 처리와 오디오 전달을 비롯하여 Twilio 연결을 담당하는 전용 전송 계층을 만들었습니다.

설정

섹션 제목: “설정”

  1. Twilio 계정과 Twilio 전화번호를 준비합니다.

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

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

  3. extensions 패키지를 설치하여 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라는 type과 원문 이벤트 데이터가 포함된 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 문서를 참조하세요.