빠른 시작
프로젝트 설정 및 인증 정보
섹션 제목: “프로젝트 설정 및 인증 정보”-
프로젝트 생성
이 빠른 시작에서는 브라우저에서 사용할 수 있는 음성 에이전트를 만듭니다. 새 프로젝트의 기본 구조를 생성하려면
Next.js또는Vite로 시작할 수 있습니다.터미널 창 npm create vite@latest my-project -- --template vanilla-ts -
권장 패키지 설치 (Zod v4 필요)
터미널 창 npm install @openai/agents zod -
클라이언트 임시 토큰 생성
이 애플리케이션은 사용자의 브라우저에서 실행되므로 Realtime API를 통해 모델에 안전하게 연결할 방법이 필요합니다. 권장 흐름은 공식 WebRTC를 사용하는 Realtime API 가이드와 같습니다. 백엔드에서 수명이 짧은 클라이언트 임시 토큰을 생성하면 브라우저는 이 토큰으로 WebRTC 연결을 설정합니다. 테스트 목적으로는
curl과 일반 OpenAI API 키를 사용해 토큰을 생성할 수도 있습니다.터미널 창 export OPENAI_API_KEY="sk-proj-...(your own key here)"curl -X POST https://api.openai.com/v1/realtime/client_secrets \-H "Authorization: Bearer $OPENAI_API_KEY" \-H "Content-Type: application/json" \-d '{"session": {"type": "realtime","model": "gpt-realtime-2.1"}}'응답에는
ek_접두사로 시작하는 최상위value필드와 실제로 적용된session객체가 포함됩니다. WebRTC 연결을 설정할 때value를 클라이언트 시크릿으로 사용하세요. 이 토큰은 수명이 짧으므로 필요할 때 백엔드에서 새 토큰을 발급해야 합니다. 브라우저 세션에authorization또는 사용자 지정headers를 사용하는 호스티드 MCP 도구가 필요하다면, 해당 인증 정보를 브라우저 코드에 노출하는 대신POST /v1/realtime/client_secrets로 보내는 서버 측session페이로드에 해당 호스티드 MCP 구성을 포함하세요.
음성 에이전트 생성 및 연결
섹션 제목: “음성 에이전트 생성 및 연결”-
첫 에이전트 생성
새
RealtimeAgent를 만드는 과정은 일반Agent를 만드는 과정과 매우 비슷합니다.import { RealtimeAgent } from '@openai/agents/realtime';const agent = new RealtimeAgent({name: 'Assistant',instructions: 'You are a helpful assistant.',}); -
세션 생성
일반 에이전트와 달리 음성 에이전트는
RealtimeSession안에서 계속 실행되며, 이 세션은 대화와 모델 연결을 지속적으로 처리합니다. 또한 오디오 처리, 인터럽션(중단 처리), 이후에 구성할 전반적인 대화 수명 주기를 관리합니다.import { RealtimeSession } from '@openai/agents/realtime';const session = new RealtimeSession(agent, {model: 'gpt-realtime-2.1',});RealtimeSession생성자는 첫 번째 인수로agent를 받습니다. 이 에이전트는 사용자가 처음으로 상호작용하는 에이전트가 됩니다. -
세션 연결
세션에 연결하려면 앞서 생성한 클라이언트 임시 토큰을 전달해야 합니다.
await session.connect({ apiKey: 'ek_...(put your own key here)' });브라우저에서는 WebRTC를 사용해 Realtime API에 연결하고 마이크 캡처와 오디오 재생을 자동으로 설정합니다. 이 기본 WebRTC 경로에서 SDK는 데이터 채널이 열리는 즉시 초기 세션 구성을 전송하고,
connect()가 완료되기 전에 해당 구성에 대한session.updated확인 응답을 기다리려고 시도합니다. 확인 응답이 오지 않으면 타임아웃 시 대체 동작으로 진행합니다. Node.js와 같은 서버 런타임에서RealtimeSession을 실행하면 SDK는 자동으로 WebSocket을 대신 사용합니다. WebSocket 경로에서는 소켓이 열리고 초기 구성이 전송된 후connect()가 완료되므로session.updated는 조금 늦게 도착할 수 있습니다. 전송 방식 선택에 관한 자세한 내용은 전송 방식 가이드에서 확인할 수 있습니다.
앱 실행 및 테스트
섹션 제목: “앱 실행 및 테스트”-
전체 코드 통합
import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';async function main() {const agent = new RealtimeAgent({name: 'Assistant',instructions: 'You are a helpful assistant.',});const session = new RealtimeSession(agent, {model: 'gpt-realtime-2.1',});// Automatically connects your microphone and audio output in the browser via WebRTC.try {await session.connect({// To get this ephemeral key string, you can run the following command or implement the equivalent on the server side:// curl -s -X POST https://api.openai.com/v1/realtime/client_secrets -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" -d '{"session": {"type": "realtime", "model": "gpt-realtime-2.1"}}' | jq .valueapiKey: 'ek_...(put your own key here)',});console.log('You are connected!');} catch (e) {console.error(e);}}main().catch(console.error); -
앱 실행 및 대화 시작
웹 서버를 시작하고 새 음성 에이전트 코드가 포함된 페이지를 여세요. 마이크 권한 요청이 표시됩니다. 접근을 허용하면 에이전트와 대화를 시작할 수 있습니다.
터미널 창 npm run dev
다음 단계
섹션 제목: “다음 단계”이제 나만의 음성 에이전트를 설계하고 구축할 수 있습니다.
- 도구, 핸드오프, 가드레일을 추가하세요.
- 턴 감지 및 음성 활동 감지, 인터럽션(중단 처리), 수동 응답 제어가 대화 루프에 미치는 영향을 알아보세요.
- 텍스트 입력, 이미지 입력, 세션 기록 관리를 추가하세요.
- 배포 환경에 적합한 전송 방식을 선택하세요. WebRTC, WebSocket, 사용자 지정 전송 방식 중에서 선택할 수 있습니다.