실시간 AI 음성 에이전트를 만드는 가장 쉬운 방법

몇 년 전만 해도 Alexa, Siri, Google Assistant와 같은 음성 비서는 대기업만 만들 수 있는 것으로 생각됐습니다. 그러나 지금은 누구나 TEN Agent를 사용하여 실시간 AI 음성 에이전트를 만들 수 있습니다. TEN Agent는 Gemini 2.0 Live, OpenAI Realtime, RTC 등을 통합한 대화형 AI 프레임워크로, 실시간으로 보고, 듣고, 말할 수 있는 기능을 제공하며 Dify와 Coze 같은 인기 워크플로우 플랫폼과 완벽하게 호환됩니다. 주요 기능은 다음과 같습니다:
- 실시간 기능: 초저지연 음성 및 비디오 상호작용으로 자연스러운 대화와 중단 지원
- 멀티모달 지원: 음성, 비디오, 이미지 및 텍스트를 원활하게 처리
- 크로스 플랫폼 호환성: Windows, Mac, Linux, 모바일 기기나 ESP32와 같은 하드웨어에서 실행
- 광범위한 통합: OpenAI, Deepgram, ElevenLabs, Google Gemini와 같은 API와 날씨 확인, 웹 검색 같은 도구 지원
이 가이드에서는 TEN Agent를 사용하여 자신만의 실시간 AI 음성 에이전트를 만드는 가장 쉬운 방법을 안내합니다. 환경 설정부터 에이전트 커스터마이징, 배포까지 시작하는 데 필요한 모든 것을 다룹니다.
TEN Agent 플레이그라운드 구축하기
사전 요구 사항
시작하기 전에 다음 사항이 준비되어 있는지 확인하세요:
API 키:
- Agora App ID 및 인증서: 실시간 통신용(매월 무료 시간 제공)
- OpenAI API 키: OpenAI 지원 LLM과 호환
- Deepgram ASR: 음성-텍스트 변환용(가입 시 무료 크레딧 제공)
- ElevenLabs TTS: 텍스트-음성 변환용(가입 시 무료 크레딧 제공)
STT를 위한 다른 지원 모델뿐만 아니라 TTS용 Fish Audio 및 Cartesia도 사용할 수 있습니다.
설치:
- Docker 및 Docker Compose
- Node.js(LTS v18 권장)
최소 시스템 요구 사항:
- CPU: 2코어 이상
- RAM: 4GB 이상
Apple Silicon을 위한 Docker 설정
Apple Silicon Mac을 사용하는 경우, Docker Desktop 설정을 열고 "Use Rosetta for x86/amd64 emulation"의 체크를 해제하세요. ARM에서는 빌드 시간이 느려질 수 있지만, x64 서버에 배포하면 성능이 정상화됩니다.
선택 사항: Trulience AI 아바타를 사용하는 경우, 아바타 ID와 토큰이 필요합니다. 토큰을 찾으려면 상단에 표시된 iFrame 코드에서 Edit → Code → Token을 클릭하세요. 예를 들어, 실험을 위해 Nadia 아바타를 선택했습니다.
음성 에이전트 생성을 위한 단계별 설정
git clone https://github.com/TEN-framework/TEN-Agent.git
프로젝트 디렉토리로 이동합니다:
cd TEN-Agent
cp ./.env.example ./.env
AGORAAPPID=agoraapp_id>
AGORAAPPCERTIFICATE=agoraapp_certificate>
docker compose up -d
Output:
[+] Running 3/3
✔ Container tenagentdemo Running 0.0s
✔ Container tenagentplayground Running 0.0s
✔ Container tenagentdev Started 15.4s
docker exec -it tenagentdev bash
Output:
root@b41516e8c5cd:/app#
task use
이 작업은 모든 종속성과 필요한 패키지를 설치하는데 시간이 걸릴 수 있습니다:
task: [use] ln -sf /app/agents/examples/default/manifest.json ./agents/
task: [use] ln -sf /app/agents/examples/default/property.json ./agents/
task: [build-agent] ./scripts/installdepsand_build.sh linux x64 && mv bin/main bin/worker
install dependencies...
Get all installed packages...
Filter compatible packages...
Attempting to retrieve information about locked packages from manifest-lock.json...
Collect all candidate packages...
....
task run
- 그래프 유형 선택(예: Voice Agent, Realtime Agent 등)
- 해당 모듈 선택(예: STT, TTS, LLM, V2V)
- 확장 프로그램을 선택하고 API 키 설정 입력
- 필요한 경우 에이전트에 추가 도구(날씨 확인, 웹 검색 등) 연결
축하합니다! 이제 플레이그라운드가 실행되고 에이전트를 커스터마이징할 준비가 되었습니다. 플레이그라운드의 드래그 앤 드롭 인터페이스를 사용하거나 agents/property.json에서 직접 에이전트 구성을 편집할 수 있습니다. 그런 다음 플레이그라운드를 새로 고침하여 변경 사항을 실시간으로 확인하세요.

데모 실행하기
TEN Agent는 보다 프로덕션에 가까운 환경을 위한 Demo 컨테이너도 함께 제공합니다. 실행 방법:
task use AGENT=agents/examples/demo
task run
이 환경은 에이전트가 더 제한된 배포 시나리오에서 어떻게 작동하는지 보여주며, 실제 사용 사례를 빠르게 테스트하는 데 완벽합니다.
배포
플레이그라운드에서 에이전트를 커스터마이징한 후 다음 단계는 서비스 패키징입니다:
docker build -t ten-agent-server .
Apple Silicon(ARM)의 경우:
docker build -t ten-agent-server . --platform linux/amd64
Demo 또는 Experimental 에이전트를 사용하는 경우 다음과 같이 지정할 수 있습니다:
docker build --build-arg USE_AGENT=agents/examples/demo -t ten-agent-server .
docker run -itd -p 8083:8080 --env-file .env --name ten-agent-server ten-agent-server
이제 에이전트가 포트 8083에서 실행됩니다.
- 에이전트의 엔드포인트에 접근합니다(API 참조는 TEN-Agent GitHub 저장소에서 확인 가능).
- 플레이그라운드 UI를 이 새 에이전트 컨테이너에 연결하려면 다음과 같이 플레이그라운드를 시작하세요:
cd playground
NEXTPUBLICEDITGRAPHMODE=false AGENTSERVERURL=http://localhost:8083 pnpm dev
로컬에서 실행하지 않는 경우 localhost를 서버 IP로 바꾸세요.
플레이그라운드 UI 배포하기
커스터마이즈된 플레이그라운드도 에이전트와 일치하도록 컨테이너화할 수 있습니다:
cd playground
docker build --build-arg EDITGRAPHMODE=false -t ten-agent-playground .
docker run -itd -p 4000:3000 \
-e AGENTSERVERURL=http://host.docker.internal:8083 \
--name ten-agent-playground \
ten-agent-playground
이제 플레이그라운드는 localhost:4000(또는 서버 IP)에서 접근할 수 있으며, http://host.docker.internal:8083에 있는 에이전트와 통신합니다.
결론
TEN Agent는 모듈성, 실시간 STT/TTS, LLM 통합 및 간단한 Docker 기반 오케스트레이션을 결합하여 음성 AI 솔루션 구축을 단순화합니다. 몇 분 안에 프로토타입을 시작하고, 플레이그라운드에서 모듈의 커스텀 그래프를 개선한 다음, 실시간으로 듣고, 생각하고, 대답하는 음성 비서를 배포할 수 있습니다.