人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载导读本文以 ai_agents/agents/examples/voice-assistant-nodejs/README.md 为核心系统讲解 TEN Framework 中基于 Node.js 的实时语音助手示例如何用两条task命令跑通包含前端、API 服务与 TMAN Designer 的全栈应用并深入剖析其背后的图graph装配、Go 应用入口、Node.js 主控扩展main_nodejs的事件驱动架构、LLM 流式对话与工具调用实现。读完本文你将掌握该示例的启动流程、各服务端口分工、预定义图的节点与连接关系以及核心扩展的源码级工作原理能够据此替换 STT/LLM/TTS 服务商或扩展自己的 Agent 逻辑。一、示例概览一个可运行的全栈语音助手voice-assistant-nodejs是 TEN Framework 提供的官方示例之一展示了如何使用Node.js 编写语音助手的主控扩展并与其他语言Go 应用层、Python 服务商扩展的组件协同工作。示例整体支持实时对话能力与 AI 集成用户通过 Agora RTC 接入音视频流语音经 STT 转写后送入 LLM 生成回复再经 TTS 合成语音回传同时提供天气查询等工具调用能力。示例目录结构如下ai_agents/agents/examples/voice-assistant-nodejs/ ├── README.md # 官方快速开始文档 ├── Taskfile.yml # task 任务编排安装/构建/运行/发布 ├── Taskfile.docker.yml # Docker 场景下的任务编排 ├── Dockerfile └── tenapp/ # TEN 应用App主体 ├── main.go # Go 语言应用入口 ├── manifest.json # 应用清单与依赖声明 ├── property.json # 预定义图graph与运行配置 ├── scripts/ │ ├── install_deps.sh # 一键安装 Node.js / Python / Go 依赖 │ └── start.sh # 应用启动脚本环境变量注入 └── ten_packages/extension/main_nodejs/ # Node.js 主控扩展 ├── manifest.json / property.json ├── package.json / tsconfig.json ├── src/ │ ├── index.ts # MainControlExtension 主控扩展 │ ├── helper.ts # 队列、句子切分、命令/数据发送工具 │ └── agent/ │ ├── agent.ts # Agent 事件总线与异步队列 │ ├── llm_exec.ts # LLM 流式请求与工具调用执行器 │ ├── events.ts # 事件类型定义 │ └── struct.ts # LLM 协议结构 └── tests/src/ # 单元测试index.spec.ts / main.spec.ts二、快速开始三条命令跑通全栈服务官方 README 给出了最简启动流程共三个步骤安装依赖task install运行语音助手task run访问应用前端Frontendhttp://localhost:3000API 服务API Serverhttp://localhost:8080TMAN Designerhttp://localhost:49483其中task是任务执行器任务定义位于 ai_agents/agents/examples/voice-assistant-nodejs/Taskfile.yml并通过dotenv: [../../../.env]从仓库根目录即ai_agents/.env加载环境变量。运行前需要准备一个.env文件填入图配置中引用到的服务商密钥详见第四节。提示task run会同时拉起三个常驻服务前端、API 服务、TMAN Designer因此会在终端前台持续运行若只部署应用本体可改用task run-tenapp单独启动 TEN 应用。三、Available Tasks 详解install / build / run / releaseREADME 中列出的任务只是 Taskfile 的顶层入口Taskfile.yml 内部将每个任务拆解为多个可复用子任务下表汇总了全部任务及其实际作用任务内部依赖实际执行内容对应目录task installinstall-tenapp → install-tenapp-deps → install-frontend → build-api-server安装 TEN 包tman install、安装 Node.js/Python 依赖、前端bun install、编译 Go API 服务tenapp / playground / servertask buildbuild-tenapp编译 tenapp 内所有 Node.js 工程./scripts/build.shtenapptask runrun-gd-server run-frontend run-api-server并行启动 TMAN Designer、前端开发服务器、API 服务tenapp / playground / servertask release—调用 ai_agents/agents/scripts/release.sh 生成发布包tenapp子任务细节如下install-tenapp在tenapp目录执行tman install按 manifest.json 拉取系统运行时ten_runtime_go、ten_runtime_nodejs、nodejs_addon_loader、ten_ai_base、Agora RTC 扩展以及全部本地路径声明的 STT/LLM/TTS 扩展。install-tenapp-deps调用 scripts/install_deps.sh该脚本会依次完成三件事通过go run .../ten_runtime_go/tools/build/main.go --verbose编译 Go 应用生成bin/main遍历 tenapp 及ten_packages/extension、ten_packages/system下所有含package.json的目录执行npm install可用NPM_INSTALL_CMD覆盖遍历所有含requirements.txt的目录执行 Python 依赖安装默认uv pip install --system可用PIP_INSTALL_CMD覆盖。install-frontend在playground前端工作台目录执行bun install --verbose。build-api-server在server目录执行go mod tidy go mod download go build -o bin/api main.go产出 API 服务二进制。run-gd-server在 tenapp 目录执行tman designer启动 TMAN Designer图形化设计器端口 49483。run-frontend在 playground 目录执行bun run dev启动前端开发服务器端口 3000。run-api-server以./bin/api -tenapp_dir{{.PWD}}/tenapp启动 API 服务端口 8080其中{{.PWD}}为 Taskfile 所在目录的绝对路径。run-tenapp先 build-tenapp再执行tman run start即按 manifest 中的scripts.start调用 scripts/start.sh 启动 TEN 应用本体。四、应用装配manifest.json 与 property.json 预定义图4.1 应用清单声明运行时与扩展依赖tenapp/manifest.json 声明了应用的类型、名称、版本与依赖。核心依赖分为三类系统运行时ten_runtime_go、ten_runtime_nodejs版本 0.11以及 Node.js 扩展加载器nodejs_addon_loader保证 Node.js 扩展能在 TEN 运行时中运行核心扩展agora_rtc音视频接入固定版本0.23.9-t1、ten_ai_baseAI 基础协议本地路径扩展以path形式引用ai_agents/ten_packages/extension下的大量 ASR、LLM、TTS 扩展包括 deepgram_asr_python、openai_llm2_python、minimax_tts_websocket_python、message_collector2、weatherapi_tool_python、streamid_adapter 等。manifest 同时把scripts.start指向scripts/start.sh这是tman run start的启动入口。4.2 预定义图voice_assistanttenapp/property.json 中定义了一个名为voice_assistant的预定义图auto_start: true表示应用启动后自动加载。图中共有 8 个扩展节点节点名addon扩展组职责agora_rtcagora_rtcdefault通过 Agora RTC 接入/发布音频处理用户进出事件sttdeepgram_asr_pythonstt语音转写Deepgram模型 nova-3语言 en-USllmopenai_llm2_pythonchatgpt对话生成OpenAI 兼容接口ttsminimax_tts_websocket_pythontts语音合成MiniMaxspeech-02-turbomain_controlmain_nodejscontrolNode.js 主控扩展协调整个会话流程message_collectormessage_collector2transcriber收集/转发对话转写消息weatherapi_tool_pythonweatherapi_tool_pythondefault天气查询工具函数调用streamid_adapterstreamid_adapter—音频流 ID 适配桥接 RTC 与 STT4.3 图的连接关系connectionsproperty.json 中通过connections定义了扩展之间的消息通路这是理解整个数据流的关键主控扩展main_control的输入cmd接收来自agora_rtc的on_user_joined/on_user_left用户进出事件接收来自weatherapi_tool_python的tool_register工具注册data接收来自stt的asr_result语音转写结果。音频通路围绕 agora_rtcagora_rtc的audio_frame/pcm_frame输出到streamid_adapterstreamid_adapter的pcm_frame输出到stt送入识别tts合成的pcm_frame输出回agora_rtc播放message_collector的data输出到agora_rtc。由此得到完整数据流RTC 音频 → streamid_adapter → STT 转写 → main_controlNode.js→ LLM 生成 → 句子切分 → TTS 合成 → RTC 播放同时 main_control 将用户/助手的转写文本发给 message_collector 用于展示。4.4 环境变量图配置中的密钥注入property.json 大量使用${env:VAR}语法从环境变量读取配置${env:VAR|}表示该变量可选缺省为空字符串。运行前需要在.env中配置环境变量用途是否必填AGORA_APP_ID/AGORA_APP_CERTIFICATEAgora RTC 应用凭证是 / 可选DEEPGRAM_API_KEYDeepgram STT 密钥是OPENAI_API_KEY/OPENAI_MODEL/OPENAI_PROXY_URLOpenAI LLM 密钥、模型名、代理地址是 / 是 / 可选MINIMAX_TTS_API_KEY/MINIMAX_TTS_GROUP_IDMiniMax TTS 凭证可选未配置时 TTS 不会发声WEATHERAPI_API_KEY天气工具密钥可选此外agora_rtc 节点还配置了channel: ten_agent_test、stream_id: 1234、remote_stream_id: 123等频道参数llm 节点配置了max_tokens: 512、frequency_penalty: 0.9、max_memory_length: 10上下文记忆轮数、greeting欢迎语。更换服务商只需修改对应节点addon名称及其property并确保该扩展已在 manifest 中声明无需改动 Node.js 主控代码——这正是图编排带来的解耦优势。五、Go 应用入口与启动脚本5.1 main.go极简的应用宿主tenapp/main.go 是一个标准的 Go 应用入口它通过ten_framework/ten_runtimeGo 绑定创建一个defaultApp支持-property命令行参数指定自定义property.json的绝对路径未指定时使用应用目录下的默认property.jsonOnConfigure中将 property 文件内容通过tenEnv.InitPropertyFromJSONBytes注入运行时然后调用OnConfigureDonestartAppBlocking创建应用实例并阻塞运行Run(true)Wait()退出前执行EnsureCleanupWhenProcessExit清理资源。5.2 start.sh环境变量注入scripts/start.sh 在启动前设置运行环境export PYTHONPATH$(pwd)/ten_packages/system/ten_ai_base/interface:$PYTHONPATH export LD_LIBRARY_PATH$(pwd)/ten_packages/system/agora_rtc_sdk/lib:$(pwd)/ten_packages/extension/agora_rtm/lib:$(pwd)/ten_packages/system/azure_speech_sdk/lib export NODE_PATH$(pwd)/ten_packages/system/ten_runtime_nodejs/lib:$NODE_PATH exec bin/main $即注入 ten_ai_base 的 Python 接口路径、RTC 相关动态库路径以及 Node.js 运行时库路径保证扩展能import ten-runtime-nodejs最后启动编译好的bin/main。六、Node.js 主控扩展源码剖析6.1 MainControlExtension生命周期与会话编排主控扩展位于 src/index.ts类名MainControlExtension通过RegisterAddonAsExtension(main_nodejs)注册为 addon 名为main_nodejs的扩展。它实现了 TEN 扩展的标准生命周期钩子onConfigure/onInit/onStart/onCmd/onData/onStop/onDeinit。在onInit中扩展从 property 读取配置用 zod 校验greeting字段并注册四类事件处理器UserJoinedEvent首个用户加入时向 TTS 发送欢迎语_send_to_tts并同步发送一条 assistant 转写UserLeftEvent维护在线用户计数ASRResultEvent收到asr_result后若文本非空且为final或长度大于 2先触发_interrupt()打断上一轮 LLM/TTS 输出避免叠加回声再将完整文本通过agent.queueLLMInput送入 LLM同时把用户转写发给 message_collectorLLMResponseEvent对message类型的非最终增量调用parseSentences按中英文标点切分完整句子并逐句送 TTS实现边说边合成的低延迟体验同时把text或reasoning类型的增量转写发给 message_collector。打断机制_interrupt是实时语音助手的关键细节清空未完成的句子片段 →agent.flushLLM()中止 LLM 请求 → 向tts发送tts_flush→ 向agora_rtc发送flush命令保证用户随时插话时旧输出被立即停止。6.2 Agent事件总线与无轮询异步队列src/agent/agent.ts 中的Agent类实现了一个轻量级事件系统on(eventClass, handler)注册处理器dispatch按事件类型分发内部维护asrQueue与llmQueue两个可等待队列配合queueMicrotask实现的 drain 调度器scheduleASRDrain/scheduleLLMDrain串行消费事件避免轮询忙等LLM 队列严格串行保证对话顺序onCmd处理on_user_joined/on_user_left/tool_register命令onData解析asr_result数据并触发 ASR 事件flushLLM通过AbortController中止排队与进行中的 LLM 任务用于打断场景。6.3 LLMExec流式对话与工具调用src/agent/llm_exec.ts 中的LLMExec负责与 LLM 扩展交互队列化输入queueInput将用户文本入队drain 循环逐个构造{ role: user, content }消息调用_sendToLLM流式请求_sendToLLM通过sendCmdEx向llm扩展发送chat_completion命令携带request_id、消息上下文、streaming: true、温度参数与可用工具列表并以for await消费流式CmdResult响应分型处理_handleLLMResponse依据parseLLMResponse解析出的类型分发——message_content_delta增量文本、message_content_done完成、message_reasoning_delta/done思维链、tool_call_content工具调用工具调用闭环收到tool_call_content后通过toolRegistry找到注册该工具名的扩展如weatherapi_tool_python向其发送tool_call命令解析返回的llmresult把function_call与function_call_output消息追加进上下文并再次调用_sendToLLM让 LLM 基于工具结果继续生成上下文管理contexts数组维护多轮对话_writeContext会就地更新最后一条同角色纯文本消息以避免上下文膨胀。6.4 辅助工具句子切分与图内通信src/helper.ts 提供四个关键工具parseSentences(fragment, content)按中英文逗号/句号/问号/感叹号切分流式文本为完整句子与残留片段且只保留包含字母数字的句子过滤纯符号噪声——这是逐句送 TTS的低延迟基础AsyncQueueT支持AbortSignal的可等待队列供 Agent / LLMExec 使用sendCmd/sendCmdEx构造Cmd并setDests指定目标扩展名发送命令sendCmdEx为流式版本返回 AsyncGeneratorsendData构造Data发送数据消息。事件类型events.ts统一继承AgentEventBase包括UserJoinedEvent、UserLeftEvent、ToolRegisterEvent、ASRResultEvent、LLMResponseEvent构成扩展内部的事件协议。七、测试与可扩展方向示例附带了针对主控扩展的单元测试位于 tests/srcindex.spec.ts/main.spec.ts可在扩展目录下通过 npm 测试框架运行用于验证扩展生命周期与事件处理逻辑。基于上述源码结构后续可扩展的方向包括更换服务商修改 property.json 中stt/llm/tts节点的addon与property示例 manifest 已内置十余种 ASR、LLM、TTS 扩展可选新增工具参照weatherapi_tool_python注册tool_register命令即可接入 LLM 函数调用多用户会话agent.ts中session_id/turn_id已随转写与 TTS 元数据透传可据此实现按会话隔离的上下文管理。八、常见问题排查task install失败确认已安装task、bun、tman与 Go 工具链tman install需要网络访问 TEN 包仓库Python 依赖安装命令可用PIP_INSTALL_CMD覆盖如pip install。运行后无声音/无识别检查.env中AGORA_APP_ID、DEEPGRAM_API_KEY、OPENAI_API_KEY等是否配置正确start.sh中的LD_LIBRARY_PATH依赖tman install成功拉取 Agora SDK 库。前端 / API 端口被占用三个服务端口3000 / 8080 / 49483均为默认值可依据 Taskfile.yml 中对应任务调整启动参数。总结voice-assistant-nodejs示例展示了一条完整的 Node.js 语音助手落地路径通过task install/task run两条命令即可拉起前端、API 服务与 TEN 应用以main_nodejs扩展为核心的图编排将 Agora RTC、Deepgram STT、OpenAI LLM、MiniMax TTS 与天气工具串联成实时对话闭环。其源码中的异步队列、流式句子切分、打断机制与工具调用闭环为在 TEN Framework 上使用 Node.js 构建生产级语音 Agent 提供了可直接参考的工程范式。赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐TEN Framework 实战指南从 Agent Examples 快速启动到 Docker 自托管部署实时多模态语音助手TEN Framework 实战指南从 Agent Examples 快速启动到 Docker 自托管部署实时多模态语音助手 导读 TEN 是一个开源的实时多人工智能AI Agent多模态语音AI 应用TEN Framework 视频语音助手示例 voice-assistant-video快速上手与架构深度解析TEN Framework 视频语音助手示例 voice assistant video快速上手与架构深度解析 视频语音助手Voice Assistant人工智能AI Agent多模态语音AI 应用TEN Framework 实时语音助手 main_python 扩展会话编排中枢的架构与实现解析TEN Framework 实时语音助手 main_python 扩展会话编排中枢的架构与实现解析 导读 main_python 是 TEN Framewor人工智能AI Agent多模态语音AI 应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考