企业官网建设流程全解析

• 人工智能
• AI Agent
• 多模态
• 语音
• AI 应用

视频语音助手（Voice Assistant with Video）是 TEN Framework 官方提供的一个具备视觉感知能力的对话式语音 AI 示例：在经典「ASR → LLM → TTS」语音链路之上，额外接入 RTC 视频帧与视觉分析工具，让智能体既能听、能说，还能"看"。本文以 ai_agents/agents/examples/voice-assistant-video/README.md 为主线，完整讲解从环境安装、一键启动到图（Graph）架构、主控扩展源码实现的全部细节，读者将掌握该示例的运行方法、图编排原理，以及基于事件驱动模型二次开发视频语音 Agent 的具体路径。

示例定位：一个带视觉能力的语音 Agent

voice-assistant-video是 TEN Framework 的 AI Agent 示例集（ai_agents/agents/examples）中面向视频交互场景的参考实现。相比纯语音示例，它在会话中引入了视频帧的采集与分析：通过 Agora RTC 订阅远端视频流，将视频帧送给视觉分析工具（vision_analyze_tool_python），再借助一个独立的视觉 LLM 实例（vllm）完成图像内容理解，使 Agent 具备"看图说话"的能力。

整个示例以 TEN Framework 的Graph（预定义图）为核心组织方式：所有能力（RTC 接入、ASR、LLM、TTS、视觉分析、主控逻辑、转写收集）都被抽象为 extension 节点，通过 property 配置完成节点间的数据流编排，无需修改任何运行时代码即可调整链路。

快速开始：三步跑起视频语音助手

官方 README 给出的启动流程非常简洁，共三步。

第一步：安装依赖

task install

该命令通过仓库内的 Taskfile.yml 定义的任务链完成四件事：

执行task install前，需要确保本机已具备Task（任务执行器）、tman（TEN 包管理器，安装方式见 tools/tman/install_tman.sh）、bun（前端依赖管理）与Go工具链。

第二步：启动应用

task run

task run会以并行方式拉起三个进程（见 Taskfile.yml 中run任务的deps）：

1. run-gd-server：在./tenapp下执行tman designer，启动 TMAN Designer 的 HTTP 开发服务；
2. run-frontend：在playground目录执行bun run dev，启动 Web 前端；
3. run-api-server：执行./bin/api -tenapp_dir={{.PWD}}/tenapp，以 tenapp 目录为参数启动 API 服务（即上一步编译出的 Go 二进制）。

其中tenapp目录下的 main.go 是 TEN 应用入口：它通过ten.NewApp创建应用实例，并支持通过-property参数显式指定property.json路径（未指定时使用默认 property.json），随后appInstance.Run(true)阻塞运行。

第三步：访问应用

启动完成后，示例会开放三个端口：

环境变量：运行前必须准备

Taskfile.yml 第 3 行通过dotenv: ["../../../.env"]加载环境变量文件，因此使用前应在对应位置（即ai_agents目录下的.env）配置第三方服务密钥。结合 property.json 中"${env:...}"的引用，本示例需要以下变量：

需要注意的是，本示例在代码与配置层面只负责读取这些密钥并转发给对应扩展，密钥本身的获取与费用由各第三方服务商负责，属于运行前提而非仓库内容。

核心架构：预定义图（Predefined Graph）编排

示例的精华在于 property.json 中名为voice_assistant的预定义图。它声明了 9 个 extension 节点与它们之间的数据连接，理解这张图就等于理解了整个示例的工作方式。

节点（Nodes）一览

其中主控扩展main_python的自述文档位于 ten_packages/extension/main_python/README.md，是理解本示例业务逻辑的第一手资料。

关键数据流（Connections）

图中连接关系定义了各能力的协作方式，按数据方向可分为三类：

1）音频上行（用户说话 → 识别）

