빠른 시작

프로젝트 생성

이 빠른 시작에서는 브라우저에서 사용할 수 있는 음성 에이전트를 만듭니다. 새 프로젝트를 살펴보고 싶다면 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를 통해 모델에 안전하게 연결할 방법이 필요합니다. 이를 위해 백엔드 서버에서 생성해야 하는 임시 클라이언트 키를 사용할 수 있습니다. 테스트 용도로는 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을 연결로 사용합니다. 다양한 전송 계층에 대해서는 Realtime Transport Layer 가이드에서 자세히 알아보세요.

모두 통합하기

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
```

다음 단계

여기서부터는 자신만의 음성 에이전트를 설계하고 구축할 수 있습니다. 음성 에이전트는 일반 에이전트와 동일한 기능을 많이 포함하지만, 고유한 기능도 일부 보유하고 있습니다.

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