빠른 시작

프로젝트 설정 및 자격 증명

프로젝트 생성

이 빠른 시작에서는 브라우저에서 사용할 수 있는 실시간 에이전트를 생성합니다. 새 프로젝트의 기본 구조를 만들려면 Next.js 또는 Vite로 시작할 수 있습니다.
Terminal window
```
npm create vite@latest my-project -- --template vanilla-ts
```
권장 패키지 설치(Zod v4 필요)
Terminal window
```
npm install @openai/agents zod
```
클라이언트 임시 토큰 생성

이 애플리케이션은 사용자의 브라우저에서 실행되므로 Realtime API를 통해 모델에 안전하게 연결할 방법이 필요합니다. 권장 흐름은 공식 WebRTC를 사용하는 Realtime API 가이드와 같습니다. 백엔드에서 수명이 짧은 임시 클라이언트 토큰을 생성한 다음, 브라우저가 해당 토큰을 사용하여 WebRTC 연결을 설정합니다. 테스트 목적으로는 curl과 일반 OpenAI API 키를 사용하여 토큰을 생성할 수도 있습니다.
Terminal window
```
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 .value
      apiKey: 'ek_...(put your own key here)',
    });
    console.log('You are connected!');
  } catch (e) {
    console.error(e);
  }
}

main().catch(console.error);

앱 실행 및 대화 시작

웹 서버를 시작하고 새로운 Realtime 에이전트 코드가 포함된 페이지를 여세요. 마이크 권한 요청이 표시됩니다. 접근 권한을 부여하면 에이전트와 대화를 시작할 수 있습니다.
Terminal window
```
npm run dev
```

다음 단계

이제 다음과 같이 자신만의 실시간 에이전트를 설계하고 구축할 수 있습니다.

도구, 핸드오프, 가드레일을 추가합니다.
턴 감지 및 음성 활동 감지, 인터럽션(중단 처리), 수동 응답 제어가 대화 루프에 미치는 영향을 알아봅니다.
텍스트 입력, 이미지 입력, 세션 기록 관리를 추가합니다.
배포 환경에 적합한 전송 방식을 선택합니다. WebRTC, WebSocket, 사용자 지정 전송 방식 중에서 선택할 수 있습니다.