몇 분 만에 리액트 앱에 산타 보이스 에이전트 추가하기
- 게시일
이번 연말연시에는 앱에 산타를 추가해 보세요.
ElevenLabs Agents Platform과 @elevenlabs/react SDK를 사용하면 산타클로스 음성 에이전트를 몇 분 만에 React 앱에 추가할 수 있습니다. 이 가이드에서는 다음을 안내합니다.
- ElevenLabs 대시보드에서 산타 에이전트 만들기
- WebRTC를 사용해 React 컴포넌트에 연결하기
- 간단한 “Call Santa” 버튼 추가하기
1. 가입하고 Agents Platform 열기
- 가입하거나 로그인하여 ElevenLabs를 이용하세요.
- 왼쪽 사이드바 상단에서 platform switcher를 여세요.
- Agents Platform을 선택하세요.
사이드바의 “Build” 섹션 아래에 Agents, Knowledge Base, Tools, Voices가 표시됩니다.
2. 산타 에이전트 만들기
다음으로 산타처럼 행동하고 산타 목소리로 말하는 에이전트를 만들어 보겠습니다.
- 사이드바에서 Agents를 클릭하세요.
- + New Agent를 클릭하세요.
- Blank Agent를 선택해 처음부터 시작하세요.
이름은 Santa로 지정하세요.
시스템 프롬프트
System Prompt 필드에 다음 내용을 붙여 넣으세요.
첫 메시지
First Message를 다음과 같이 설정하세요.
호호호! 메리 크리스마스, 친구! 이름이 뭐니?
통화가 시작되면 사용자는 이 메시지를 듣게 됩니다.
목소리
Voice 섹션에서 다음을 설정하세요.
- “Jerry B. – Santa Claus”
- 음성 ID:
MDLAMJ0jxkpYkjXbmG4t
이제 산타가 실제로 산타처럼 들리게 됩니다.
보안
이 예시에서는 공개 상태로 유지하겠습니다.
- Security에서 Enable authentication이 꺼짐 상태인지 확인하세요.
첫 데모에서는 Enable Authentication을 꺼 둬도 괜찮습니다. 그러면 누구나 제한 없이 에이전트에 연결할 수 있습니다. 온보딩이 더 빨라지며, 빠른 프로토타입, 해커톤 프로젝트 또는 내부 쇼케이스에 적합합니다.
하지만 프로덕션 환경이나 외부에서 접근할 수 있는 애플리케이션에서는 에이전트를 절대로 공개 상태로 두면 안 됩니다. 대신 ElevenLabs Token Endpoint를 사용해 사용자 세션별로 짧은 수명의 범위 지정 액세스 토큰을 생성하세요. 이렇게 하면 연결 가능한 사용자, 액세스 기간, 사용자에게 허용되는 작업을 완전히 제어할 수 있습니다. 인증을 활성화하면 무단 통화, 악용 또는 의도한 한도를 벗어난 사용으로부터 에이전트를 보호할 수 있으므로, 출시 전에 반드시 권장합니다.
3. 에이전트 ID 가져오기
에이전트 페이지 상단에 Agent ID 필드가 있습니다.
이 값을 기록해 두세요. 다음 단계에서 React 컴포넌트에 붙여 넣습니다.
4. React SDK 설치하기
React / Next.js 프로젝트에서 ElevenLabs React SDK를 설치하세요.
설치가 완료되면 useConversation 훅으로 음성 통화를 시작하고 종료할 수 있습니다.
5. “Call Santa” 버튼 추가하기
예를 들어 CallSantaButton.tsx라는 새 컴포넌트를 만들고 다음 코드를 붙여 넣으세요.
이제 바꾸세요 "<AGENT_ID>"를 대시보드에서 복사한 실제 에이전트 ID로 바꾸세요.
그런 다음 UI의 원하는 위치에 버튼을 렌더링하세요. 예를 들면 다음과 같습니다.
6. 사용해 보기
브라우저에서 열고 Start Call을 클릭하세요.
- 브라우저가 마이크 권한을 요청합니다.
- 산타 에이전트와 WebRTC 세션이 시작됩니다.
- 다음 메시지가 들립니다:
“호호호! 메리 크리스마스, 친구! 이름이 뭐니?”
이후 산타가 이름, 위시리스트, 그리고 올해 착한 아이 명단에 들기 위해 무엇을 했는지 물어봅니다.
다음 단계
기본 기능이 작동하면 다음을 할 수 있습니다.
- 인증 뒤에 산타 배치하기: 에이전트의 보안 설정을 사용합니다
- 언어 전환하기: 사용자 로케일을 전달하고 프롬프트가 처리하도록 합니다
- UI 꾸미기: 맞춤 버튼, 애니메이션 또는 전체 “Call Santa” 화면을 활용합니다
하지만 핵심 통합 요소는 다음뿐입니다.
- Agents Platform의 에이전트 하나
agentId 하나useConversation훅과 버튼 하나
이것만 있으면 React 앱에 실시간 대화형 산타의 마법을 더할 수 있습니다.




