TEN Framework 实时语音助手 main_python 扩展：会话编排中枢的架构与实现解析

人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载导读main_python是 TEN Framework 实时语音助手voice-assistant-realtime示例中的核心控制扩展位于 ai_agents/agents/examples/voice-assistant-realtime/tenapp/ten_packages/extension/main_python 目录承担着 AI 智能体对话的总编排角色它接收 ASR 语音识别结果、驱动 LLM 语义理解与回复生成、协调 TTS 语音输出并统一管理会话状态与数据路由。阅读本文后你将掌握该扩展的 API 接口设计、配置参数、事件驱动架构、与 RTC/LLM/TTS 等组件的协作方式并能够基于源码理解其底层实现原理为二次开发实时语音 Agent 提供可直接参考的实战范式。扩展定位实时语音 Agent 的控制中枢在 TEN Framework 中扩展extension是构成图graph的最小功能单元通过命令Cmd与数据Data进行通信。main_python扩展实现的是AsyncExtension异步接口其职责定位在 README 中有明确描述作为 AI Agent 交互的中央控制逻辑管理语音识别ASR、语言模型处理LLM与文本转语音TTS之间的协同。从源码结构看该扩展由以下模块组成文件职责addon.py通过register_addon_as_extension(main_python)注册扩展实例extension.pyMainControlExtension主类实现生命周期与事件消费循环agent/agent.pyAgent类将底层 Cmd/Data 转换为语义化 AgentEvent 并维护工具注册表agent/events.py定义全部 AgentEvent 事件模型config.pyMainControlConfigPydantic 配置模型helper.py_send_cmd/_send_data等图内消息发送工具值得强调的是addon.py 中通过装饰器注册后on_create_instance在运行时创建MainControlExtension(name)实例这是 TEN Framework 扩展加载的标准入口模式。功能特性总览README 将扩展能力归纳为六个方面这些能力在源码中均有对应实现实时语音处理接收 ASR 结果并管理流式文本对应InputTranscriptEvent处理LLM 集成协调语音到语音voice-to-voice模型完成语义理解与回复生成对应_send_message_item、_send_create_responseTTS 协调管理文本转语音请求输出音频会话管理跟踪用户在线状态与对话状态对应_rtc_user_count计数与session_ready标志流式支持同时处理最终结果与中间结果final/is_final字段贯穿始终字幕生成为无障碍与日志提供实时字幕对应_send_transcript转发到message_collector。事件驱动的双层架构设计从源码结构看该扩展采用底层消息 → 语义事件 → 业务分发的双层架构这是它区别于简单扩展的核心设计亮点。第一层Cmd/Data 到 AgentEvent 的转换agent.pyagent/agent.py 中的Agent类负责第一层转换on_cmd将on_user_joined、on_user_left、tool_register等命令转换为对应事件并放入asyncio.Queue事件队列on_data将来自 MLLM 服务端的数据如DATA_MLLM_OUT_REQUEST_TRANSCRIPT输入转写、DATA_MLLM_OUT_RESPONSE_TRANSCRIPT输出转写、DATA_MLLM_OUT_SESSION_READY会话就绪、DATA_MLLM_OUT_INTERRUPTED服务中断、DATA_MLLM_OUT_FUNCTION_CALL函数调用解析为语义事件。这些事件全部继承自 agent/events.py 中定义的AgentEventBase含type与name字段并汇总为AgentEventUnion 类型共覆盖八种事件UserJoinedEvent、UserLeftEvent、ToolRegisterEvent、SessionReadyEvent、ServerInterruptEvent、InputTranscriptEvent、OutputTranscriptEvent、FunctionCallEvent。第二层事件消费循环extension.pyextension.py 中的_consume_agent_events是核心事件循环通过await self.agent.get_event()持续从队列取事件并使用 Python 3.10 的match模式匹配分发UserJoinedEvent用户数加一触发_greeting_if_ready()欢迎逻辑UserLeftEvent用户数减一ToolRegisterEvent调用agent.register_tool将工具元数据转发给 MLLMFunctionCallEvent调用agent.call_tool执行工具调用InputTranscriptEvent提取session_id元数据并转发用户转写OutputTranscriptEvent转发助手回复转写ServerInterruptEvent触发打断逻辑_interrupt()SessionReadyEvent置位session_ready并尝试发送欢迎语。这种双层设计让框架层的 Cmd/Data与业务层的语义事件解耦扩展主类只关注事件语义逻辑清晰且易于扩展新事件类型。API 接口规范输入数据ASR 结果输入转写扩展从 MLLM 服务端接收的输入转写数据格式如下对应 agent/agent.py 中MLLMServerInputTranscript的解析{ text: string, final: bool, metadata: { session_id: string } }final字段区分中间结果与最终结果为false时表示流式过程中的增量转写为true时表示一段语音的最终识别结果。metadata.session_id用于多会话场景下区分不同用户或通道。LLM 结果输出转写{ text: string, end_of_segment: bool }end_of_segment标识一段回复是否结束。在源码中InputTranscriptEvent 与 OutputTranscriptEvent 分别额外携带delta增量片段、content累计内容与metadata字段其中OutputTranscriptEvent还提供is_final标记流式回复是否终结。输出数据文本数据转发给 message_collector{ text: string, is_final: bool, end_of_segment: bool, stream_id: uint32 }该结构由 _send_transcript 方法组装并发送。注意源码中实际发送的载荷还包含data_type: transcribe、roleuser/assistant、text_ts毫秒级时间戳等字段stream_id默认取session_id的整数值用户转写或固定值100助手回复用于流式字幕的排序与去抖。命令接口输入命令命令触发时机对应事件on_user_joined用户加入会话UserJoinedEventon_user_left用户离开会话UserLeftEventtool_register其他扩展注册工具ToolRegisterEvent输出命令flush发送刷新命令到 LLM、TTS 与 RTC 组件用于打断当前生成。源码 _interrupt 中向agora_rtc发送flush命令实现打断。配置详解扩展的配置在 manifest.json 的api.property.properties中声明为字符串类型实际解析由 config.py 中的 Pydantic 模型完成{ greeting: Hello there, Im TEN Agent }配置参数说明参数类型默认值说明greetingstringHello, I am your AI assistant.源码 config.py 中的默认值首个用户加入时发送的欢迎语需要说明两点与 README 的差异默认值差异README 示例写为Hello there, Im TEN Agent而源码 config.py 中 Pydantic 模型的默认值实为Hello, I am your AI assistant.实际生效值以运行时属性为准欢迎机制欢迎语并非直接显示而是通过 _greeting_if_ready 构造一条say {greeting} to me的用户消息注入 LLM并触发_send_create_response()让模型以语音方式说出欢迎语——即让模型把欢迎语说给用户听。配置加载发生在on_init生命周期中extension.py通过ten_env.get_property_to_json(None)读取运行时属性再用MainControlConfig.model_validate_json校验解析。由于扩展目录下 property.json 内容为空对象{}实际配置值来自应用图的属性注入见下文 graph 配置。依赖与运行环境manifest.json 声明了两项系统级依赖ten_runtime_python版本 0.11TEN Framework 的 Python 运行时提供AsyncExtension、AsyncTenEnv、Cmd、Data等核心 APIREADME 中标注为 0.10仓库实际 manifest 已升级为 0.11ten_ai_base版本 0.7AI 基础能力库提供 MLLM 客户端/服务端数据结构MLLMClientMessageItem、MLLMServerInputTranscript等与消息常量DATA_MLLM_IN_*/DATA_MLLM_OUT_*。打包配置中package.include包含manifest.json、property.json、**.tent、**.py、README.md与tests/**意味着该扩展以标准 TEN 包形式分发。使用指南安装扩展是 TEN Framework 的一部分可通过 TEN 包管理器安装ten install main_python集成组件main_python设计为与实时语音助手图中的其他组件协同工作。从示例应用 tenapp/manifest.json 的依赖列表可以看到完整组件阵容ASR/语音输入通过agora_rtc版本0.23.9-t1实时采集音频LLMvoice-to-voiceopenai_mllm_python、azure_mllm_python、gemini_mllm_python、glm_mllm_python、stepfun_mllm_python等多供应商 MLLM 扩展支持 OpenAI GPT Realtime、Azure Voice AI、Gemini 2.0 Flash、GLM、StepFun 等模型TTS由 voice-to-voice 模型直接输出语音无需独立 TTS 链路RTCagora_rtc承担实时通信streamid_adapter负责流 ID 适配消息收集器message_collector2接收转写字幕数据工具扩展weatherapi_tool_python提供天气查询工具演示工具调用链路。工作流结合源码完整对话流程如下用户加入RTC 通道建立后发送on_user_joined命令扩展计数用户数并在session_ready就绪时通过 LLM 触发欢迎语语音处理ASR 结果经 MLLM 服务端以输入转写数据下发扩展生成字幕并转发给message_collectorLLM 处理最终语音片段finaltrue作为完整消息送入 LLM模型以语音对语音方式直接生成回复回复生成LLM 输出转写流式返回扩展实时转发为字幕同时音频经 RTC 推流给用户流式交互中间结果finalfalse与最终结果finaltrue分开处理保证低延迟体验检测到用户再次说话时ServerInterruptEvent触发flush打断当前生成。工具调用main_python还内置了完整的工具调用Function Calling链路工具扩展通过tool_register命令注册工具Agent.register_tool将其记录在tool_registry并转发给 MLLM当 MLLM 发起DATA_MLLM_OUT_FUNCTION_CALL时Agent.call_tool根据工具名从注册表找到来源扩展向其发送tool_call命令工具执行结果若为llmresult类型则通过DATA_MLLM_IN_FUNCTION_CALL_OUTPUT回传给 MLLM 继续生成。构建与测试扩展使用 TEN Framework 标准构建系统ten build main_python运行扩展测试ten test main_python在示例应用层面tenapp/manifest.json 的 scripts 中build对应scripts/install_python_deps.sh安装 Python 依赖start对应scripts/start.sh。架构要点总结从源码抽象出的架构特征可归纳为四点生命周期管理实现on_init加载配置、创建 Agent、启动事件循环任务、on_start预留初始上下文注入点、on_stop置位停止标志并调用agent.stop()清空事件队列异步事件处理基于asyncio.Queue的事件队列与match模式匹配分发命令与数据处理均为异步状态管理_rtc_user_count追踪用户数、session_ready标记会话就绪、current_metadata维护当前会话元数据数据路由通过 _send_cmd / _send_data 在应用图内定向投递消息目标地址由Loc(, , dest)指定扩展名完成解耦通信。此外helper.py 还提供了parse_sentences中英文标点断句工具支持中英文逗号、句号、问号、感叹号可用于按句子粒度切分流式文本这在字幕渲染与分段 TTS 场景中非常实用。在示例应用中的实际配置main_python的实例化与配置发生在应用级 tenapp/property.json 的predefined_graphs中。以voice_assistant_realtime图为例agora_rtc节点配置 Agora 凭据与频道参数subscribe_audio、publish_audio、publish_data均开启v2v节点选用openai_mllm_python并配置model: gpt-realtime、voice: alloy、language: en、vad_type: semantic_vad、vad_eagerness: auto等语义级 VAD 参数实现端到端的极低延迟语音对话。greeting等扩展属性同样可在此处按需注入覆盖 config.py 中的默认值。运行该示例前需准备 Agora 凭据AGORA_APP_ID必填与至少一个语音模型提供商的 API KeyOpenAI/Azure/Gemini/GLM/StepFun 任选其一可参考示例目录下 README.md 的环境变量清单与task install/task run启动流程。许可协议main_python扩展作为 TEN Framework 的组成部分遵循 Apache License 2.0 开源许可允许自由使用、修改与再分发具体条款见仓库根目录 LICENSE。赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐TEN Framework 语音助手中枢扩展 main_python从 Twilio 通话到 ASR/LLM/TTS 的完整编排实践TEN Framework 语音助手中枢扩展 main_python从 Twilio 通话到 ASR/LLM/TTS 的完整编排实践 导读 main_pyth人工智能AI Agent多模态语音AI 应用TEN Framework 语音助手伴生 Agent 的中枢控制扩展main_python 架构解析与实战指南TEN Framework 语音助手伴生 Agent 的中枢控制扩展main_python 架构解析与实战指南 导读 main_python 是 TEN Fr人工智能AI Agent多模态语音AI 应用Activepieces Emailit 集成解析用 API v2 发送事务性邮件的 Piece 实现Activepieces Emailit 集成解析用 API v2 发送事务性邮件的 Piece 实现 在 Activepieces 工作流中邮件通知是最常人工智能AI Agent多模态语音AI 应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考