콘텐츠로 이동

빠른 시작

  1. 프로젝트 생성

    이 빠른 시작에서는 브라우저에서 사용할 수 있는 음성 에이전트를 만듭니다. 새 프로젝트의 기본 구조를 생성하려면 Next.js 또는 Vite로 시작할 수 있습니다.

    터미널 창
    npm create vite@latest my-project -- --template vanilla-ts
  2. 권장 패키지 설치 (Zod v4 필요)

    터미널 창
    npm install @openai/agents zod
  3. 클라이언트 임시 토큰 생성

    이 애플리케이션은 사용자의 브라우저에서 실행되므로 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 구성을 포함하세요.

  1. 첫 에이전트 생성

    새 RealtimeAgent를 만드는 과정은 일반 Agent를 만드는 과정과 매우 비슷합니다.

    import { RealtimeAgent } from '@openai/agents/realtime';
    const agent = new RealtimeAgent({
    name: 'Assistant',
    instructions: 'You are a helpful assistant.',
    });
  2. 세션 생성

    일반 에이전트와 달리 음성 에이전트는 RealtimeSession 안에서 계속 실행되며, 이 세션은 대화와 모델 연결을 지속적으로 처리합니다. 또한 오디오 처리, 인터럽션(중단 처리), 이후에 구성할 전반적인 대화 수명 주기를 관리합니다.

    import { RealtimeSession } from '@openai/agents/realtime';
    const session = new RealtimeSession(agent, {
    model: 'gpt-realtime-2.1',
    });

    RealtimeSession 생성자는 첫 번째 인수로 agent를 받습니다. 이 에이전트는 사용자가 처음으로 상호작용하는 에이전트가 됩니다.

  3. 세션 연결

    세션에 연결하려면 앞서 생성한 클라이언트 임시 토큰을 전달해야 합니다.

    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는 조금 늦게 도착할 수 있습니다. 전송 방식 선택에 관한 자세한 내용은 전송 방식 가이드에서 확인할 수 있습니다.

  1. 전체 코드 통합

    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 .value
    apiKey: 'ek_...(put your own key here)',
    });
    console.log('You are connected!');
    } catch (e) {
    console.error(e);
    }
    }
    main().catch(console.error);
  2. 앱 실행 및 대화 시작

    웹 서버를 시작하고 새 음성 에이전트 코드가 포함된 페이지를 여세요. 마이크 권한 요청이 표시됩니다. 접근을 허용하면 에이전트와 대화를 시작할 수 있습니다.

    터미널 창
    npm run dev

이제 나만의 음성 에이전트를 설계하고 구축할 수 있습니다.