OpenAI Realtime API로 음성 에이전트 구축하기: 7단계 프로덕션 튜토리얼 (2026)
우리의 테스트 에이전트는 Twilio 전화를 받아 발신자가 말을 멈춘 지 1.1초 만에 첫 단어를 말했습니다. 이는 semantic_vad를 사용한 gpt-realtime-2 모델로 40회의 통화에 대해 측정한 p50(중앙값) 왕복 지연 시간입니다. 마법이 아닙니다. OpenAI Realtime API는 하나의 소켓 내에서 음성 대 음성(Speech-to-Speech) 처리를 수행하므로, STT → LLM → TTS 릴레이 과정에서 약 600ms의 오버헤드가 발생하는 것을 건너뜁니다. 하지만 기본 설정만으로는 1초대의 응답 속도를 달성할 수 없습니다. 다음은 우리가 실제로 배포한 7단계 구축 과정과 코드, 그리고 지연 시간 표입니다.
이 글은 개념 설명서가 아닌 실제 구축 튜토리얼입니다. 먼저 계층별 분석이 필요하다면 AI 음성 에이전트가 실제로 무엇인지를 읽고 돌아오세요. 아래의 모든 내용은 OpenAI API 키와 Node 런타임 환경을 보유하고 있다고 가정합니다.
주요 요약:
- gpt-realtime-2는 하나의 소켓에서 음성 대 음성을 처리하므로 STT/LLM/TTS 릴레이가 필요 없어 약 600ms를 절약합니다.
- 서버 측에서 **일회성 키(Ephemeral keys)**를 발급하세요. 표준 API 키를 브라우저에 노출해서는 안 됩니다.
- Twilio 미디어 스트림은 8kHz μ-law 형식입니다. Realtime API를 위해 24kHz PCM16으로 리샘플링해야 합니다.
- 우리는 p50 1.1초 / p95 1.9초의 왕복 지연 시간을 측정했습니다. 끼어들기(Barge-in)는
response.cancel을 통해 처리됩니다.
7단계로 구축할 내용
이 튜토리얼에서는 1.5초 이내에 응답하고, 대화 중간에 실제 함수를 호출하며, 발신자의 끼어들기를 허용하는 전화 응답용 OpenAI Realtime API 음성 에이전트를 구축합니다. 흐름은 간단합니다. 발신자가 전화번호로 전화를 걸면, 오디오가 서버로 스트리밍되고, 서버는 단일 소켓을 통해 이를 gpt-realtime-2에 연결합니다. 모델이 답변을 말하고 도구 호출을 트리거할 수 있으며, 오디오는 다시 사용자에게 스트리밍됩니다.
다음은 진행 경로이며, 사용 사례에 맞는 단계에서 중단해도 됩니다.
- 일회성 키 발급 (서버 라우트)
- 세션 열기 및 구성
- 함수 호출 추가
- Twilio로 전화번호에 브리지 연결
- 끼어들기(Barge-in) 및 중단 처리
- 지연 시간을 1초 미만으로 조정
- 배포 및 보안 강화
오디오를 전달하는 세 가지 전송 방식(Transport)이 있으며, 선택은 오디오 소스에 따라 달라집니다. 브라우저에서 직접 캡처하는 경우(WebRTC), 서버에 이미 RAW 스트림이 있는 경우(WebSocket), 또는 전화 네트워크를 통해 전달되는 경우(SIP)입니다. 우리는 Twilio 브리지를 위해 WebSocket을 사용할 것이며, 다른 방식이 적합한 곳에서는 이를 언급하겠습니다.
1단계: 일회성 키 발급 (생략할 수 없는 라우트)
표준 OpenAI API 키를 브라우저나 클라이언트 장치에 절대 노출하지 마십시오. Realtime API는 이를 위해 단기적인 **일회성 키(Ephemeral keys)**를 발급합니다. 서버는 실제 키를 사용하여 POST /v1/realtime/client_secrets를 호출하고, 클라이언트에게 약 1분 후 만료되는 토큰을 전달합니다. 클라이언트는 이 토큰을 사용하여 연결합니다.
다음은 일회성 키를 발급하는 최소한의 Express 라우트 예제입니다.
// server.js
import express from "express";
const app = express();
app.get("/session", async (req, res) => {
const r = await fetch("https://api.openai.com/v1/realtime/client_secrets", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.OPENAI_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
session: { type: "realtime", model: "gpt-realtime-2" },
}),
});
const data = await r.json();
res.json({ client_secret: data.value, expires_at: data.expires_at });
});
app.listen(3000);브라우저는 /session을 fetch하여 단기 시크릿을 읽은 뒤, 이를 사용하여 Realtime 연결을 엽니다. 에이전트가 서버 전용인 경우(4단계의 Twilio 사례), 클라이언트 핸드오프를 건너뛰고 백엔드에서 표준 키를 사용하여 직접 소켓을 열 수 있습니다. 일회성 키 흐름은 신뢰할 수 없는 클라이언트를 보호하기 위해 존재합니다.
2단계: 세션 열기 및 gpt-realtime-2 구성
연결을 연 후, 모델, 오디오 형식, 목소리 및 턴 감지(Turn detection)를 설정하는 session.update를 전송합니다. OpenAI 문서는 reasoning.effort를 low로 설정하고 도구 로직이 더 높은 정확도를 필요로 할 때만 높일 것을 권장합니다. 높은 effort 설정은 지연 시간을 증가시키기 때문입니다. 오디오는 양방향 모두 24kHz PCM16 형식으로 실행됩니다.
ws.send(JSON.stringify({
type: "session.update",
session: {
type: "realtime",
model: "gpt-realtime-2",
output_modalities: ["audio"],
audio: {
input: { format: "pcm16", sample_rate: 24000 },
output: { format: "pcm16", sample_rate: 24000, voice: "marin" },
},
instructions: "You are a reservations agent for a restaurant. Be brief.",
reasoning: { effort: "low" },
turn_detection: { type: "semantic_vad" },
},
}));소켓을 어떤 전송 방식으로 감싸느냐는 오디오 소스에 따라 달라집니다.
| 전송 방식 (Transport) | 사용 시기 | 오디오 소스 |
|---|---|---|
| WebRTC | 브라우저 또는 모바일 앱이 마이크를 직접 캡처할 때 | 클라이언트 장치 |
| WebSocket | 서버가 이미 RAW 오디오 스트림을 보유할 때 | 서버 파이프라인 |
| SIP | OpenAI가 전화 구간을 직접 처리하도록 할 때 | PSTN / 전화망 |
전체 세션 필드 목록과 GA(일반 제공) 기능 세트에 대해서는 OpenAI Realtime API 문서가 공식 출처입니다. 우리는 4단계에서 Twilio가 RAW 오디오를 전달하므로 WebSocket을 사용할 것입니다.
3단계: 함수 호출 추가 (에이전트가 실제로 작업을 수행하도록)
작업을 수행할 수 없는 음성 에이전트는 단순한 내레이션에 불과합니다. **함수 호출(Function calling)**은 gpt-realtime-2가 대화 중간에 일시 중지하고 코드를 실행하도록 요청한 후, 그 결과와 함께 대화를 계속 이어갈 수 있게 합니다. 세션에서 도구를 선언하면, 모델이 필요할 때 function_call_arguments.done 이벤트를 발생시킵니다. 이때 작업을 수행하고 결과를 다시 전송합니다.
도구를 선언하고 이벤트를 처리하는 방법은 다음과 같습니다.
// in session.update -> session.tools:
tools: [{
type: "function",
name: "book_reservation",
description: "Book a table for a given party size and time.",
parameters: {
type: "object",
properties: {
party_size: { type: "integer" },
time: { type: "string", description: "ISO 8601 datetime" },
},
required: ["party_size", "time"],
},
}]
// handling the call:
if (event.type === "response.function_call_arguments.done") {
const args = JSON.parse(event.arguments);
const result = await bookTable(args); // your real logic
ws.send(JSON.stringify({
type: "conversation.item.create",
item: {
type: "function_call_output",
call_id: event.call_id,
output: JSON.stringify(result),
},
}));
ws.send(JSON.stringify({ type: "response.create" })); // let it speak the result
}도구가 묵묵부답으로 전혀 실행되지 않는 가장 흔한 원인: function_call_arguments.done를 수신 대기하지 않고 이후에 response.create를 전송하지 않는 경우입니다. 모델이 호출을 생성했는데 무시해 버리면, 발신자는 침묵만 듣게 됩니다.
에이전트가 많은 도구를 다루어야 한다면, OpenAI Agents SDK가 판도를 바꿨습니다. 2026년 4월 15일의 대규모 개편으로 Model Context Protocol(MCP)이 일급 시민(first-class)이 되었으며, 하위 에이전트(Sub-agent) 간의 인수인계가 런타임 기본 요소로 전환되었습니다. 따라서 모든 도구를 하나의 프롬프트에詰め넣는 대신, 라우터 에이전트가 예약 업무를 예약 하위 에이전트로, 청구 관련 질문을 다른 하위 에이전트로 넘길 수 있습니다. Agents SDK 음성 퀵스타트는 동일한 Realtime 세션을 RealtimeAgent로 감싸고, 자체 오케스트레이션 루프를 작성하지 않고도 인수인계를 가능하게 합니다.
4단계: 전화번호에 브리지 연결 (Twilio)
실제 전화를 받기 위해서는 통신사 공급자를 소켓에 브리지로 연결해야 합니다. Twilio를 사용하는 경우, 수신 전화를 서버로 WebSocket을 여는 TwiML <Connect><Stream>으로 향하게 하고, Twilio와 Realtime API 사이에서 오디오 프레임을 중계합니다. SIP는 대안입니다. OpenAI Realtime은 SIP를 직접 수용하므로, 오디오를 조작할 필요가 없다면 미디어 중계 계층을 완전히 제거할 수 있습니다.
스트림을 시작하는 TwiML은 다음과 같습니다.
<Response>
<Connect>
<Stream url="wss://your-server.com/twilio-stream" />
</Connect>
</Response>여기서 놓치면 하루를 날릴 수 있는 함정이 있습니다. Twilio의 미디어 스트림은 8kHz μ-law 형식인 반면, Realtime API는 24kHz PCM16을 요구합니다. 양방향으로 리샘플링을 수행하지 않으면 오디오가 깨지거나 '칩멍크(Chipmunk)'처럼 들리게 됩니다.
// inbound: Twilio (8kHz μ-law base64) -> Realtime (24kHz PCM16)
const pcm16 = upsample(muLawDecode(Buffer.from(msg.media.payload, "base64")), 8000, 24000);
realtime.send(JSON.stringify({
type: "input_audio_buffer.append",
audio: pcm16.toString("base64"),
}));
// outbound: Realtime (24kHz PCM16) -> Twilio (8kHz μ-law)
const ulaw = muLawEncode(downsample(modelPcm16, 24000, 8000));
twilioWs.send(JSON.stringify({
event: "media",
media: { payload: ulaw.toString("base64") },
}));전체 프레임 형식은 Twilio Media Streams 문서에 나와 있습니다. 리샘플링은 가볍게 유지하세요. 무거운 라이브러리를 사용하면 모든 프레임에서 지불해야 하는 지연 시간이 추가되기 때문입니다.
5단계: 끼어들기(Barge-in) 및 중단 처리
프로덕션 수준의 에이전트는 발신자가 말하는 동안에도 대응할 수 있어야 합니다. **끼어들기(Barge-in)**란 에이전트가 문장을 말하는 중간에 발신자가 말을 시작했음을 감지하고, 에이전트의 발언을 깔끔하게 끊는 것을 의미합니다. Realtime API는 response.cancel을 통해 이를 처리합니다. 재생 중에 턴 감지가 음성 시작을 보고하면, 활성 응답을 취소하고 발신자에게 버퍼링된 오디오를 즉시 플러시합니다.
if (event.type === "input_audio_buffer.speech_started") {
realtime.send(JSON.stringify({ type: "response.cancel" }));
twilioWs.send(JSON.stringify({ event: "clear" })); // drop queued playback
}턴 감지에는 두 가지 모드가 있으며, 선택이 중요합니다. server_vad는 RAW 침묵 임계값을 기반으로 트리거되며 자연스러운 일시 정지에서도 발신자의 말을 끊는 경향이 있습니다. semantic_vad는 모델이 발신자가 실제로 생각을 마쳤다고 판단할 때까지 기다리므로, 생각에 잠긴 일시 정지에서의 잘못된 끼어들기가 훨씬 적습니다. 전화 통화의 경우, 인간처럼 느껴지게 하는 것은 semantic VAD입니다.
6단계: 지연 시간을 1초 미만으로 조정
데모가 제품이 되는 지점입니다. 이론적인 예산이 아닌, 우리 직접 구축한 시스템에서 측정한 실제 숫자를 소개합니다. 2026년 5월, OpenAI 리전 근처에 colocated된 작은 서버 하나에서 동일한 레스토랑 에이전트로 40회의 테스트 통화를 진행했으며, 턴 감지 및 추론 설정만 변경했습니다.
| 구성 | p50 왕복 지연 시간 | p95 | 비고 |
|---|---|---|---|
| server_vad, reasoning low | ~1.4초 | ~2.3초 | 일시 정지 시 잘못된 끼어들기 증가 |
| semantic_vad, reasoning low | ~1.1초 | ~1.9초 | 우리의 프로덕션 기본값 |
| semantic_vad, reasoning medium | ~1.8초 | ~3.1초 | 도구 정확도는 높지만 느림 |
실제로 효과를 본 레버들은 영향력 순서대로 다음과 같습니다.
- 특정 도구가 정말로 정확도를 필요로 하지 않는 한
reasoning.effort를 낮게 유지하세요. Medium 설정은 우리의 p50 지연 시간을 거의 두 배로 늘렸습니다. - 실시간보다 빠르게 오디오를 푸시하지 마세요.
input_audio_buffer.append를 과도하게 채우면 버퍼 오버런과 드리프트가 발생합니다. 프레임을 벽시계 시간(wall-clock time)에 맞춰 조절하세요. - 소켓을 따뜻하게(Warm) 유지하세요. 호출마다 연결을 새로 열면(first-word latency) 핸드셰이크 시간이 첫 단어 지연 시간에 추가됩니다. 호출량이 허용하는 범위에서 연결을 풀링(Pooling)하세요.
- 효율적으로 리샘플링하세요. 핫 패스(Hot path)에서 naive한 리샘플러를 사용하면 턴당 약 80ms가 추가되었습니다.
라이브 환경에서 분당 비용은 얼마나 될까요? BYOK(Bring Your Own Key) 비용 계산은 별도로 진행했습니다. 여기서 다시 유도하기보다는 BYOK 음성 에이전트의 분당 비용을 참조하세요.
7단계: 프로덕션을 위한 배포 및 보안 강화
"내 노트북에서는 작동했는데"와 "하루 500통의 전화를 견디는 것" 사이의 차이는 잘 알려진 몇 가지 실패 사례에 달려 있습니다. 다음은 Realtime 에이전트를 실제로 망가뜨리는 실수들에서 추출한 보안 강화 체크리스트입니다.
| 함정 | 증상 | 해결책 |
|---|---|---|
| 잘못된 샘플 레이트 | 깨진 오디오 / 칩멍크 소리 | 양방향 24kHz PCM16 사용 |
function_call_arguments.done 무시 | 도구가 전혀 실행되지 않음 | 수신 대기 후 response.create 전송 |
| 실시간보다 빠른 오디오 푸시 | 버퍼 오버런, 드리프트 | 프레임을 실시간 속도에 맞춰 조절 |
| 재연결 로직 부재 | 소켓 불안정 시 통화 끊김 | 자동 재연결 + 세션 재개 |
response.done 처리 부재 | 턴 중복 | 다음 턴을 response.done에 따라 게이트 처리 |
실제 트래픽을 위해 두 가지 사항을 더 추가합니다. 긴 통화의 경우, 컨텍스트가 드리프트되지 않도록 여러 턴마다 세션을 회전하거나 재설정하세요. 20분간의 통화는 모델이 헛갈리기 시작할 정도의 상태를 누적합니다. 또한 모든 도구 호출과 그 인수, 결과를 로그로 남기세요. 발신자가 "에이전트가 잘못된 시간을 예약했다"고 말할 때, 기록만으로는 모델의 실수인지 코드의 실수인지 알 수 없기 때문입니다.
3단계에서 Agents SDK 경로를 채택한다면, 새로운 컨테이너 샌드박스가 도구 코드를 격리되어 실행합니다. 이는 도구가 단순히 API뿐만 아니라 파일 시스템이나 셸에 접근할 때 중요해집니다.
관리형 플랫폼을 구매해야 할 때
Realtime API를 직접 구축하면 가장 큰 제어권과 가장 낮은 분당 비용을 얻을 수 있지만, 4단계부터 7단계까지의 재연결 로직, 전화 브리지, 규정 준수, 관찰 가능성 등 모든 덜 매력적인 부분을 직접 책임져야 합니다. 이번 주 내에 전화 에이전트를 가동해야 하고 미디어 중계기를 유지보수하고 싶지 않다면, 관리형 플랫폼이 더 빠른 선택입니다.
우리는 동일한 에이전트를 주요 세 가지 플랫폼에서 구축하고 솔직하게 비교했습니다: Retell, Vapi, 또는 Bland. 아직 어느 쪽을 선택할지 결정하지 못했다면, 엔지니어링 시간을 투입하기 전에 완전한 구축 vs 구매 결정 프레임워크를 살펴보세요.
팀이 맞춤형 Realtime 구축의 제어권을 원하지만 이를 담당할 인력이 부족할 때, 이것이 우리가 하는 작업입니다: 프로덕션 음성 에이전트 개발, 전화 브리지부터 위의 지연 시간 튜닝까지. 고려 중이라면 귀하의 사용 사례를 검토해 드릴 수 있습니다.
저자 소개 — Mert Batur Gurbuz는 Techsy.io의 공동 창업자로, 팀은 B2B 고객을 위해 AI 에이전트, 자동화 시스템, 음성/SDR 파이프라인을 제공합니다. 그는 버밍엄 대학교에서 공부하며, Techsy 팀이 프로덕션에서 실제로 사용하는 LLM 툴링 스택에 대해 글을 씁니다. LinkedIn
자주 묻는 질문
OpenAI Realtime API 음성 에이전트의 지연 시간은 얼마인가요?
semantic_vad와 낮은 추론 Effort를 사용한 gpt-realtime-2 기반의 우리 구축 환경에서, 40회의 테스트 통화에 대해 측정한 왕복 지연 시간은 p50 1.1초 및 p95 1.9초였습니다. 하나의 소켓에서의 음성 대 음성 처리는 STT/LLM/TTS 릴레이를 피하게 해주며, 이것이 1초 미만의 응답을 가능하게 하는 핵심 요소입니다.
음성 에이전트에 WebRTC, WebSocket, SIP 중 무엇이 필요한가요?
브라우저 또는 모바일 앱이 마이크를 직접 캡처할 때는 WebRTC를, 서버가 이미 RAW 오디오 스트림을 보유할 때(Twilio 브리지 사례)는 WebSocket을, 자체 미디어 중계기 없이 OpenAI가 전화 구간을 처리하도록 할 때는 SIP를 사용하세요. 대부분의 전화 에이전트는 WebSocket 또는 SIP를 사용합니다.
OpenAI Realtime API를 Twilio에 어떻게 연결하나요?
수신 Twilio 전화를 서버로 WebSocket을 여는 TwiML <Connect><Stream>으로 향하게 한 후, Twilio와 Realtime 소켓 사이에서 오디오를 중계하세요. 오디오가 깨지는 것을 방지하려면 Twilio의 8kHz μ-law를 API의 24kHz PCM16으로 양방향 리샘플링해야 합니다.
Realtime API에서 함수 호출은 어떻게 작동하나요?
세션 구성에서 도구를 선언합니다. 모델이 도구를 원할 때 function_call_arguments.done 이벤트를 발생시킵니다. 작업을 수행하고 결과를 function_call_output 대화 항목으로 다시 전송한 후, 에이전트가 결과를 말하도록 response.create를 전송합니다. 마지막 단계를 잊어버리는 것이 도구가 "묵묵부답"으로 실패하는 일반적인 이유입니다.
Realtime API에서 끼어들기(Barge-in)는 어떻게 처리하나요?
재생 중에 턴 감지가 input_audio_buffer.speech_started를 보고하면, response.cancel을 전송하여 활성 응답을 중지하고 발신자에게 큐잉된 출력 오디오를 지웁니다. 자연스러운 일시 정지가 문장 중간에 잘못된 끼어들기를 트리거하지 않도록 semantic_vad와 함께 사용하세요.
OpenAI Realtime API는 어떤 오디오 샘플 레이트를 사용하나요?
Realtime API는 양방향 모두 24kHz PCM16 오디오를 사용합니다. Twilio와 같은 통신사 공급자는 8kHz μ-law를 전달하므로, 전화 브리지는 입력 시 업샘플링하고 출력 시 다운샘플링해야 합니다. 샘플 레이트 불일치는 오디오 왜곡의 가장 흔한 원인입니다.
Realtime API에서 음성 에이전트를 운영하는 데 드는 비용은 얼마인가요?
비용은 gpt-realtime-2의 오디오 입력 및 출력 분수에 의해 결정되며, BYOK 경제학은 관리형 분당 플랫폼과 크게 다릅니다. 여기에서 추정하기보다는 음성 에이전트 가격 분석에서 전체 계산을 확인하세요.
Realtime API로 직접 구축해야 할까요, 아니면 Retell, Vapi, Bland를 사용해야 할까요?
최대의 제어권과 가장 낮은 분당 비용을 원하고 재연결, 전화망, 규정 준수를 직접 책임질 수 있다면 직접 구축하세요. 출시 속도가 더 중요하다면 관리형 플랫폼을 구매하세요. Retell vs Vapi vs Bland 비교와 구축 vs 구매 프레임워크에서 장단점을 확인할 수 있습니다.
2026년 4월 OpenAI Agents SDK 업데이트가 음성 에이전트에 어떤 변화를 가져왔나요?
2026년 4월 15일의 대규모 개편으로 Model Context Protocol이 일급 시민이 되었고, 도구 코드를 위한 컨테이너 샌드박스가 추가되었으며, 하위 에이전트 인수인계가 런타임 기본 요소로 전환되었습니다. 음성 에이전트의 경우, 이는 라우터 에이전트가 모든 도구를 하나의 프롬프트에詰め넣는 대신 전문 하위 에이전트로 업무를 넘길 수 있음을 의미합니다.