Claude Code로 ElevenAgents 만들기

예전에는 보이스 에이전트를 만들려면 여러 업체와 긴 작업이 필요했지만, 이제 Claude Code만 있으면 오후 한나절 만에 처음부터 끝까지 만들 수 있습니다. 이 가이드에서는 페르소나, 지식 베이스, 워크플로우, 도구, 가드레일, 테스트, 그리고 실제로 전화할 수 있는 번호까지 전 과정을 안내합니다.

오후에 만들 수 있는 것들:

• 밤새 CI 오류를 요약해 아침에 깨워주는 보이스 에이전트
• 오늘 오후에 바로 적용할 수 있는 사이드 프로젝트 다국어 지원 라인
• 본인처럼 말하는 포트폴리오 사이트용 인터랙티브 에이전트

보이스 에이전트가 기계적으로 느껴졌던 이유였던 지연, 억양, 턴테이킹 같은 제약들이 크게 개선되었습니다. 가장 빠른 모델은 약 75ms의 지연으로 실시간으로 멈춤과 끊김을 처리하는 턴테이킹 모델을 사용합니다. Eleven v3는 사람처럼 억양을 바꾸고, 웃고, 한숨 쉬는 등 가장 표현력이 뛰어난 TTS 모델입니다.

빠른 시작

먼저, Claude Code에서 아래 프롬프트로 ElevenLabs 스킬을 설치하세요:

Install the ElevenLabs skill globally - npx skills add elevenlabs/skills

그 다음 setup-api-key 스킬을 실행해 ElevenLabs API 키를 연결하세요:

Set up the elevenlabs key using the setup-api-key skill.

꿀팁: 키 권한을 "agents-write"로만 제한하고, 일일 사용 한도를 설정하세요. 무한 루프가 발생하면 크레딧이 빠르게 소모될 수 있습니다.

에이전트 만들기

ElevenAgents는 자연어 프롬프트만으로 Claude Code에서 몇 분 만에 바로 쓸 수 있는 보이스 에이전트를 만들 수 있도록 설계되었습니다. 이 가이드의 나머지 부분은 그런 프롬프트 예시로, 빈 작업 공간에서 실제로 전화할 수 있는 번호까지 단계별로 안내합니다.

먼저 에이전트 자체부터 시작해봅시다. 이 첫 번째 프롬프트로 페르소나, 목소리, 추론을 담당할 LLM이 포함된 에이전트를 만듭니다. 아직 도구, 지식 베이스, 워크플로우는 없고, 최소한의 기능만 빠르게 구현하는 방법입니다.

Create an ElevenAgent: a warm, knowledgeable product expert. Use a v3 conversational voice and Qwen-3.6 as the LLM. Return the dashboard URL.

지식 베이스 추가

지식 베이스는 에이전트가 질문을 받았을 때 참고할 수 있는 문서, URL, FAQ 모음입니다. ElevenAgents가 검색 파이프라인(RAG, 검색 기반 생성)을 자동으로 처리합니다. 사용자가 질문하면, 플랫폼이 색인된 콘텐츠를 검색해 가장 관련성 높은 부분을 LLM에 컨텍스트로 전달한 뒤 답변을 생성합니다. 소스가 변경되면 자동으로 다시 색인되어, 문서를 다시 업로드하지 않아도 에이전트가 항상 최신 상태를 유지합니다.

Add a knowledge base to my agent. Index 
https://elevenlabs.io/docs/eleven-agents/overview
 and ./README.md if it exists. 

Auto-reindex on.

워크플로우 추가

하나의 프롬프트만 가진 단일 에이전트는 단순한 작업에 적합합니다. 워크플로우를 추가하면 다양한 의도를 가진 대화도 처리할 수 있습니다. 모든 행동을 하나의 시스템 프롬프트에 몰아넣는 대신, 각 의도를 담당하는 노드로 에이전트를 나누고, 발신자의 요구에 따라 노드 간을 이동합니다. 각 노드는 고유한 행동을 담당하고, 노드 간 이동은 LLM이 조건을 평가해 결정합니다.

Add a workflow to my agent: greeting, classify intent, then branch to either answer from KB or escalate to human, then wrap up.

