企业官网建设流程全解析

TEN Agent RTM 传输示例前端 Playground：本地开发、联调与容器化部署指南

【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址: https://gitcode.com/TEN-framework/ten-framework

本指南以 frontend/README.md 为骨架，系统讲解 TEN Agent 的 RTM 传输示例（rtm-transport）所附带的前端 Playground：它是什么、采用怎样的技术栈、如何在本地完成依赖安装与启动，以及如何与 Ten Agent 后端联调、如何构建成 Docker 镜像发布。读完本文，你将能够独立把该前端跑起来，并通过源码理解它与 RTC/RTM 双传输 Agent 之间的调用关系。

Playground 是什么

rtm-transport是 TEN Agent 仓库中一个演示双传输架构的语音助手示例：同时使用 Agora RTC（实时音频）与 Agora RTM（实时消息，用于文本/数据）来构建更丰富的实时通信能力。而本文主角——位于 frontend/ 的 Playground，正是这个示例的本地 Web 前端，官方定位为 "Local playground for Ten Agent"，负责提供 Agent 的交互界面（语音通话、实时字幕、消息聊天等）。

从仓库结构看，该前端与后端配套关系如下：

技术栈与工程结构

Playground 前端基于Next.js + React + TypeScript + shadcn/ui + Redux Toolkit，并集成了 Agora 官方 Web SDK。虽然 README 徽章标注为 Next.js 15 / React 18，但仓库实际 package.json 中锁定的是next 16.0.7、react 19.2.0，运行前以实际文件为准即可。

核心依赖一览（取自 package.json）：

• 通信：agora-rtc-sdk-ng（实时音视频）、agora-rtm（实时消息）、axios（HTTP）
• 状态管理：@reduxjs/toolkit+react-redux+redux
• UI 体系：@radix-ui/react-*系列原语 +tailwindcss+lucide-react+sonner（通知）+react-hook-form+zod
• 业务扩展：@trulience/react-sdk（数字人 Avatar）、protobufjs（STT 消息序列化）
• 开发工具：typescript、@biomejs/biome（lint/格式化）、protobufjs-cli

源码目录的核心模块：

frontend/src/ ├── app/api/agents/start/route.tsx # 启动 Agent 的 Next.js API 路由 ├── common/ # 常量、图配置、请求封装、存储工具 ├── components/ # Agent(音视频)、Chat、Dynamic、Layout、ui 等组件 ├── manager/rtc/ manager/rtm/ # Agora RTC 与 RTM 封装 ├── protobuf/SttMessage.proto # STT 消息 proto 定义 └── store/ # Redux 全局状态

其中 manager/rtc/ 与 manager/rtm/ 分别封装了 RTC 音视频与 RTM 消息能力，与后端双传输架构一一对应。

前置条件

按 frontend/README.md 要求，本地开发需要：

• Node.js >= 20（package.json的engines字段同样声明了该下限）
• pnpm 9.12.3：可通过corepack enable启用 Corepack 后使用对应版本

此外，Playground 只是"壳"，它依赖已启动的 Ten Agent 服务端。README 明确要求先按照示例根 README 的指引启动 Ten Agent 开发容器/服务，即 rtm-transport/README.md 中的环境变量与 Setup 部分：

• Agora：AGORA_APP_ID（RTC 与 RTM 共用，必填）、AGORA_APP_CERTIFICATE（可选）
• Deepgram：DEEPGRAM_API_KEY（STT，必填）
• OpenAI：OPENAI_API_KEY（LLM，必填），OPENAI_MODEL、OPENAI_PROXY_URL可选
• ElevenLabs：ELEVENLABS_TTS_KEY（TTS，必填）
• 可选：WEATHERAPI_API_KEY（天气工具）

本地开发：安装依赖并启动

安装依赖

# 进入前端目录 cd ai_agents/agents/examples/rtm-transport/frontend # 启用 corepack（按需） corepack enable # 安装依赖 pnpm install

启动开发服务器

pnpm dev

该命令实际执行的是next dev --turbopack（见 package.json 的scripts），启动后访问http://localhost:3000即可打开 Playground 界面。

使用 Taskfile 一键启动（推荐）

示例根目录的 Taskfile.yml 封装了完整链路：

• task install：依次执行tman install（拉取 TEN 扩展包）、安装 Python 依赖、安装前端依赖、构建 Go API Server
• task run：并行启动 TMAN Designer（:49483）、前端（:3000）、API Server（:8080）

