Realtime API 시작하기

Realtime API 시작하기

Realtime API로 음성-음성 음성 에이전트를 만드는 방법을 알아볼게요. 이 모델은 오디오를 직접 처리하고 대화 상태를 유지하면서 도구도 호출할 수 있어요. 이 가이드는 브라우저 애플리케이션을 기준으로 Agents SDK부터 시작하고, 더 낮은 레벨의 제어가 필요할 때는 연결 가이드를 따로 참고하면 됩니다. 별도의 위임 백엔드로 전이중(풀-듀플렉스) 대화가 필요하다면 GPT-Live 가이드를, 여러 음성 아키텍처를 비교하고 싶다면 Voice agents 문서를 보세요.

출처: 공식문서

음성-음성 에이전트 만들기

Realtime API는 상호작용이 대화처럼 자연스럽고 즉각적이어야 할 때 가장 어울려요. barg-in(말하는 중 끼어들기), 낮은 첫 오디오 지연, 자연스러운 턴 테이킹, 실시간 도구 사용이 필요한 음성 에이전트라면 여기가 최적의 출발점입니다.

일반적인 브라우저 흐름은 이렇게 진행돼요:

  1. 애플리케이션 서버가 Realtime 세션용 임시 클라이언트 시크릿을 만든다.
  2. 프론트엔드가 RealtimeSession을 생성한다.
  3. 세션이 브라우저에선 WebRTC로, 서버에선 WebSocket으로 연결된다.
  4. 에이전트가 그 세션 안에서 오디오 턴·도구·인터럽션·핸드오프를 처리한다.

Realtime 음성 세션 시작:

import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";

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: *** key from your server)",
});

이 지점부터는 텍스트 에이전트에 붙이던 것과 같은 방식으로 RealtimeAgent에 도구·핸드오프·가드레일을 붙이면 됩니다. 오디오 전송 같은 우려는 세션 레이어에, 비즈니스 로직은 에이전트 정의에 두는 걸 권장해요.

더 낮은 레벨의 제어가 필요할 때는 전송 문서부터 시작하세요:

안전 식별자(Safety identifiers)

애플리케이션이 개별 최종 사용자를 식별한다면 Realtime API 요청에 안전 식별자를 포함해 보세요. OpenAI는 안전 식별자를 권장하지만 필수로 요구하지는 않아요. 이 값은 유해 행위 감지와 집행 대상을 조직 전체가 아니라 특정 사용자로 좁히는 데 도움을 줍니다. 해시된 내부 사용자 ID처럼 안정적이고 프라이버시를 보호하는 값을 쓰면 됩니다.

Realtime 요청에서는 이 식별자를 OpenAI-Safety-Identifier 헤더로 보내요. 임시 토큰을 쓸 때는 클라이언트 시크릿을 만드는 서버 측 요청에 헤더를 실어 세션과 연결하고, WebSocket이나 통합 WebRTC 인터페이스로 신뢰 서버에서 연결할 때는 연결 요청에 헤더를 설정하면 됩니다.

안전 식별자는 Responses API 요청이나 다른 세션으로 이어지지 않아요. 애플리케이션 다른 곳에서 Responses API의 safety_identifier 파라미터를 쓴다면, Realtime 세션을 만들거나 연결할 때도 같은 안정적인 값을 넘겨 주세요.

베타에서 GA로 마이그레이션

아직 베타 Realtime 통합을 쓰고 있다면 새 작업을 진행하기 전에 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 같은 새 응답 이벤트 이름을 사용한다.
  • 음성-음성 앱을 앞으로 이전한다면 브라우저 예제에서, 전사 워크플로를 이전한다면 Realtime transcription 문서에서 시작한다.

현재 GA 흐름은 Realtime 클라이언트 이벤트 레퍼런스, Realtime 세션 레퍼런스, 그리고 브라우저 예제에서 확인할 수 있어요.

다음 단계

다른 오디오 워크플로

워크플로 선택기와 공통 오디오 용어는 이제 오디오와 음성 문서로 옮겨졌습니다. 지속적인 번역에는 Live translation을, 실시간 자막에는 Live transcription을, 녹음된 오디오에는 File transcription을 쓰면 돼요.

더 알아보기 (Learn more)