agora_rtc (audio_frame: pcm_frame) → streamid_adapter → stt (audio_frame: pcm_frame) stt (data: asr_result) → main_control (data: asr_result)

远端用户音频经 RTC 采集、流适配后送入 Deepgram 做语音识别，识别结果（含中间/最终结果）以asr_result数据流进入主控扩展。

2）音频下行（回复合成 → 播放）

main_control → tts (tts_text_input) [通过 send_data 命令直发] tts (audio_frame: pcm_frame) → agora_rtc (audio_frame 的 source)

主控扩展把 LLM 回复按句子切分后通过_send_to_tts发送给 TTS 扩展（见下文源码），合成的 PCM 音频再回流到 RTC 发布给远端用户。

3）视频上行（视觉感知）

agora_rtc (video_frame: video_frame) → vision_tool_python vision_tool_python (cmd: chat_completion) → vllm

RTC 订阅到的视频帧被送入视觉工具；视觉工具以 tool 形式向 LLM 注册能力（main_control的tool_register命令来源即vision_tool_python），当 LLM 需要看图时，通过chat_completion命令调用vllm完成多模态推理。

4）用户会话与消息

agora_rtc (cmd: on_user_joined / on_user_left) → main_control main_control → message_collector (data: message) [转写/消息下行] message_collector (data: data) → agora_rtc (data 的 source) [发回前端展示]

LLM 双实例的设计意图

图中存在llm与vllm两个openai_llm2_python实例：llm承载主对话（带greeting、max_memory_length: 10等记忆参数），vllm仅作为视觉推理通道，由视觉工具按需触发。这种"对话推理与视觉推理分离"的编排方式，是本示例在工程上区别于纯语音 Agent 的关键设计。

主控扩展 main_python 源码级解析

main_control（addon 为main_python）是整个 Agent 的"大脑"，采用事件驱动 + 异步队列的架构，核心代码集中在 ten_packages/extension/main_python 下。

1. 事件模型（agent/events.py）

events.py 定义了 5 种 Agent 事件，统一继承自AgentEventBase：

2. Agent 核心（agent/agent.py）

agent.py 中的Agent类提供三块核心能力：

• 事件注册与分发：on()方法同时支持agent.on(EventType, handler)与@agent.on(EventType)两种注册方式，_dispatch()将事件按类型顺序派发给已注册处理器；
• 双队列异步消费：_asr_queue与_llm_queue两个asyncio.Queue分别缓存 ASR 与 LLM 事件，由_consume_asr/_consume_llm两个常驻协程消费，保证事件处理有序；LLM 消费时通过asyncio.create_task包装处理器，便于在打断时取消进行中的任务；
• LLM 控制：register_llm_tool()向 LLM 注册工具、queue_llm_input()将用户文本入队、flush_llm()清空队列并取消活动任务、stop()完成优雅停机。

3. 主控扩展（extension.py）

extension.py 中的MainControlExtension继承AsyncExtension，在on_init中加载配置并自动扫描带@agent_event_handler装饰器的方法完成事件绑定（decorators.py 通过给方法附加_agent_event_type属性实现标记）。其业务逻辑包括：

• 问候语：首个用户加入（_rtc_user_count从 0 变 1）且配置了greeting时，向 TTS 发送问候语并输出转写。问候语来自 config.py 中的MainControlConfig，默认值为"Hello, I am your AI assistant."；
• ASR 流式处理：非空文本触发_interrupt()（打断正在进行的 LLM/TTS 输出，提升交互实时性），最终结果入队交给 LLM；
• LLM 流式处理与句子切分：借助 helper.py 的parse_sentences()按标点（中英文逗号、句号、问号、感叹号）切分增量文本，完整句子立即送 TTS 播报，剩余片段缓存等待下一增量——这是实现"边说边出"低延迟体验的关键；
• 打断机制：_interrupt()清空句子缓存、flush_llm()中断 LLM 推理，并向 TTS 发送tts_flush、向 RTC 发送flush命令，保证用户抢话时系统立即停止播报。

