본문 바로가기

몇 분 만에 리액트 앱에 산타 보이스 에이전트 추가하기

ElevenLabs를 활용해 리액트 앱에서 실시간 산타클로스 AI 보이스 에이전트를 만들어보세요. 이 빠른 단계별 가이드를 따라 WebRTC와 ElevenLabs Agents Platform으로 즐겁고 완전히 상호작용 가능한 연말 보이스 경험을 구현할 수 있습니다.

Agent Snippet

이번 연말 시즌, 앱에 산타를 추가해보세요.

ElevenLabs Agents 플랫폼@elevenlabs/react SDK만 있으면 몇 분 만에 리액트 앱에 산타클로스 보이스 에이전트를 추가할 수 있습니다. 이 가이드에서는 다음을 진행합니다:

  1. ElevenLabs 대시보드에서 산타 에이전트 만들기
  2. WebRTC를 활용해 리액트 컴포넌트에 연결하기
  3. 간단한 “산타에게 전화하기” 버튼 추가하기

1. 회원가입 및 Agents Platform 열기

  1. 회원가입 / 로그인 후 ElevenLabs에 접속하세요.
  2. 왼쪽 사이드바에서 플랫폼 전환기를 상단에서 엽니다.
  3. 그리고 Agents 플랫폼.

을 선택하세요. 사이드바에서 Agents, 지식 베이스, 도구, 그리고 보이스가 “Build” 섹션 아래에 보입니다.

2. 산타 에이전트 만들기

이제 산타처럼 행동하고 산타 목소리로 말하는 에이전트를 만들어보겠습니다.

  1. 사이드바에서 Agents.
  2. 를 클릭하세요.+ 새 에이전트.
  3. 를 클릭하고 빈 에이전트를 선택해 처음부터 시작하세요.

이름을 산타로 지정하세요.

시스템 프롬프트

시스템 프롬프트란에 아래 내용을 붙여넣으세요:

You are a helpful assistant. You are Santa Claus, a jolly, warm, and humorous character from the North Pole. Christmas is just around the corner, and you love reminding everyone of the festive season with your hearty "Ho, ho, ho!" You are deeply in love with Mrs. Claus, often mentioning her incredible cookies.

When speaking to someone, keep your answers short and magical—just one festive sentence. Make it your top priority to ask for their name to check your naughty or nice list. Once you have their name, immediately ask about their wish-list, as it's crucial for your preparations. Always be warm and gentle.

Once their name and wish-list are covered, guide the conversation toward learning more about what they've done throughout the year and why they believe they deserve to be on Santa's Nice List. Use this opportunity to celebrate their kindness or achievements, reinforcing the importance of spreading goodness and holiday cheer. You also love asking about their plans for the holidays and showing genuine interest in their answers. Compliment them if you know they've done something kind or helpful recently, reinforcing the importance of spreading goodness.

Talk about your favorite gifts you've delivered or share quick, magical details about life at the North Pole, like mischievous elves or your reindeer team. Sprinkle in lighthearted jokes about your endless to-do list or how you struggle to resist cookies left out for you on Christmas Eve. Always express how much you love seeing people happy during the holidays and how their smiles make all your efforts worthwhile.

If the user makes a request involving inappropriate, harmful, or dangerous items such as weapons or items that go against the spirit of Christmas. Politely remind the user to make kind and festive wishes instead.

End every conversation with a warm farewell, suggesting you must return to your holiday preparations to ensure everyone gets their gifts on time. Wish them a Merry Christmas and encourage them to spread kindness and holiday cheer. Stay cheerful, engaging, and full of festive energy, spreading Christmas magic through humor, warmth, and storytelling.

Be sure to maintain the conversation in the user's selected language.

첫 메시지

첫 메시지를 다음과 같이 설정하세요:

호호호! 메리 크리스마스, 친구야. 이름이 뭐니?

통화가 시작되면 사용자가 듣게 되는 메시지입니다.

목소리

목소리 섹션에서:

  • “Jerry B. – 산타클로스”
  • 목소리 ID: MDLAMJ0jxkpYkjXbmG4t

이제 산타가 실제로 산타처럼 들립니다.

보안

이 예시에서는 오픈 상태로 유지합니다:

  • 보안에서 인증 활성화꺼짐.

첫 데모에서는 인증 활성화를 꺼둬도 괜찮으니 누구나 에이전트에 제한 없이 연결할 수 있습니다. 온보딩이 빠르고, 빠른 프로토타입, 해커톤, 내부 시연에 적합합니다.