도구 추가

ElevenAgents는 세 가지 종류의 도구를 지원하며, 각각 역할이 다릅니다. 클라이언트 도구는 프론트엔드에서 UI 동작을 실행해 에이전트가 화면을 탐색하거나, 강조 표시하거나, 사용자에게 보이는 내용을 업데이트할 수 있습니다. 웹훅 도구는 서버 API를 호출해 에이전트가 자체 시스템의 데이터를 읽거나 쓸 수 있게 합니다. 내장 도구는 통화 종료, 발신자 언어 감지, 상담원 연결 등 직접 구현하지 않아도 되는 일반적인 플랫폼 기능을 제공합니다.

Add three tools to my agent: 
1. A client tool called show_help_article that takes an article_id. 
2. A webhook tool called get_weather hitting 
https://wttr.in/
{location}?format=j1. 
3. Enable the built-in end_call and language_detection tools.

가드레일 추가

가드레일은 LLM과 별도로 동작해 시스템 프롬프트에서 놓친 예외 상황을 잡아줍니다. 일반적으로는 시스템 프롬프트에만 의존하지 않고 platform_settings에서 설정하는 것이 좋지만, 중요한 규칙은 두 곳 모두에 적용하는 것이 안전합니다. 시스템 프롬프트와 별도의 커스텀 가드레일로 함께 설정하면, LLM이 지침에서 벗어나더라도 응답 검증기가 사용자에게 전달되기 전에 문제를 차단할 수 있습니다.

Add guardrails to my agent. Enable focus and prompt injection protection. Add custom rules to block specific pricing claims, speculation about unreleased features, and any write access to billing systems.

테스트 추가

실제 사용자에게 에이전트를 공개하기 전에, 제대로 동작하는지 꼭 확인해야 합니다. ElevenAgents는 세 가지 테스트 방식을 지원하며, 보통 모두 사용하는 것이 좋습니다. 응답 테스트는 에이전트가 올바른 내용과 톤으로 말하는지 확인합니다. 도구 호출 테스트는 올바른 도구와 파라미터로 호출하는지 확인합니다. 시뮬레이션 테스트는 여러 차례 대화가 예상과 다르게 흘러가도 전체 흐름이 유지되는지 확인합니다.

Add three tests to my agent: one that checks the greeting tone, one that checks it calls show_help_article when asked about password resets, and a simulation that checks if it defers to sales when asked about pricing.

전화 연결하기

지금까지는 에이전트가 대시보드에서만 동작했습니다. 전화번호와 연결하면 음성 트래픽이 텔레포니(통신) 제공업체를 통해 오가면서, 수신 및 발신 통화가 모두 가능합니다. 발신자는 전화를 걸 수 있고, 에이전트도 전화를 걸 수 있으며, 오디오가 텔레포니 제공업체를 통해 전달됩니다. ElevenAgents는 Twilio, SIP trunk, Vonage, Telnyx, Plivo, Genesys와 네이티브로 연동되어 별도의 미디어 서버나 수동 TwiML 라우팅 없이 바로 사용할 수 있습니다. 음성 모델부터 LLM, 텔레포니 제공업체까지 모든 스택이 한 플랫폼에 연결됩니다.

Twilio 네이티브 연동이 가장 빠른 설정 방법입니다. Twilio 번호를 ElevenAgents 대시보드에 Account SID와 Auth Token으로 가져오면, 플랫폼이 음성 웹훅과 오디오 포맷을 자동으로 설정해줍니다. 참고로, Twilio에서 구매한 번호는 수신 및 발신 통화 모두 지원합니다. Twilio에서 발신자 ID로 인증한 번호는 발신만 지원합니다.

Connect my Twilio account to ElevenAgents. Reserve a +1 number from Twilio's available pool, assign it my ElevenAgent via the native Twilio integration, and return the number to dial.

꿀팁: Twilio 계정이 없어도 대시보드의 'Talk to Agent' 버튼으로 브라우저에서 바로 테스트할 수 있습니다. 전화번호는 실제 운영용입니다.

이제 더 이상 기계처럼 들리지 않는 보이스 에이전트를 갖게 되었습니다.