几年前，我们所知的语音助手还只有Alexa、Siri和GoogleAssistant。那时，只有那些拥有丰富经验的大公司，似乎才有能力开发出如此智能的工具。但现在，借助TEN Agent，任何人都可以创建属于自己的实时AI语音代理。TEN Agent是一个由TEN驱动的对话式AI框架，集成了Gemini 2.0 Live、OpenAIRealtime、RTC等多种技术。它不仅具备实时“看、听、说”的能力，还完全兼容Dify、Coze等主流工作流平台。其主要特性包括：

• 实时能力：超低延迟的语音和视频交互，支持打断与自然对话。
• 多模态支持：可无缝处理语音、视频、图片和文本。
• 跨平台兼容：可运行于Windows、Mac、Linux，甚至移动设备或如ESP32等硬件。
• 丰富集成：兼容OpenAI、Deepgram、ElevenLabs、Google Gemini等API，以及天气查询、网页搜索等工具。
• 简易上手：提供拖拽式操作界面及docker容器，便于快速部署。

本指南将带您逐步搭建专属的实时AI语音助手，从环境配置、功能定制到正式上线，涵盖入门所需的全部内容。

一、入门：搭建TEN Agent Playground

前置条件

在开始之前，请确保您已拥有以下资源：

API密钥

• Agora App ID与证书：用于实时通讯（每月有免费额度）。
• OpenAI API密钥：兼容任意OpenAI支持的大模型。
• Deepgram ASR：用于语音转文本（注册即有免费额度）。
• ElevenLabs TTS：用于文本转语音（注册即有免费额度）。
• 还可选用Fish Audio、Cartesia等TTS服务，以及其他支持的STT模型。

环境安装

• Docker与Docker Compose
• Node.js（推荐LTS v18）
• 最低系统要求：CPU2核及以上，内存4GB及以上

Apple Silicon Docker设置

如您使用Apple Silicon Mac，请在Docker Desktop设置中取消勾选“Use Rosettafor x86/amd64 emulation”。这会使ARM架构下的构建速度变慢，但部署到x64服务器后性能会恢复正常。

可选项：如需使用Trulience AI虚拟形象，需要获取avatarID和token。点击Edit → Code → Token即可在iFrame代码顶部获取。例如，笔者实验时选择了Nadia虚拟形象。

二、逐步搭建语音助手

1. 克隆代码仓库：

   在终端输入以下命令克隆TEN Agent仓库：

git clone https:// github.com/TEN-framework/TEN-Agent.git

1. 进入项目目录：

cd TEN-Agent

1. 准备配置文件：

   复制示例配置为.env文件：

cp ./.env.example ./.env

1. 配置Agora信息：

   编辑.env文件，填写以下内容：

AGORA_APP_ID=AGORA_APP_CERTIFICATE=

1. 启动Docker容器：

   在项目根目录下，后台启动Docker容器：

docker compose up -d

输出示例：

[+] Running 3/3 ✔ Containerten_Agent_demo Running 0.0s ✔ Container ten_agent_playground Running 0.0s ✔ Container ten_agent_dev Started 15.4s

1. 进入开发容器：

   进入开发容器的Shell：

docker exec -it ten_agent_dev bash

输出示例：

root@b41516e8c5cd:/app#

1. 构建Agent：

   在容器内输入以下命令进行依赖安装和构建：

task use

此过程会安装所有依赖包，需耐心等待。

1. 启动Web服务：

   输入命令启动Web服务器：

task run

1. 配置Playground：

   打开浏览器访问localhost:3000。在Playground中：

• 选择图形类型（如Voice Agent、Realtime Agent等）。
• 选择对应模块（如STT、TTS、LLM、V2V）。
• 选择扩展并填写API密钥。
• 如有需要，附加天气查询、网页搜索等工具。
• 可在属性中配置模块参数，如语言、语音类型等。例如，语音转文本模块可设置语言代码（如en-US、es-ES等）。

恭喜！Playground已成功运行，您可以通过拖拽界面或编辑agents/property.json文件实时定制Agent。修改后刷新Playground即可实时生效。

三、运行Demo

TEN Agent还附带Demo容器，适合模拟实际生产环境。启动方式如下：

1. 切换到Demo代理目录：

task use AGENT=agents/examples/demo

1. 启动Agent：

task run

1. 打开浏览器访问 http://localhost:3002。

该环境适合测试更接近真实部署场景的Agent功能。

四、部署上线

自定义Agent后，可将服务打包部署：

1. 构建正式版Docker镜像：

docker build -t ten-agent-server .

Apple Silicon (ARM)用户请用：

docker build -t ten-agent-server . --platformlinux/amd64

如需指定Demo或Experimental Agent：

docker build --build-arg USE_AGENT=agents/examples/demo -t ten-agent-server .

1. 运行Docker容器：

docker run -itd -p 8083:8080 --env-file .env --name ten-agent-server ten-agent-server

Agent将运行在8083端口。

1. 测试服务：

   参考TEN-Agent GitHub仓库API文档，访问Agent接口。

如需将Playground UI连接至新Agent容器，使用以下命令启动Playground：

cd playgroundNEXT_PUBLIC_EDIT_GRAPH_MODE=false AGENT_SERVER_URL=http://localhost:8083 pnpm dev

如非本地运行，请将localhost替换为服务器IP。

五、部署Playground UI

您也可将定制后的Playground容器化，和Agent一同部署：

cd playgrounddocker build --build-arg EDIT_GRAPH_MODE=false -t ten-agent-playground .docker run -itd -p 4000:3000 \ -e AGENT_SERVER_URL=http://host.docker.internal:8083 \ --name ten-agent-playground \ ten-agent-playground

此时可通过localhost:4000访问Playground，后端与http://host.docker.internal:8083的Agent通信。

六、结语

TEN Agent结合了模块化设计、实时语音识别/合成、大模型集成和简洁的Docker编排，大大简化了语音AI解决方案的开发流程。您可以在几分钟内完成原型搭建，利用Playground灵活定制模块流程，然后一键部署，实现实时“聆听-思考-回应”的语音助手。如果本指南对您有帮助，欢迎star TEN-Agent的GitHub仓库，及时获取最新功能和优化信息。