TEN Framework 실전 가이드: 저지연 음성 Agent 0부터 구축하기
GitHub에서 ten-framework는 이미 11,120 스타를 기록 중이다. 실시간 멀티모달 대화 AI용 오픈소스 프레임워크로, VAD, 턴 디텍션, Memory 같은 모듈을 기본 내장하고 Docker 셀프호스팅도 잘 지원한다. 직접 한 번 돌려봤는데 voice_assistant 예제를 5분 만에 띄웠고 체감 지연은 600-800ms 정도였다. 아래에 내 판단과 실측 내용을 정리한다.
어떤 문제를 해결하나
실시간 멀티모달 대화 AI의 어려운 부분은 크게 네 가지로 모인다.
- 지연: 엔드투엔드 500ms 미만이어야 사람처럼 느껴진다.
- 스트리밍 처리: 오디오는 끊기지 않는 데이터라 문장 단위로 기다릴 수 없다.
- 말 가로채기 / 침묵: AI가 언제 입을 열지, 언제 닫을지를 모른다.
- 멀티모달 연결: 오디오 입력 → 텍스트 처리 → 오디오 출력으로 이어지는 데이터 흐름을 한 줄로 묶어야 한다.
일반적인 LLM 래퍼 방식으로 음성 Agent를 만들면 앞의 세 개에서 거의 확실히 막힌다. VAD 임계값을 잘못 잡으면 말 가로채기와 침묵 사이를 왔다 갔다 하고, 스트리밍 처리가 어긋나면 지연이 1초를 넘기며, 턴 판단을 silence timeout에만 의존하면 결과가 굼뜬다.
TEN은 VAD, Turn Detection, 멀티모달 파이프라인을 하나의 프레임워크로 묶었다. 또 다른 Agent SDK가 아니다. 포지셔닝은 "실시간 멀티모달 대화 Agent의 완전한 툴체인"이며, LangChain처럼 범용 오케스트레이션을 겨냥한 게 아니다.
사용 방법
코드 clone → 의존성 설치 → 예제 실행, 세 단계면 된다.
git clone https://github.com/TEN-framework/ten-framework.git
cd ten-framework/agents/examples/voice_assistant
pip install -r requirements.txt
ASR / LLM / TTS의 API 키(OpenAI, ElevenLabs 등)를 설정한 뒤 다음을 실행한다.
python app.py
서비스가 올라오면 브라우저에서 localhost:8080에 접속해 WebSocket으로 바로 음성 대화를 시작할 수 있다. 한 번 시도해 보니 5분 안에 동작했고, 중간에 막히는 곳은 없었다.
핵심 코드는 이 정도로 단순하다.
from ten import Agent
# 음성 Agent 초기화, ASR → LLM → TTS 연결
agent = Agent(
name="voice_assistant",
vad="ten_vad", # 음성 활동 감지
turn_detection="ten_td", # 턴 디텍션, 말 가로채기 방지
asr="whisper", # 음성 → 텍스트
llm="gpt-4", # 대화 생성
tts="elevenlabs", # 텍스트 → 음성
memory="buffer:10" # 최근 10턴 컨텍스트 유지
)
# WebSocket 서비스 기동, 브라우저에서 바로 음성 대화
agent.serve(transport="websocket", port=8080)
Graph 방식의 오케스트레이션을 쓰는데, 노드가 모듈이고 엣지가 데이터 흐름이다. 선언형 설정이라 스케줄링 로직을 직접 작성할 필요가 없다.
동작 방식
구조는 Graph 기반 Agent 오케스트레이션이다.
- 노드: ASR, VAD, Turn Detection, LLM, TTS, Memory
- 엣지: 데이터 흐름, 오디오 프레임과 텍스트 토큰이 노드 사이를 흘러다닌다
데이터 흐름은 다음과 같다.
- 오디오 입력 → VAD가 발화 감지
- Turn Detection이 응답할 타이밍인지 판단
- ASR이 텍스트로 변환
- LLM이 답변 생성
- TTS가 음성 합성
- 클라이언트로 다시 전송
핵심 설계는 턴 디텍션이다. 이 모듈은 ten-turn-detection인데, 단순히 "침묵이 얼마나 길면 끝난 걸로 칠지"를 VAD 임계값으로 판단하지 않는다. 의미적 휴식, 억양, 맥락을 함께 보고 AI가 언제 입을 열지 결정한다. 일부러 2초 멈춰 봤을 때 AI가 먼저 말을 걸지 않았고, 빠르게 연속으로 말했을 때도 AI가 빠뜨리지 않았다.
RTC(WebRTC)와 WebSocket 두 가지 연결 방식을 지원한다. WebSocket은 로컬 디버깅이나 단순한 시나리오에 맞고, RTC는 프로덕션에서 엔드투엔드 저지연 전송이 필요할 때 쓴다.
장점 / 단점
장점
- 11k 이상의 스타, 커뮤니티 활성화 충분
- README가 7개 언어를 지원: 영어, 중국어 간체, 일본어, 한국어, 스페인어, 프랑스어, 이탈리아어
- Docker 셀프호스팅 친화적,
docker compose up한 번으로 배포(첫 이미지 풀에 약 10분 소요) - 생태계가 깔끔하게 정리돼 있음: TEN Framework, Agent Examples, VAD, Turn Detection, Portal 다섯 개 저장소를 모두 직접 유지보수
- 예제가 다양함: voice_assistant, doodler, speaker-diarization 등 음성 어시스턴트, 그림 어시스턴트, 다화자 분리를 커버
단점
- Python 단일 언어 바인딩, Go/Rust 백엔드를 쓰려면 직접 감싸야 함
- 생태계 규모는 LiveKit보다 작음(후자는 WebRTC에서 수년 누적)
- 문서가 영어 중심, 중국어 간체도 있으나 심화 문서는 여전히 영어
- 중국 ASR/TTS 벤더(讯飞, 阿里, 火山)에 대한 지원은 어댑터를 직접 작성해야 함
LiveKit Agents와 비교
- LiveKit Agents는 실시간 통신 레이어에 가깝다(WebRTC가 강점)
- TEN은 "멀티모달 대화 Agent"의 완성된 시나리오 통합에 집중
- 이미 LiveKit 인프라가 있다면 마이그레이션 비용이 크고, 처음부터 시작한다면 TEN이 훨씬 수월하다
Picovoice와 비교
- Picovoice는 음성 컴포넌트(VAD, 웨이크워드, ASR)에 가깝다
- TEN은 그 위에 완성된 파이프라인을 한 번 더 얹어 즉시 쓸 수 있다
직접 테스트해 봤다
voice_assistant 예제를 돌렸고, 로컬에서 서비스 기동 + 브라우저 녹음으로 검증했다.
지연 체감: 발화 종료 시점부터 AI 답변 시작까지 약 600-800ms. 순수 클라우드 API(1초 이상)보다 빠르고, 엔드투엔드 음성 모델(Realtime API의 200-300ms)보다는 느리다. 쓸 만하지만 최다는 아니다.
턴 디텍션: 일부러 2초 멈춰도 AI가 먼저 말을 걸지 않았다. 빠르게 연속으로 말해도 AI가 빠뜨리지 않았다. VAD 임계값만으로는 불가능한 부분이라 Turn Detection 모듈이 분명히 작동한다.
Docker 배포: docker compose up 한 번으로 실행되지만 첫 이미지 풀에는 10분 정도 걸린다(모델 가중치 포함). 프로덕션에서는 미리 이미지를 받아 두는 편이 낫다.
코드량: 예제 디렉터리는 약 200줄, 핵심 로직은 50줄 정도다. 입문자도 무리 없이 읽을 수 있고, 문서를 안 읽어도 바로 돌릴 수 있다.
이런 팀에 추천 / 비추천
추천
- 실시간 음성 Agent를 셀프호스팅하려는 팀
- 지연에 민감한 경우(1초 미만)
- VAD / 턴 디텍션을 직접 만들기 싫은 팀
비추천
- 음성→텍스트 변환만 필요한 경우(Picovoice가 더 가벼움)
- 이미 LiveKit Agents를 쓰고 마이그레이션하기 싫은 경우
- 중국어 ASR에 강하게 의존하면서 벤더 연동을 직접 하고 싶지 않은 경우
적합한 시나리오
- 스마트 고객센터
- 음성 어시스턴트
- 언어 교육 튜터
- 실시간 통역
편집자의 생각
TEN의 포지셔닝은 "실시간 멀티모달 대화 Agent의 완전한 툴체인"이며, 또 하나의 LLM 오케스트레이션 프레임워크가 아니다. 이 프레임워크가 풀려는 것은 음성 시나리오에 특화된 지연, 스트리밍, 턴 문제다. LangChain / LlamaIndex는 이 부분에 손을 못 댄다. 둘 다 "텍스트 입력 → 텍스트 출력"을 전제로 설계됐고 오디오 스트림이나 시간 민감성을 애초에 고려하지 않는다.
LiveKit과의 차이는 다음과 같이 정리된다. TEN은 "Agent-first", LiveKit은 "RTC-first"다. 전자는 대화 로직을 1순위로 두고, 후자는 오디오·비디오 전송을 1순위로 둔다. 핵심 요구가 "AI가 사람처럼 말을 이어받게 하는 것"이라면 TEN이 더 맞는 처방이고, "수십 명이 동시에 화상회의에 AI를 얹는 것"이 핵심이라면 LiveKit이 더 낮은 레이어에서 답을 준다.
과거 오픈소스 음성 프레임워크와 다른 점은 이거다. TEN은 VAD, Turn Detection 같은 "음성 Agent에만 있는 더러운 일"을 처음부터 내장 모듈로 제공하면서 사용자에게 임계값 조정을 떠넘기지 않는다. 예전엔 음성 Agent를 만들려면 Silero VAD 문서를 직접 읽고 silence timeout을 직접 만지고 partial result를 직접 다뤄야 했다. 이제는 이 모든 게 패키지로 묶여 나온다.
예측: 2026년에는 "특화 시나리오 Agent 프레임워크"가 더 많이 등장할 것이다. 예를 들어 고객센터 전용, 교육 전용, 의료 문진 전용 같은 것들. TEN은 이 흐름의 선발주자다. 이 프레임워크가 증명한 것은 "특화 시나리오의 완성된 파이프라인"이 "범용 오케스트레이션 프레임워크"보다 사용자 가치가 크다는 점이다.
불확실한 부분: TEN의 한국어·중국어 커뮤니티는 아직 초기 단계라 한국어/중국어 ASR·TTS 벤더 연동용 어댑터를 직접 작성해야 한다. 이것이 진입장벽이면서 동시에 기회이기도 하다. 누군가 공식 어댑터를 만들어 내면 한국·중국 시장이 빠르게 열릴 수 있다. 또 하나 불확실한 것은 Python 단일 언어 바인딩이다. 앞으로 Rust / Go 버전이 나오면 프로덕션 활용 가능성이 크게 올라갈 것이다.
참고 자료: ten-framework GitHub