Next.js에서 Agents Platform을 활용한 데이터 수집 및 분석
Next.js에서 Agents Platform을 활용한 데이터 수집 및 분석
Agents Platform 및 Next.js를 사용해 통화 후 웹훅에서 데이터를 수집하고 분석합니다.
튜토리얼 · ElevenAgents 빠른 시작을 완료했고 Next.js 프로젝트를 설정했다고 가정합니다.
소개
이 튜토리얼에서는 대화를 통해 사용자로부터 정보를 수집하고, 데이터를 구조화된 방식으로 분석 및 추출한 다음 통화 후 웹훅을 통해 애플리케이션으로 전송하는 음성 에이전트를 구축하는 방법을 알아봅니다.
요구 사항
- API 키가 있는 ElevenLabs 계정
- 컴퓨터에 설치된 Node.js v18 이상
설정
새 Next.js 프로젝트 만들기
애플리케이션의 시작점으로 v0.dev Agents Platform 템플릿을 사용하는 것이 좋습니다. 이 템플릿은 ElevenLabs 에이전트가 이미 통합된 프로덕션 준비 완료 Next.js 애플리케이션입니다.
Agents Platform 설정
설치 및 구성 단계는 Next.js 가이드를 따르세요. 그런 다음 여기로 돌아와 고급 기능을 구축합니다.
에이전트 구성
클라이언트 도구 설정
단계 간 이동에 사용할 다음 클라이언트 도구를 설정합니다.
- 이름:
set_ui_state- 설명: 이 클라이언트 측 도구를 사용하여 여러 UI 상태 간에 이동합니다.
- 응답 대기:
true - 응답 시간 제한(초): 1
- 매개변수:
- 데이터 유형: string
- 식별자: step
- 필수: true
- 값 유형: LLM Prompt
- 설명: UI에서 이동할 단계입니다. 시스템 프롬프트에 정의된 단계만 사용하세요!
평가 기준 설정
Analysis 탭으로 이동하여 새 평가 기준을 추가합니다.
- 이름:
all_data_provided- 프롬프트: 사용자가 생성하려는 에이전트에 대한 설명과 해당 에이전트가 가져야 할 음성에 대한 설명을 제공했는지 평가합니다.
데이터 수집 구성
통화 후 분석을 사용하여 대화에서 데이터를 추출할 수 있습니다. Analysis 탭의 Data Collection에서 다음 항목을 추가합니다.
- 식별자:
voice_descriptiondata-type:String- 설명: 사용자가 에이전트에 적용하고자 하는 음성 설명을 바탕으로, 가능한 경우 나이, 억양, 톤 및 성격을 포함한 간결한 음성 설명을 생성합니다.
- 식별자:
agent_descriptiondata-type:String- 설명: 사용자가 설계하려는 에이전트에 대한 설명을 바탕으로, 모델이 해당 에이전트로 작동하도록 학습하는 데 사용할 수 있는 프롬프트를 생성합니다.
통화 후 웹훅 구성
통화 후 웹훅은 통화가 종료되고 분석 및 데이터 추출 단계가 완료되었을 때 알림을 보내는 데 사용됩니다.
이 예시에서 통화 후 웹훅은 다음 단계를 수행합니다.
voice_description을 기반으로 맞춤 음성 디자인을 생성합니다.- 사용자가 제공한
agent_description을 기반으로 사용자를 위한 ElevenLabs 에이전트를 생성합니다. - Redis에 저장된 대화 상태에서 지식 베이스 문서를 가져와 에이전트에 연결합니다.
- 맞춤 ElevenLabs 에이전트가 대화할 준비가 되었음을 알리는 이메일을 사용자에게 보냅니다.
로컬에서 실행하는 경우 로컬 서버를 인터넷에 노출하려면 ngrok과 같은 도구가 필요합니다.
Agents Platform 설정으로 이동한 후 Post-Call Webhook에서 새 웹훅을 만들고 ngrok URL https://<your-url>.ngrok-free.app/api/convai-webhook을 붙여넣습니다.
웹훅을 저장하면 웹훅 시크릿을 받게 됩니다. 나중에 .env 파일에 설정해야 하므로 이 시크릿을 안전하게 보관하세요.
고급 기능 통합
대화 상태 저장을 위한 Redis 데이터베이스 설정
이 예시에서는 Redis를 사용하여 대화 상태를 저장합니다. 이를 통해 통화가 끝난 후 대화 상태에서 지식 베이스 문서를 가져올 수 있습니다.
Vercel에 배포하는 경우 Upstash for Redis 통합을 구성하거나, 무료 Upstash 계정에 가입하여 새 데이터베이스를 만들 수 있습니다.
통화 후 이메일 전송을 위한 Resend 설정
이 예시에서는 Resend를 사용하여 사용자에게 통화 후 이메일을 전송합니다. 이를 위해 무료 Resend 계정을 만들고 새 API 키를 설정해야 합니다.
환경 변수 설정
프로젝트 루트에 .env 파일을 만들고 다음 변수를 추가합니다.
보안 및 인증 구성
ElevenLabs 에이전트를 보호하려면 에이전트 구성의 Security 탭에서 인증을 활성화해야 합니다.
인증을 활성화한 후에는 에이전트와의 대화를 시작하기 위해 보안이 유지되는 서버 측 환경에서 서명된 URL을 생성해야 합니다. Next.js에서는 새 API 라우트를 설정하여 이를 수행할 수 있습니다.
대화 세션 시작
대화를 시작하려면 먼저 API 라우트를 호출하여 서명된 URL을 가져온 다음, useConversation 훅을 사용해 대화 세션을 설정합니다.
클라이언트 도구 및 동적 변수
앞서 에이전트 구성에서 에이전트가 여러 UI 상태 간에 이동할 수 있도록 set_ui_state 클라이언트 도구를 등록했습니다. 이를 모두 연결하려면 conversation.startSession 옵션에 클라이언트 도구 구현을 전달해야 합니다.
여기에서 대화에 동적 변수를 전달할 수도 있습니다.
지식 베이스에 문서 업로드
Training 단계에서 에이전트는 사용자에게 문서를 업로드하거나 에이전트가 사용할 수 있어야 하는 정보가 있는 공개 웹사이트 URL을 제출하도록 요청합니다. 여기서는 Next.js 15의 새로운 after 함수를 활용하여 백그라운드에서 문서를 업로드할 수 있습니다.
양식 제출 시 지식 베이스 생성을 처리할 새 upload 서버 액션을 만듭니다. 모든 지식 베이스 문서가 생성되면 대화 ID와 지식 베이스 ID를 Redis 데이터베이스에 저장합니다.
통화 후 웹훅 처리
통화 후 웹훅은 통화가 종료되고 분석 및 데이터 추출 단계가 완료되면 트리거됩니다.
여기에서는 다음 단계를 수행합니다.
- 웹훅 시크릿을 검증하고 웹훅 페이로드를 구성합니다.
voice_description을 기반으로 맞춤 음성 디자인을 생성합니다.- 사용자가 제공한
agent_description을 기반으로 사용자를 위한 ElevenLabs 에이전트를 생성합니다. - Redis에 저장된 대화 상태에서 지식 베이스 문서를 가져와 에이전트에 연결합니다.
- 맞춤 ElevenLabs 에이전트가 대화할 준비가 되었음을 알리는 이메일을 사용자에게 보냅니다.
각 단계를 자세히 살펴보겠습니다.
웹훅 시크릿 검증 및 웹훅 페이로드 구성
웹훅 요청을 받으면 먼저 웹훅 시크릿을 검증하고 웹훅 페이로드를 구성합니다.
voice_description을 기반으로 맞춤 음성 디자인 생성
웹훅 페이로드의 voice_description을 사용하여 맞춤 음성 디자인을 생성합니다.
Redis에 저장된 대화 상태에서 지식 베이스 문서 가져오기
문서 업로드는 웹훅 데이터 분석보다 오래 걸릴 수 있으므로, 문서가 업로드될 때까지 Redis에서 대화 상태를 폴링해야 합니다.
사용자가 제공한 agent_description을 기반으로 사용자를 위한 ElevenLabs 에이전트 생성
사용자가 제공한 agent_description을 기반으로 ElevenLabs 에이전트를 생성하고, 새로 생성된 음성 디자인과 지식 베이스를 에이전트에 연결합니다.
맞춤 ElevenLabs 에이전트가 대화할 준비가 되었음을 알리는 이메일을 사용자에게 전송
에이전트가 생성되면 맞춤 ElevenLabs 에이전트가 대화할 준비가 되었음을 알리는 이메일을 사용자에게 보낼 수 있습니다.
Resend 팀의 유용한 도구인 new.email을 사용하면 이메일 템플릿을 바이브 디자인할 수 있습니다. 템플릿이 마음에 들면 새 컴포넌트를 만들고 에이전트 ID를 prop으로 추가합니다.
앱 실행
앱을 로컬에서 처음부터 끝까지 실행하려면 먼저 Next.js 개발 서버를 실행한 다음, 별도의 터미널에서 ngrok 터널을 실행하여 웹훅 핸들러를 인터넷에 노출해야 합니다.
- 터미널 1:
pnpm dev를 실행하여 Next.js 개발 서버를 시작합니다.
- 터미널 2:
ngrok http 3000을 실행하여 웹훅 핸들러를 인터넷에 노출합니다.
이제 http://localhost:3000을 열고 나만의 음성으로 맞춤 ElevenLabs 에이전트를 디자인해 보세요!