Realtime API 시작하기 — 음성 에이전트 빌드

Realtime API 시작하기 — 음성 에이전트 빌드

Realtime API는 스피치 투 스피치 음성 에이전트를 만들기 위한 것이에요. 모델이 오디오를 직접 다루고, 대화 상태를 유지하며, 도구를 호출할 수 있죠. 이 가이드는 브라우저 앱에서 Agents SDK로 시작하고, 더 낮은 레벨의 제어가 필요할 때 연결 가이드를 쓰는 흐름으로 돼 있어요.

출처: https://developers.openai.com/api/docs/guides/realtime

대화적이고 즉각적인 상호작용이 필요할 때 Realtime API를 써요. 보통 브라우저 흐름은:

  1. 앱 서버가 Realtime 세션용 일시적(ephemeral) 클라이언트 시크릿을 만든다.
  2. 프론트엔드가 RealtimeSession을 만든다.
  3. 브라우저에선 WebRTC, 서버에선 WebSocket으로 세션을 연결한다.
  4. 세션 안에서 오디오 턴, 도구, 중단, 핸드오프를 처리한다.
import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";

const agent = new RealtimeAgent({
  model: "gpt-realtime",
  instructions: "You are a concise voice assistant.",
  session: new RealtimeSession({ voice: "alloy" }),
});

전체 문서 인덱스는 llms.txt에서, 페이지별 마크다운은 URL에 .md를 붙여 볼 수 있어요.

더 알아보기