빠른 시작

프로젝트 생성

이 빠른 시작에서는 브라우저에서 사용할 수 있는 음성 에이전트를 만듭니다. 새 프로젝트를 시작하고 싶다면 Next.js 또는 Vite를 사용해 볼 수 있습니다.
Terminal window
```
npm create vite@latest my-project -- --template vanilla-ts
```
Agents SDK 설치
Terminal window
```
npm install @openai/agents zod@3
```
또는 독립 실행형 브라우저 패키지로 @openai/agents-realtime를 설치할 수 있습니다.
클라이언트 임시 토큰 생성

이 애플리케이션은 사용자의 브라우저에서 실행되므로 Realtime API를 통해 모델에 안전하게 연결할 방법이 필요합니다. 이를 위해 백엔드 서버에서 생성해야 하는 ephemeral client key를 사용할 수 있습니다. 테스트 목적이라면 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"
     }
   }'
```
응답에는 최상위에 “value” 문자열이 포함되며, “ek_” 접두사로 시작합니다. 이 임시 키로 이후 WebRTC 연결을 설정할 수 있습니다. 이 키는 유효 기간이 짧으므로 재생성이 필요합니다.

첫 번째 에이전트 생성

새로운 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',
});
```
RealtimeSession 생성자는 첫 번째 인자로 agent를 받습니다. 이 에이전트가 사용자가 처음 상호작용할 수 있는 에이전트가 됩니다.
세션에 연결

세션에 연결하려면 앞에서 생성한 클라이언트 임시 토큰을 전달해야 합니다.
```
await session.connect({ apiKey: 'ek_...(put your own key here)' });
```
이는 브라우저에서 WebRTC를 사용해 Realtime API에 연결하고, 오디오 입력과 출력을 위해 마이크와 스피커를 자동으로 구성합니다. RealtimeSession을 백엔드 서버(Node.js 등)에서 실행하는 경우 SDK는 자동으로 연결 방식으로 WebSocket을 사용합니다. 다양한 전송 계층에 대한 자세한 내용은 전송 방식 가이드를 참고하세요.

모두 합쳐서 사용

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

export async function setupCounter(element: HTMLButtonElement) {
  // ....
  // for quickly start, you can append the following code to the auto-generated TS code

  const agent = new RealtimeAgent({
    name: 'Assistant',
    instructions: 'You are a helpful assistant.',
  });
  const session = new RealtimeSession(agent);
  // 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"}}' | jq .value
      apiKey: 'ek_...(put your own key here)',
    });
    console.log('You are connected!');
  } catch (e) {
    console.error(e);
  }
}

엔진 시동 및 대화 시작

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

다음 단계

이제부터 직접 음성 에이전트를 설계하고 구축할 수 있습니다. 음성 에이전트는 일반 에이전트와 많은 기능을 공유하지만, 고유한 기능도 일부 갖고 있습니다.

음성 에이전트에 다음을 제공하는 방법 알아보기
다양한 전송 계층 더 알아보기