Realtime API로 음성-음성 변환 에이전트를 만들어 보세요. 모델은 오디오를 직접 처리하고 대화 상태를 유지하며 도구를 호출할 수 있습니다. 이 가이드에서는 먼저 Agents SDK로 브라우저 애플리케이션을 만드는 방법을 살펴봅니다. 연결을 직접 제어해야 한다면 하위 수준의 연결 가이드를 참고하세요.
별도 백엔드에 처리를 위임하는 전이중 대화 방식은 GPT-Live를 참고하세요. 음성 아키텍처와 여러 처리 단계를 연결한 파이프라인을 비교하려면 음성 에이전트를 참고하세요.
음성-음성 변환 에이전트 만들기
자연스러운 대화처럼 즉각적인 응답이 필요할 때는 Realtime API를 사용하세요. 사용자가 에이전트의 말에 끼어들 수 있어야 하고, 첫 음성 응답까지 걸리는 시간이 짧아야 하며, 자연스럽게 발언을 주고받고 실시간으로 도구를 사용해야 한다면 Realtime API로 시작하는 것이 가장 좋습니다.
일반적인 브라우저 연결 플로우는 다음과 같습니다.
- 애플리케이션 서버에서 Realtime 세션용 임시 클라이언트 시크릿을 생성합니다.
- 프런트엔드에서
RealtimeSession을 생성합니다. - 세션을 연결할 때 브라우저에서는 WebRTC를, 서버에서는 WebSocket을 사용합니다.
- 에이전트는 해당 세션에서 음성 대화 턴, 도구 사용, 끼어들기, 핸드오프를 처리합니다.
import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";
const ephemeralKey = process.env.OPENAI_REALTIME_EPHEMERAL_KEY;
if (!ephemeralKey)
throw new Error("Set OPENAI_REALTIME_EPHEMERAL_KEY from your server.");
const agent = new RealtimeAgent({
name: "Assistant",
instructions: "You are a helpful voice assistant.",
});
const session = new RealtimeSession(agent, {
model: "gpt-realtime-2.1",
});
await session.connect({
apiKey: ephemeralKey,
});그다음에는 텍스트 에이전트를 구성할 때와 같은 방식으로 RealtimeAgent에 도구, 핸드오프, 가드레일을 추가하세요. 오디오 전송은 세션 계층에서 처리하고 비즈니스 로직은 에이전트 정의에 두세요.
전송 방식을 더 세밀하게 제어해야 한다면 다음 문서부터 살펴보세요.
안전 식별자
애플리케이션에서 최종 사용자를 개별적으로 식별한다면 Realtime API 요청에 안전 식별자를 포함하세요. OpenAI는 안전 식별자 사용을 권장하지만 필수로 요구하지는 않습니다. 안전 식별자가 있으면 OpenAI가 유해한 행동을 감지하고 조직 전체에 조치를 취하는 대신 해당 사용자로 조치 대상을 한정할 수 있습니다. 해시 처리한 내부 사용자 ID처럼 사용자마다 일관되게 유지되면서 개인정보를 보호하는 값을 사용하세요.
Realtime API 요청에서는 OpenAI-Safety-Identifier 헤더에 식별자를 담아 보내세요. 임시 토큰을 사용하는 경우, 서버에서 클라이언트 시크릿을 생성하는 요청에 이 헤더를 설정해 식별자를 세션에 연결하세요. 신뢰할 수 있는 서버에서 WebSocket 또는 통합 WebRTC 인터페이스로 연결하는 경우에는 연결 요청에 헤더를 설정하세요.
Responses API 요청이나 다른 세션에 사용한 안전 식별자는 새 세션에 자동으로 전달되지 않습니다. 애플리케이션의 다른 부분에서 Responses API의 safety_identifier 매개변수를 사용한다면 Realtime 세션을 생성하거나 연결할 때마다 동일한 값을 전달하세요.
베타에서 정식 버전(GA)으로 마이그레이션하기
애플리케이션에서 아직 베타 버전의 Realtime API를 사용한다면 새 작업을 시작하기 전에 GA 인터페이스로 마이그레이션하세요. 주요 변경 사항은 다음과 같습니다.
- GA 인터페이스를 호출할 때는
OpenAI-Beta: realtime=v1헤더를 제거하세요. POST /v1/realtime/client_secrets를 사용해 브라우저 또는 모바일 클라이언트용 임시 인증 정보를 생성하세요.- WebRTC 세션을 연결할 때는
/v1/realtime/calls를 사용하세요. - GA 인터페이스에 맞게 세션과 이벤트의 데이터 구조를 업데이트하세요. 특히
session.type을 설정하고 출력 오디오 설정을session.audio.output아래로 옮기세요. 응답 이벤트에는response.output_text.delta,response.output_audio.delta,response.output_audio_transcript.delta와 같은 새 이름을 사용하세요. - 음성-음성 변환 앱을 마이그레이션한다면 브라우저 예제부터 살펴보세요. 전사 워크플로우를 마이그레이션한다면 실시간 전사를 참고하세요.
현재 GA 플로우는 Realtime 클라이언트 이벤트 레퍼런스, Realtime 세션 레퍼런스, 브라우저 예제에서 확인할 수 있습니다.
다음 단계
- 대화 관리에서 세션을 구성하고 오디오, 텍스트, 이벤트를 처리하는 방법을 알아보세요.
- 음성 활동 감지에서 대화 턴을 자동으로 감지하도록 설정하는 방법을 알아보세요.
- 도구 및 MCP에서 함수, MCP 서버, 커넥터를 추가하는 방법을 알아보세요.
- 음성 모델용 프롬프트 작성에서 사용 중인 Realtime 모델에 맞는 가이드를 참고하세요.
- 비용 최적화에서 Realtime 사용량 집계 방식과 캐싱 방식을 알아보세요.
- 서버 측 제어에서 서버가 도구 실행과 세션 제어를 담당하도록 구성하는 방법을 알아보세요.
기타 오디오 워크플로우
워크플로우 선택 안내와 오디오 공통 용어는 이제 오디오 및 음성에서 확인할 수 있습니다. 음성을 연속으로 번역하려면 실시간 번역을 참고하세요. 실시간 자막을 만들려면 실시간 전사를, 녹음된 오디오를 텍스트로 변환하려면 파일 전사를 참고하세요.