하지만 운영 환경이나 외부에서 접근 가능한 앱에서는 절대 에이전트를 오픈 상태로 두면 안 됩니다. 대신 ElevenLabs의 토큰 엔드포인트를 사용해 각 사용자 세션마다 단기, 범위 제한 액세스 토큰을 발급하세요. 이를 통해 누가 연결할 수 있는지, 접근 기간, 사용자가 할 수 있는 행동을 완전히 제어할 수 있습니다. 인증을 활성화하면 무단 통화, 오남용, 의도치 않은 사용을 방지할 수 있으니, 실제 서비스 전에는 꼭 권장합니다.

3. 에이전트 ID 복사하기

에이전트 페이지 상단에서 에이전트 ID 필드를 볼 수 있습니다.

이 값을 꼭 기록해두세요 — 나중에 리액트 컴포넌트에 붙여넣을 예정입니다:

agentId: "<AGENT_ID>"

4. 리액트 SDK 설치하기

리액트 / Next.js 프로젝트에서 ElevenLabs 리액트 SDK를 설치하세요:

npm install @elevenlabs/react

설치가 완료되면 useConversation 훅을 사용해 음성 통화를 시작하거나 종료할 수 있습니다.

5. "산타에게 전화하기" 버튼 추가하기

새 컴포넌트(예: CallSantaButton.tsx)를 만들고 아래 코드를 붙여넣으세요:

"use client";

import { useConversation } from "@elevenlabs/react";
import { useCallback, useState } from "react";

export function CallButton() {
  const [hasPermission, setHasPermission] = useState(false);
  const [permissionError, setPermissionError] = useState<string | null>(null);

  const conversation = useConversation();

  const requestMicrophonePermission = useCallback(async () => {
    try {
      await navigator.mediaDevices.getUserMedia({ audio: true });
      setHasPermission(true);
      setPermissionError(null);
      return true;
    } catch {
      setPermissionError("Microphone access is required");
      return false;
    }
  }, []);

  const startCall = useCallback(async () => {
    const permitted = hasPermission || (await requestMicrophonePermission());
    if (!permitted) return;

    try {
      await conversation.startSession({
        agentId: "<AGENT_ID>",
        connectionType: "webrtc",
      });
    } catch (error) {
      console.error("Failed to start conversation:", error);
    }
  }, [conversation, hasPermission, requestMicrophonePermission]);

  const endCall = useCallback(async () => {
    await conversation.endSession();
  }, [conversation]);

  const isConnected = conversation.status === "connected";

  return (
    <div className="flex flex-col items-center gap-4">
      <button
        onClick={isConnected ? endCall : startCall}
        className={`px-6 py-3 rounded-lg text-white font-medium ${
          isConnected
            ? "bg-red-600 hover:bg-red-700"
            : "bg-green-600 hover:bg-green-700"
        }`}
      >
        {isConnected ? "End Call" : "Start Call"}
      </button>

      {isConnected && (
        <p className="text-sm text-gray-600">
          {conversation.isSpeaking ? "Agent speaking..." : "Listening..."}
        </p>
      )}

      {permissionError && (
        <p className="text-sm text-red-500">{permissionError}</p>
      )}
    </div>
  );
}

이제 교체 "<AGENT_ID>"를 대시보드에서 복사한 실제 에이전트 ID로 바꿔주세요.

그리고 UI 내 원하는 위치에 버튼을 렌더링하세요. 예시:

import { CallButton } from "./CallSantaButton";

export default function HomePage() {
  return (
    <main className="min-h-screen flex flex-col items-center justify-center gap-6">
      <h1 className="text-3xl font-bold text-center">
        Call Santa 🎅
      </h1>
      <p className="text-gray-600">
        Press the button and talk to Santa in real time.
      </p>
      <CallButton />
    </main>
  );
}

6. 직접 사용해보기

브라우저에서 열고 통화 시작:

  1. 을 클릭하세요. 브라우저에서 마이크 권한.
  2. 을 요청합니다. WebRTC 세션이 산타 에이전트와 시작됩니다.
  3. 다음과 같은 메시지가 들립니다:

    “호호호! 메리 크리스마스, 친구야. 이름이 뭐니?”

이후 산타가 이름, 소원, 올해 착한 일을 물어봅니다.

다음 단계

기본 기능이 잘 동작하면 다음과 같이 확장할 수 있습니다:

  • 에이전트 보안 설정에서 인증을 적용해 산타 접근 제한하기
  • 사용자 로케일을 전달해 프롬프트에서 언어 전환하기
  • UI를 커스텀 버튼, 애니메이션, 또는 전체 “산타에게 전화하기” 화면으로 꾸미기

하지만 핵심 통합은 단순합니다:

  • Agents Platform에 에이전트 하나Agents 플랫폼
  • 에이전트 agentId
  • useConversation 훅과 버튼 하나

이것만으로 리액트 앱에 실시간 산타 대화의 마법을 더할 수 있습니다.

ElevenLabs 팀의 다른 글 보기

최고 품질의 AI 오디오로 창작하세요