cd ai_agents/agents/examples/rtm-transport task install task run

注意：Taskfile 中前端依赖使用bun（bun install --verbose、bun run dev），与 README 的 pnpm 方式二选一即可，效果等价。

三个服务端口

前端如何与 Agent 后端联调

启动 Agent 的 API 路由

前端通过 Next.js 路由 src/app/api/agents/start/route.tsx 代理请求：读取环境变量AGENT_SERVER_URL，向前端本地接口发起POST /start，将request_id、channel_name、user_uid、graph_name、properties透传给 Go API Server。因此运行前必须配置AGENT_SERVER_URL指向 API Server（默认 http://localhost:8080），否则接口会返回 "Environment variables are not available"。

前端配置项

src/common/constant.ts 中维护了 UI 侧的默认选项：

• DEFAULT_OPTIONS：channel（频道名）、userName、userId、appId、token，用于 RTC/RTM 入会
• GRAPH_OPTIONS：预置va_openai_azure（语音 Agent）与camera_va_openai_azure（带视觉），对应后端图的名称
• LANGUAGE_OPTIONS/VOICE_OPTIONS：语言（en-US/zh-CN/ko-KR/ja-JP）与音色（male/female）选择

这些参数最终经POST /start提交，后端按 tenapp/property.json 中定义的预置图voice_assistant拉起整套 Agent。

RTM 传输示例的图编排（后端上下文）

虽然前端只是交互层，但理解它服务的图能帮助你排查联调问题。voice_assistant图的节点与连接（见 tenapp/property.json）体现了双传输的关键设计：

音频流（RTC）：

agora_rtc (输入音频) → streamid_adapter (按 stream_id 注入 session_id 元数据) → stt (Deepgram ASR) → llm (OpenAI) → tts (ElevenLabs) → agora_rtc (输出音频)

消息流（RTM + RTC 数据通道）：

message_collector2 (接收 "message" 数据) → 将文本分块为 base64 → 经 agora_rtc 数据通道发送 → agora_rtm 发送 "rtm_message_event" 给 main_control

关键扩展一览：

其中 RTC 侧的channel为ten_agent_test、本地stream_id为 1234、订阅远端remote_stream_id为 123——前端连接时需与这些值保持一致（或通过 token 动态覆盖）。agora_rtm节点配置了channel_type: "message"、user_id: "1234"与rtm_enabled: true，token 在启动时动态覆盖。

生产构建与 Docker 部署

前端独立镜像

frontend/Dockerfile 采用bun + Next.js standalone的多阶段构建：deps阶段安装依赖 →builder阶段执行bun run build→runner阶段仅拷贝.next/standalone与.next/static，以非 root 用户运行，暴露3000端口。与之配套，next.config.mjs 开启了output: "standalone"，这是该镜像能够轻量化的前提。

整体示例镜像

示例根 README 提供了把整个 rtm-transport（前端 + API Server + tenapp）打包成镜像的方式（需在 Docker 容器外执行）：

cd ai_agents docker build -f agents/examples/rtm-transport/Dockerfile -t rtm-transport-app . docker run --rm -it --env-file .env -p 8080:8080 -p 3000:3000 rtm-transport-app

启动后访问 http://localhost:3000（前端）与 http://localhost:8080（API Server），.env文件需包含前面列出的 Agora / Deepgram / OpenAI / ElevenLabs 凭据。

常用脚本与自定义扩展

package.json 提供的脚本：

关于自定义：示例采用模块化设计，可通过 TMAN Designer（http://localhost:49483）可视化替换 STT / LLM / TTS 供应商，前端选择图与参数后即会生效，无需改动 Playground 代码。若涉及 proto 变更，记得在改动SttMessage.proto后执行pnpm proto重新生成绑定。

小结

本指南围绕 frontend/README.md 展开，覆盖了 Playground 的定位、技术栈、本地开发（pnpm install/pnpm dev）、与 Agent 后端的联调机制，以及 Docker 化部署路径，并结合 package.json、route.tsx、property.json 等源码给出了可验证的细节。你可以据此快速搭建起一套基于 Agora RTC + RTM 双传输的语音 Agent 调试环境，并进一步探索多用户分路 ASR、音视频 + 文本混合交互等高级玩法。

【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址: https://gitcode.com/TEN-framework/ten-framework