人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载在 TEN Framework 的 AI Agent 演示应用ai_agents/agents/examples/demo中main_realtime_python是承担中枢控制职责的 Python 扩展它负责把用户加入/离开、语音识别结果、实时大模型MLLM流式回复、工具调用等异构事件统一收敛到一个事件循环中再驱动问候语、字幕、打断与工具执行等行为。本文以该扩展的 README 为主线结合仓库内源码与图配置完整讲解其 API 数据契约、配置项、事件驱动架构与在 Demo 图中的实际接入方式读完后你将具备理解、配置甚至复刻这类实时语音 Agent 主控扩展的完整能力。扩展概览一个异步编排中枢main_realtime_python是 TEN Framework 的一个扩展Extension它本身不直接处理音频编解码而是作为 AI Agent 交互的中央控制逻辑接收 ASR 识别结果、驱动 LLM/MLLM 处理、协调 TTS 输出并维护用户会话状态与各组件间的数据流转。官方 README 中将其定位为 the orchestrator for AI agent conversations核心能力包括实时语音处理Real-time Speech Processing接收 ASRAutomatic Speech Recognition结果管理流式文本。LLM 集成LLM Integration协调语言模型完成自然语言理解与回复生成。TTS 协调TTS Coordination管理文本转语音请求驱动音频输出。会话管理Session Management跟踪用户在场状态加入/离开维护会话状态。流式支持Streaming Support同时处理最终结果与中间结果保证交互平滑。字幕生成Caption Generation面向可访问性与日志输出实时字幕。从源码结构看这一编排职责由MainControlExtension继承AsyncExtension与一个独立的Agent类协同完成前者负责与 TEN 运行时交互后者负责把底层命令/数据翻译成语义化事件。包结构与源码骨架扩展位于 ai_agents/agents/examples/demo/tenapp/ten_packages/extension/main_realtime_python核心文件如下文件职责addon.pyAddon 注册入口声明扩展名main_realtime_python并创建扩展实例extension.pyMainControlExtension生命周期管理、事件循环、对外发送逻辑agent/agent.pyAgent类命令/数据 → 语义事件的事件队列与工具调度agent/events.py8 类语义化 Agent 事件的定义Pydantic 模型config.pyMainControlConfig扩展配置模型helper.py_send_cmd/_send_data等图内消息发送工具manifest.json扩展清单名称、版本、依赖与属性 Schemaproperty.json默认属性当前为空对象配置由上层图注入扩展的注册方式很典型在 addon.py 中通过register_addon_as_extension(main_realtime_python)声明 addon 名称并在on_create_instance回调中返回MainControlExtension(name)实例。也就是说运行时在图中实例化该扩展时实际创建的类就是下面要讲的MainControlExtension。API 接口与数据契约README 定义了三类数据契约下面分别结合源码说明其实际消费方式。输入数据ASR Result{ text: string, final: bool, metadata: { session_id: string } }对应图中stt如azure_asr_python扩展产出的asr_result数据。在 agent.py 中DATA_MLLM_OUT_REQUEST_TRANSCRIPTmllm_server_input_transcript被解析为MLLMServerInputTranscript结构进而生成InputTranscriptEvent事件中携带delta、content、final与metadata四个字段。输入数据LLM Result{ text: string, end_of_segment: bool }对应 MLLM 服务端输出的流式回复。在 agent.py 中DATA_MLLM_OUT_RESPONSE_TRANSCRIPTmllm_server_output_transcript被解析为MLLMServerOutputTranscript生成携带delta、content、is_final、metadata的OutputTranscriptEvent。注意实际数据字段名在事件层是content与is_final与 README 简化的text/end_of_segment对应。输出数据Text Data{ text: string, is_final: bool, end_of_segment: bool, stream_id: uint32 }这是主控扩展向message_collector输出的字幕数据。查看 _send_transcript 的实现实际发送的载荷为{ data_type: transcribe, role: user | assistant, text: string, text_ts: 1720000000000, is_final: true, stream_id: 100 }其中text_ts取int(time.time() * 1000)毫秒时间戳stream_id对用户输入取自metadata.session_id缺省为100对助手输出固定为100。若配置了no_transcripttrue该函数会直接跳过发送用于抑制字幕。语义化事件模型从数据到事件README 的 API 章节只描述了原始 JSON而源码进一步将消息收敛为 8 类语义事件定义于 agent/events.py这是理解整个扩展的关键事件类触发来源语义UserJoinedEventon_user_joined命令用户加入会话UserLeftEventon_user_left命令用户离开会话ToolRegisterEventtool_register命令工具扩展注册工具元数据SessionReadyEventmllm_server_session_ready数据MLLM 会话就绪ServerInterruptEventmllm_server_interrupted数据服务端打断用户开始说话等InputTranscriptEventmllm_server_input_transcript数据用户输入转写部分/最终OutputTranscriptEventmllm_server_output_transcript数据助手输出转写流式FunctionCallEventmllm_server_function_call数据MLLM 发起函数调用这些事件全部继承自AgentEventBase含type与name两个字面量字段并以AgentEvent联合类型统一导出方便在事件循环中做模式匹配。命令体系Commands输入命令由外部扩展发往主控on_user_joined用户加入会话时触发。在 Demo 图中由agora_rtc扩展发出见下节图配置Agent.on_cmd将其转换为UserJoinedEvent入队主控据此递增_rtc_user_count并触发问候逻辑。on_user_left用户离开会话时触发主控递减用户计数。tool_register工具扩展如weatherapi_tool_python注册工具元数据时触发Agent会把LLMToolMetadata与来源扩展名存入tool_registry并透传给 MLLM 侧完成工具注册。对应实现在 agent.pyon_cmd按命令名分派处理成功后返回StatusCode.OK异常则返回StatusCode.ERROR。输出命令由主控发往其他扩展flush向 LLM/MLLM、TTS 与 RTC 组件发送清空/打断命令。查看 _interrupt 实现实际是向agora_rtc发送flush命令用于在检测到用户语音时中断正在进行的模型生成与音频播放保证边说边打断的低延迟体验。配置详解README 给出的配置示例为{ greeting: Hello there, Im TEN Agent }配置参数greetingstring第一名用户加入时展示的问候语。README 声称默认值为Hello there, Im TEN Agent但以仓库实际源码为准config.py 中MainControlConfig的默认值是Hello, I am your AI assistant.。no_transcriptbool默认false置为true时抑制向message_collector发送字幕。该参数已写入 manifest.json 的api.property.properties声明greeting为 string、no_transcript为 bool因此配置校验由 TEN 运行时按 Schema 强制执行。配置的加载路径在 extension.pyon_init中通过ten_env.get_property_to_json(None)读取图注入的全部属性再用MainControlConfig.model_validate_json做 Pydantic 校验得到强类型的self.config。在实际图配置中的用法在 Demo 应用的图配置 ai_agents/agents/examples/demo/tenapp/property.json 中main_control节点以main_realtime_pythonaddon 实例化并通过property注入问候语{ type: extension, name: main_control, addon: main_realtime_python, extension_group: control, property: { greeting: TEN Agent connected. How can I help you today? } }这意味着无需改动任何代码仅通过图配置即可更换开机问候语体现了扩展配置与实现解耦的设计。核心实现原理事件驱动的双循环架构README 的 Architecture 章节提到该扩展实现AsyncExtension接口并提供生命周期管理、异步事件处理、状态管理与数据路由。下面从源码还原其具体机制。生命周期管理MainControlExtension覆写了 4 个生命周期回调见 extension.pyon_init保存ten_env、加载配置、创建Agent实例并立即启动事件消费协程_consume_agent_eventsasyncio.create_task。on_start预留设置初始上下文消息的钩子源码中为注释掉的示例可自定义开场语境。on_stop置stopped True并调用agent.stop()停止事件队列。on_cmd/on_data将 TEN 运行时收到的命令与数据直接转交Agent处理。主事件循环_consume_agent_events 是核心循环while not self.stopped中不断await self.agent.get_event()从队列取事件然后用 Python 3.10 的match语句分派UserJoinedEvent→_rtc_user_count 1调用_greeting_if_ready()UserLeftEvent→_rtc_user_count - 1ToolRegisterEvent→ 转发agent.register_toolFunctionCallEvent→ 转发agent.call_toolInputTranscriptEvent→ 更新会话元数据、计算stream_id空文本直接跳过否则发送用户字幕OutputTranscriptEvent→ 发送助手字幕ServerInterruptEvent→ 调用_interrupt()发送flushSessionReadyEvent→ 置session_ready True并尝试问候其他 → 记录log_warn循环体以try/except包裹异常记log_error后继续保证单次事件失败不影响整个会话这种队列 单一消费循环的模式把并发来源RTC、ASR、MLLM、工具统一串行化处理避免了多协程竞争会话状态。问候语触发条件_greeting_if_ready 的触发条件有三个_rtc_user_count 1第一名用户、config.greeting非空、session_readyMLLM 会话就绪。满足后向v2v实时 MLLM 扩展发送一条roleuser的消息say {greeting} to me随后发送DATA_MLLM_IN_CREATE_RESPONSE请求生成回复——即问候语并非直接播放而是让模型说出来保证音色与语气统一。Agent 与工具调度Agent 类 维护一个asyncio.Queue[AgentEvent]与一个tool_registry: dict[str, str]工具名 → 注册来源扩展名工具注册register_tool把工具名映射到来源扩展并向v2v发送DATA_MLLM_IN_REGISTER_TOOL注册给模型。工具调用当 MLLM 发出FunctionCallEvent时call_tool依据tool_registry找到目标扩展向其发送tool_call命令载荷含name与解析后的arguments命令返回StatusCode.OK后读取CMD_PROPERTY_RESULT若结果类型为llmresult且内容是字符串则通过DATA_MLLM_IN_FUNCTION_CALL_OUTPUT回传给 MLLM形成模型调用工具 → 工具返回 → 模型生成最终回复的闭环。图内消息发送工具helper.py 提供三个便捷函数_send_cmd发送命令并等待结果、_send_cmd_ex异步生成器版本、_send_data发送数据。三者都通过Loc(, , dest)指定目标扩展名set_dests后经ten_env.send_cmd/send_data发送。文件注释特别提醒这类按目标扩展名直发的方式只对当前图有效通用型扩展应尽量避免而本扩展作为 Demo 图内的中枢正是其合理使用场景。在 Demo 图中的实际接入方式在 ai_agents/agents/examples/demo/tenapp/property.json 的实时语音图如va_gemini_v2v中main_control与周边节点的连接清晰展示了它的枢纽地位命令流入agora_rtc→main_control的on_user_joined、on_user_leftweatherapi_tool_python→main_control的tool_register。数据流入实时 MLLM 扩展v2vgemini_mllm_python配置了server_vad: true、transcribe_user: true、transcribe_agent: true等→main_control的mllm_server_input_transcript、mllm_server_output_transcript、mllm_server_session_ready、mllm_server_interrupted、mllm_server_function_call五路数据。音频通路agora_rtc→streamid_adapter→stt完成上行识别v2v的 PCM 直接回灌agora_rtc完成下行播放实时 MLLM 自带语音生成因此图中没有独立 TTS 节点。字幕通路main_control将转写数据发往message_collector再由agora_rtc的数据通道广播给客户端展示。这也印证了 README 的 Integration 章节主控扩展与 ASR、LLM、TTS、RTC、Message Collector 协作——在实时realtime模式下v2v这类多模态实时模型把 ASR/LLM/TTS 的能力合并进了一个扩展主控扩展则始终保持命令/数据收敛点的角色不变。完整工作流结合 README 的 Workflow 章节与源码一次完整会话的时序如下用户加入agora_rtc发出on_user_joined主控递增用户计数待v2v广播mllm_server_session_ready后若用户数为 1 且配置了greeting则向模型注入问候消息并请求回复。语音处理v2v流式产出mllm_server_input_transcript部分/最终主控生成用户侧字幕并维护session_id映射。LLM 处理最终语音片段进入实时模型生成回复图内无需主控显式转发模型持续监听音频流。回复生成mllm_server_output_transcript逐段返回主控生成助手侧字幕音频由v2v直接输出到 RTC。流式与打断中间结果与最终结果均被处理用户一旦开口mllm_server_interrupted触发主控向agora_rtc发送flush立即打断未完成的模型/播放。工具调用模型若发起函数调用如查询天气主控通过tool_registry路由到对应工具扩展并把结果回传模型继续生成。安装、构建与测试README 给出的标准命令如下均通过 TEN 包管理器执行# 安装扩展 ten install main_python # 构建扩展 ten build main_python # 运行扩展测试 ten test main_python需要说明的是README 中使用的名称main_python是文档层面的泛称仓库中该扩展的实际 addon 名称与包名是main_realtime_python见 manifest.json 与 addon.py执行安装/构建时应以实际名称main_realtime_python为准。该扩展随 Demo 应用tenapp一起分发在整仓环境中也可以跟随 ai_agents 构建脚本 一并构建。依赖与版本说明README 的 Dependencies 章节声明了两项依赖ten_runtime_python0.10TEN Framework 核心运行时Python 绑定。ten_ai_base0.6.9AI 基础能力消息结构、工具元数据、MLLM 协议常量等。但以仓库实际清单为准manifest.json 中声明的是ten_runtime_python0.11 与ten_ai_base0.7README 与 manifest 存在版本差异实际安装解析时以 manifest 为准。代码中大量使用的DATA_MLLM_*常量、MLLMClient*/MLLMServer*结构体均来自ten_ai_base的mllm与struct模块运行依赖与源码引用一致。架构特性小结README 的 Architecture 章节总结了四点结合源码可进一步确认生命周期管理on_init/on_start/on_stop三阶段清晰配置在初始化期完成校验加载。事件处理命令与数据先由Agent转成语义事件入队再由单一消费协程异步分派天然规避竞态。状态管理_rtc_user_count、session_ready、current_metadata共同决定问候时机与会话上下文。数据路由借助_send_cmd/_send_data按目标扩展名在图中直发字幕、flush、工具调用各归其位。许可与贡献该扩展随 TEN Framework 项目一起发布遵循 Apache License 2.0见仓库根目录 LICENSE贡献指南请参阅 TEN Framework 主文档如 AGENTS.md 与 docs/README-CN.md。总体而言main_realtime_python是一个小而完整的实时语音 Agent 中枢示例数据契约清晰、事件模型语义化、配置可通过图属性注入非常适合作为理解 TEN Framework 扩展间如何通过命令/数据/事件协作的入门范本也可以作为自研语音 Agent 主控扩展的直接参考骨架。赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐TEN Framework main_python 扩展实战构建 ASR-LLM-TTS 实时语音对话 Agent 中枢控制器TEN Framework main_python 扩展实战构建 ASR LLM TTS 实时语音对话 Agent 中枢控制器 导读 本文聚焦 TEN Fra人工智能AI Agent多模态语音AI 应用vue-burger-menu终极动画效果解析10种侧边栏过渡方式全攻略vue burger menu终极动画效果解析10种侧边栏过渡方式全攻略 vue burger menu是一款功能强大的Vue侧边栏组件提供了10种独特的动人工智能AI Agent多模态语音AI 应用TEN Framework 主控扩展 main_python 源码深度解析AI Agent 会话编排的核心引擎TEN Framework 主控扩展 main_python 源码深度解析AI Agent 会话编排的核心引擎 导读 main_python 是 TEN Fr人工智能AI Agent多模态语音AI 应用上一篇终极指南如何用OpCore Simplify一键生成黑苹果EFI配置下一篇OpenCore Legacy Patcher 三步免费升级让 2012 年的老 Mac 用上最新 macOS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