4. LLM 执行器（agent/llm_exec.py）

llm_exec.py 的LLMExec负责与 LLM 扩展的完整交互：

• 通过AsyncQueue串行处理用户输入，以chat_completion命令向llm扩展发起流式请求（streaming=True，temperature=0.7，携带tools列表）；
• 使用parse_llm_response解析流式响应，按LLMResponseMessageDelta / MessageDone / ReasoningDelta / ReasoningDone / ToolCall分派处理；
• 工具调用（LLMResponseToolCall）时根据tool_registry找到注册该工具的来源扩展，向其发送tool_call命令，再把工具结果以function_call_output消息回填上下文并继续追问 LLM，形成完整的 Function Call 循环；
• flush()时通过abort命令携带request_id通知 LLM 侧终止当前请求。

5. 直发辅助函数（helper.py）

helper.py 提供_send_cmd/_send_cmd_ex/_send_data三个便捷方法：通过Loc("", "", dest)指定目标扩展，即可在不显式建立连接的条件下向图内任意扩展发送命令/数据。源码注释明确指出这类用法包含针对当前图结构的假设（假定目标扩展必然存在于图中），因此它适用于业务编排扩展，通用型扩展应避免使用。

运行环境细节与扩展阅读

tenapp 启动脚本

scripts/start.sh 是 tman 启动 tenapp 时实际执行的脚本，它在启动bin/main前配置了三类运行时路径：

• PYTHONPATH：指向ten_packages/system/ten_ai_base/interface，确保 Python 扩展可导入ten_ai_base；
• LD_LIBRARY_PATH：加载agora_rtc_sdk、agora_rtm、azure_speech_sdk等原生库；
• NODE_PATH：指向ten_runtime_nodejs/lib。

脚本中注释掉的TEN_ENABLE_PYTHON_DEBUG/TEN_PYTHON_DEBUG_PORT环境变量表明：如需调试 Python 扩展，可取消注释并配合远程调试器使用。

依赖声明

manifest.json 是 tenapp 的包清单：声明了ten_runtime_go（版本 0.11）、agora_rtc（=0.23.9-t1）、ten_ai_base（0.7）等版本化依赖，并通过path形式引用仓库内 ten_packages/extension 下的本地扩展（ASR/TTS/LLM 全家桶、streamid_adapter、message_collector2、vision_analyze_tool_python等）。它同时声明了scripts.start（对应start.sh）与scripts.build（对应install_python_deps.sh）。

打包发布

如需将示例打包发布，可执行：

task release

该任务调用 ai_agents/scripts/release.sh 并传入 tenapp 目录路径，产出可分发的 TEN 应用包。

延伸阅读

• 纯语音（无视频）版本参考同目录下的 voice-assistant，与本示例形成对照；
• 前端交互界面源码位于 playground，API 服务源码位于 server；
• 想了解图上其他扩展的完整行为，可在 ai_agents/ten_packages/extension 中查找对应 addon（如vision_analyze_tool_python、deepgram_asr_python、elevenlabs_tts2_python）的 manifest 与 README。

小结

voice-assistant-video是理解 TEN Framework「图编排 + 事件驱动 Agent」理念的极佳范本：三条命令即可启动一套完整的视频语音 Agent；通过 property.json 的图配置，可以清晰看到音视频上行、回复下行、视觉推理三条数据通路的协作关系；而main_python扩展则以「事件 + 双队列 + 可取消任务」的方式，优雅地解决了流式 ASR/LLM/TTS 协同、句子级低延迟播报与抢话打断等真实场景问题。无论是要快速验证视频语音 Agent 的效果，还是以此为模板开发自己的多模态 Agent，本示例都是值得从图配置与源码两个层面精读的起点。

• 人工智能
• AI Agent
• 多模态
• 语音
• AI 应用