TEN framework：开源实时语音多模态 Agent

想做能打断、能边听边回的实时语音 Agent，最麻烦的往往不是模型本身，而是音频链路、会话状态和扩展怎么拼在一起。TEN（The TEN Framework）是一套开源的实时多模态对话框架，把 VAD、轮次检测、RTC/WebSocket、以及可插拔的 STT/LLM/TTS 扩展收成一条可本地跑、可 Docker 部署的流水线。仓库在 TEN-framework/ten-framework，官网文档见 theten.ai/docs。

TEN 是什么

TEN 的定位不是又一个聊天 SDK，而是面向「实时对话 Agent」的运行时和扩展生态。生态里大致有几块：

• TEN Framework：核心运行时与扩展机制
• TEN VAD：低延迟流式语音活动检测
• TEN Turn Detection：支持全双工对话的轮次检测
• Agent Examples：可直接跑的示例（语音助手、口型同步、SIP、转写、ESP32 等）
• Portal：文档与博客站点

官方示例覆盖常见场景：低延迟语音助手（RTC 或 WebSocket）、说话人分离、Live2D/第三方数字人唇形同步、SIP 电话、纯转写，以及在 ESP32-S3 Korvo V3 上跑的硬件端。

本地先跑通一个语音助手

准备

Apple Silicon 上建议关掉 Docker 的「Use Rosetta for x86/amd64 emulation」，本地构建可能慢一点，但部署到 x64 服务器时性能更正常。

克隆并配环境

git clone https://github.com/TEN-framework/ten-framework.git
cd ten-framework/ai_agents
cp ./.env.example ./.env

在 .env 里至少填这些：

AGORA_APP_ID=
AGORA_APP_CERTIFICATE=
DEEPGRAM_API_KEY=
OPENAI_API_KEY=
ELEVENLABS_TTS_KEY=

起开发容器并构建示例

docker compose up -d
docker exec -it ten_agent_dev bash

进容器后选一个示例目录（链式语音助手，或实时 speech-to-speech）：

cd agents/examples/voice-assistant
# 或
cd agents/examples/voice-assistant-realtime

task install
task run

如果改过本地源码（尤其是 TypeScript / Go），需要先 task build 再 task run。首次构建大概要 5–8 分钟。

跑起来后两个入口：

• TMAN Designer：http://localhost:49483，可视化改 STT / LLM / TTS 扩展属性
• 示例 UI：http://localhost:3000

在 Designer 里右键对应扩展，填好 API Key，提交后刷新 UI 就能用新配置。

不想折腾本机 Docker 时，也可以用 GitHub Codespaces 跑 Agent Examples，一般比本地 Docker 起得快。

换扩展、加能力

示例不是死 demo，而是按扩展拼出来的图。常见加装方向：

• Memory：给对话挂长期记忆（仓库里有 voice-assistant-with-memU）
• TEN VAD / Turn Detection：更稳的端点检测和全双工打断
• WebSocket 示例：不走 RTC、用 WebSocket 拉流
• SIP：对接电话链路（如 Twilio 示例）
• 唇形 / 数字人：Live2D、Trulience、HeyGen、Tavus 等

改完 property.json（或在 Designer 里改）再 task run 即可验证。

发布成服务

本地调通后，在宿主机（不要在容器里）按示例打镜像：

cd ai_agents
docker build -f agents/examples/<example-name>/Dockerfile -t example-app .
docker run --rm -it --env-file .env -p 3000:3000 example-app

也可以前后端拆开：后端容器暴露 8080，前端放到 Vercel / Netlify，把 AGENT_SERVER_URL 指到后端，并处理好 CORS 或走内置代理。后端适合跑长生命周期 worker，前端只负责 UI 和转发。

什么时候适合用 TEN

• 你要的是低延迟、可打断的语音对话，而不只是「录音 → 一次 ASR → 回一段 TTS」
• 希望 STT / LLM / TTS / VAD 能换厂商，但会话图和扩展接口保持稳定
• 需要从 Web Demo 一路走到 Docker、SIP 甚至嵌入式（ESP32）

如果只是离线转写或一次性语音命令，轻量 ASR + TTS 脚本就够了；TEN 的价值在实时会话编排和扩展生态。

相关链接

• 框架仓库：https://github.com/TEN-framework/ten-framework
• 文档：https://theten.ai/docs
• TEN VAD：https://github.com/ten-framework/ten-vad
• TEN Turn Detection：https://github.com/ten-framework/ten-turn-detection