TEN Framework 主控扩展 main_python 源码深度解析AI Agent 会话编排的核心引擎【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址: https://gitcode.com/TEN-framework/ten-framework导读main_python是 TEN Framework 中负责AI Agent 会话编排的核心 Python 扩展Extension它像一位总指挥串联起语音识别ASR、大语言模型LLM、文本转语音TTS与实时通信RTC等组件让一次语音进、语音出的完整 Agent 交互得以流畅运转。本文以该扩展的 README 为主线结合其真实源码事件总线、流式 LLM 执行器、会话状态管理逐层拆解其数据流、事件模型与配置方式读完你将掌握如何阅读、配置乃至二次开发一个 TEN 主控类扩展。概述什么是 main_python在 TEN Framework 的 Agent 应用中main_python承担的是**中央控制逻辑central control logic**角色。它以AsyncExtension的形式运行负责处理实时语音识别结果ASR维护流式文本与语言模型LLM交互协调自然语言理解与响应生成向 TTS 发送语音合成请求完成音频输出跟踪用户会话状态管理对话上下文处理中间结果intermediate与最终结果final保证交互流畅生成实时字幕caption兼顾无障碍与日志记录。在 doodler 示例应用面向儿童的语音绘图应用中main_python正是把agora_rtc语音输入、openai_asr_pythonWhisper 转写、openai_llm2_pythonGPT-4o-mini 理解意图、openai_gpt_image_python绘图工具与message_collector聊天记录串成完整工作流的粘合剂。功能特性按照 README该扩展提供以下核心能力实时语音处理Real-time Speech Processing接收并处理 ASR 结果管理流式文本区分中间结果与最终结果LLM 集成LLM Integration协调语言模型完成自然语言理解与响应生成TTS 协调TTS Coordination管理文本转语音请求驱动音频输出会话管理Session Management跟踪用户上下线presence维护会话与轮次状态流式支持Streaming Support同时处理 final 与 intermediate 结果保障体验平滑字幕生成Caption Generation为 accessibility 与日志提供实时字幕。API 接口输入、输出与命令输入数据Input DataASR 结果语音识别模块通过名为asr_result的 Data 帧上报识别结果其 JSON 结构为{ text: string, final: bool, metadata: { session_id: string } }字段说明text为识别出的文本final标识是否为最终结果false表示中间结果metadata.session_id用于标识来源会话。在 agent.py 的on_data中扩展会读取该 Data 的名称若为asr_result则解析 JSON 并封装为ASRResultEvent投入事件队列。LLM 结果语言模型以流式方式返回响应其数据结构为{ text: string, end_of_segment: bool }输出数据Output Data文本数据Text Data主控扩展向字幕/消息收集器输出的结构化文本包含{ text: string, is_final: bool, end_of_segment: bool, stream_id: uint32 }其中stream_id由会话 ID 转换而来源码中stream_id int(self.session_id)用于把多条字幕流关联到同一个会话。命令Commands输入命令上游如 RTC 扩展可通过 Cmd 通知用户状态变化on_user_joined用户加入会话时触发on_user_left用户离开会话时触发。此外源码中还支持tool_register命令用于注册 LLM 工具详见下文工具注册小节。输出命令主控扩展对外发送的典型命令为flush用于向 LLM、TTS 和 RTC 组件下发冲刷/打断信号终止正在进行的生成。配置greeting 参数扩展支持通过运行时属性property进行配置README 给出的配置示例为{ greeting: Hello there, Im TEN Agent }配置参数表参数类型默认值说明greetingstring见下方说明第一位用户加入时展示/播报的问候语需要说明的是README 示例中的默认值为Hello there, Im TEN Agent而仓库内 config.py 中MainControlConfig的实际默认值是Hello, I am your AI assistant.。greeting通过 Pydantic 的BaseModel定义在 extension.py 的on_init中通过ten_env.get_property_to_json(None)读取运行时属性并调用MainControlConfig.model_validate_json()完成校验与装载。同时在 manifest.json 的api.property.properties中声明了greeting的 JSON Schema 类型为string供 TEN 框架校验。源码验证当第一位用户加入且配置了问候语时_on_user_joined会同时向 TTS 发送问候语音_send_to_tts并向 message_collector 发送assistant角色的字幕_send_transcript实现开口即欢迎。依赖README 声明扩展依赖两个 TEN 系统包ten_runtime_pythonTEN Framework 核心运行时README 标注 0.10当前 manifest.json 实际声明为 0.11ten_ai_baseAI 基础能力库提供LLMToolMetadata、LLMRequest/LLMResponse等结构README 标注 0.6.9manifest 实际声明为 0.7。依赖声明方式在扩展的manifest.json的dependencies数组中以system类型声明安装时由 TEN 包管理器自动解析。安装与集成安装该扩展随 TEN Framework 分发布可通过 TEN 包管理器安装ten install main_python在 doodler 示例中扩展位于 ten_packages/extension/main_python其中addon.py通过register_addon_as_extension(main_python)完成 Addon 注册on_create_instance负责实例化MainControlExtension。集成组件该扩展被设计为与以下 TEN 组件协同工作ASR 扩展提供语音识别结果LLM 扩展处理自然语言并生成响应TTS 扩展将文本转为语音RTC 扩展处理实时通信含用户上下线通知与打断Message Collector消息收集器捕获并展示会话数据字幕、推理过程等。在 doodler 的图配置tenapp/property.json中这些组件通过有向连接与main_python组成 Agent 图。工作流一次完整对话的五个阶段README 将一次典型交互拆解为 5 步用户加入User Joins用户上线触发on_user_joined若配置了问候语则先送出欢迎语语音处理Speech ProcessingASR 结果到达后被处理并生成字幕LLM 处理LLM Processing最终语音段finaltrue被送入 LLM 处理响应生成Response GenerationLLM 响应被转为语音并作为字幕展示流式输出Streaming中间与最终结果均被妥善处理保证交互平滑。源码级数据流佐证结合 extension.py 的事件处理器上述流程的底层实现如下ASR 结果处理_on_asr_result更新session_id与stream_id当finaltrue或文本长度大于 2 时先调用_interrupt()打断旧输出finaltrue时turn_id 1并将文本通过agent.queue_llm_input()送入 LLM随后无论中间还是最终结果都会调用_send_transcript(user, ...)发送用户字幕。打断机制_interrupt清空句子碎片调用agent.flush_llm()冲刷 LLM 队列并取消进行中的任务同时向tts发送tts_flushData、向agora_rtc发送flushCmd——这是实现用户一开口就立刻打断机器说话的关键。LLM 响应处理_on_llm_response中间message结果累积到sentence_fragment最终结果时通过_select_tts_text提取首个完整句子借助helper.parse_sentences按中英文标点切句无有效内容时回退为默认提示语Got it. Drawing now!并保证每轮只发送一次 TTS通过_tts_sent_turn_id与turn_id比对推理过程reasoning类型则以data_typeraw的 JSON 形式发送给 message_collector。字幕发送_send_transcript统一构造messageData 发往message_collector携带data_type、role、text、text_ts、is_final、stream_id等字段。架构事件驱动的 Agent 内核README 指出该扩展实现了AsyncExtension接口提供生命周期管理、事件处理、状态管理与数据路由能力。从源码看其内核是一个轻量级事件总线 双异步队列的 Agent 框架1. 事件模型agent/events.py所有事件继承自 Pydantic 的AgentEventBase分为 Cmd 类与 Data 类UserJoinedEvent/UserLeftEventCmd 类用户上下线ToolRegisterEventCmd 类携带LLMToolMetadata与来源扩展名用于注册 LLM 工具ASRResultEventData 类携带text、final、metadataLLMResponseEventData 类携带delta、text、is_final并用type区分普通消息message与推理过程reasoning。统一类型AgentEvent是上述五者的 Union作为事件分发与类型匹配的依据。2. 事件注册与分发agent/agent.pyAgent类维护一个_callbacks注册表支持agent.on(EventType, handler)与agent.on(EventType)两种注册方式。extension.py在on_init中通过扫描实例方法上的_agent_event_handler装饰器元数据完成自动注册。_dispatch按事件类型匹配isinstance并串行执行所有处理器单处理器异常仅记录日志而不中断整体分发。3. 双队列消费者ASR / LLM 分离Agent内置_asr_queue与_llm_queue两个asyncio.Queue并各启动一个消费者任务。LLM 消费端特别设计为可取消_consume_llm将分发逻辑包装为asyncio.create_task以便flush_llm()在打断时能取消进行中的 LLM 处理任务并清空队列——这是实现低延迟打断的并发基础。4. LLM 执行器agent/llm_exec.pyLLMExec是 LLM 交互的具体执行者输入队列queue_input()将用户文本入队_process_input_queue循环消费并构造LLMMessageContent(roleuser, ...)流式请求通过_send_cmd_ex向llm扩展发送chat_completionCmdstreamingTrue模型名传空字符串表示使用 LLM 扩展默认模型temperature0.7并携带toolsself.available_tools响应分发_handle_llm_response用match语句分派LLMResponseMessageDelta增量文本、LLMResponseMessageDone结束、LLMResponseReasoningDelta/Done推理流与LLMResponseToolCall工具调用上下文管理_queue_context/_write_context维护contexts消息列表连续同角色消息自动合并工具调用LLMResponseToolCall触发时根据tool_registry找到注册该工具的扩展向其发送tool_callCmd成功后把function_call与function_call_output写回上下文并继续请求 LLM形成工具增强闭环。5. 图内通信工具helper.py_send_cmd/_send_data是图内便捷通信函数通过Loc(, , dest)指定目标扩展名即可在无需显式连线的情况下向图内其他扩展发送 Cmd 或 Data——这正体现了主控扩展假设目标扩展已存在于图中的编排式设计源码注释明确提示此类写法只适用于特定图通用扩展应避免使用。开发构建与测试构建该扩展使用 TEN Framework 标准构建系统ten build main_python测试运行扩展测试ten test main_python从 manifest.json 的package.include可见发布包会包含manifest.json、property.json、**.tent、**.py、README.md与tests/**测试目录被显式纳入打包范围。生命周期与状态管理小结扩展完整实现了AsyncExtension生命周期钩子on_init加载配置MainControlConfig、创建Agent、自动注册事件处理器on_start记录启动日志on_stop置stopped标志、调用agent.stop()内部依次停止 LLMExec、冲刷 LLM 队列并取消 ASR/LLM 消费者任务on_cmd/on_data把框架层的 Cmd/Data 透传给Agent由Agent转换为领域事件。状态管理方面扩展用_rtc_user_count跟踪在线用户数首个用户上线才触发问候、turn_id标记对话轮次、session_id标识会话、_tts_sent_turn_id防止重复播报——这些字段共同构成了多用户场景下会话编排的状态基础。许可证该扩展属于 TEN Framework 的一部分遵循 Apache License 2.0 开源协议发布如需贡献请参阅 TEN Framework 主仓库的贡献指南AGENTS.md 与 CLAUDE.md。【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址: https://gitcode.com/TEN-framework/ten-framework创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TEN Framework 主控扩展 main_python 源码深度解析：AI Agent 会话编排的核心引擎
TEN Framework 主控扩展 main_python 源码深度解析AI Agent 会话编排的核心引擎【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址: https://gitcode.com/TEN-framework/ten-framework导读main_python是 TEN Framework 中负责AI Agent 会话编排的核心 Python 扩展Extension它像一位总指挥串联起语音识别ASR、大语言模型LLM、文本转语音TTS与实时通信RTC等组件让一次语音进、语音出的完整 Agent 交互得以流畅运转。本文以该扩展的 README 为主线结合其真实源码事件总线、流式 LLM 执行器、会话状态管理逐层拆解其数据流、事件模型与配置方式读完你将掌握如何阅读、配置乃至二次开发一个 TEN 主控类扩展。概述什么是 main_python在 TEN Framework 的 Agent 应用中main_python承担的是**中央控制逻辑central control logic**角色。它以AsyncExtension的形式运行负责处理实时语音识别结果ASR维护流式文本与语言模型LLM交互协调自然语言理解与响应生成向 TTS 发送语音合成请求完成音频输出跟踪用户会话状态管理对话上下文处理中间结果intermediate与最终结果final保证交互流畅生成实时字幕caption兼顾无障碍与日志记录。在 doodler 示例应用面向儿童的语音绘图应用中main_python正是把agora_rtc语音输入、openai_asr_pythonWhisper 转写、openai_llm2_pythonGPT-4o-mini 理解意图、openai_gpt_image_python绘图工具与message_collector聊天记录串成完整工作流的粘合剂。功能特性按照 README该扩展提供以下核心能力实时语音处理Real-time Speech Processing接收并处理 ASR 结果管理流式文本区分中间结果与最终结果LLM 集成LLM Integration协调语言模型完成自然语言理解与响应生成TTS 协调TTS Coordination管理文本转语音请求驱动音频输出会话管理Session Management跟踪用户上下线presence维护会话与轮次状态流式支持Streaming Support同时处理 final 与 intermediate 结果保障体验平滑字幕生成Caption Generation为 accessibility 与日志提供实时字幕。API 接口输入、输出与命令输入数据Input DataASR 结果语音识别模块通过名为asr_result的 Data 帧上报识别结果其 JSON 结构为{ text: string, final: bool, metadata: { session_id: string } }字段说明text为识别出的文本final标识是否为最终结果false表示中间结果metadata.session_id用于标识来源会话。在 agent.py 的on_data中扩展会读取该 Data 的名称若为asr_result则解析 JSON 并封装为ASRResultEvent投入事件队列。LLM 结果语言模型以流式方式返回响应其数据结构为{ text: string, end_of_segment: bool }输出数据Output Data文本数据Text Data主控扩展向字幕/消息收集器输出的结构化文本包含{ text: string, is_final: bool, end_of_segment: bool, stream_id: uint32 }其中stream_id由会话 ID 转换而来源码中stream_id int(self.session_id)用于把多条字幕流关联到同一个会话。命令Commands输入命令上游如 RTC 扩展可通过 Cmd 通知用户状态变化on_user_joined用户加入会话时触发on_user_left用户离开会话时触发。此外源码中还支持tool_register命令用于注册 LLM 工具详见下文工具注册小节。输出命令主控扩展对外发送的典型命令为flush用于向 LLM、TTS 和 RTC 组件下发冲刷/打断信号终止正在进行的生成。配置greeting 参数扩展支持通过运行时属性property进行配置README 给出的配置示例为{ greeting: Hello there, Im TEN Agent }配置参数表参数类型默认值说明greetingstring见下方说明第一位用户加入时展示/播报的问候语需要说明的是README 示例中的默认值为Hello there, Im TEN Agent而仓库内 config.py 中MainControlConfig的实际默认值是Hello, I am your AI assistant.。greeting通过 Pydantic 的BaseModel定义在 extension.py 的on_init中通过ten_env.get_property_to_json(None)读取运行时属性并调用MainControlConfig.model_validate_json()完成校验与装载。同时在 manifest.json 的api.property.properties中声明了greeting的 JSON Schema 类型为string供 TEN 框架校验。源码验证当第一位用户加入且配置了问候语时_on_user_joined会同时向 TTS 发送问候语音_send_to_tts并向 message_collector 发送assistant角色的字幕_send_transcript实现开口即欢迎。依赖README 声明扩展依赖两个 TEN 系统包ten_runtime_pythonTEN Framework 核心运行时README 标注 0.10当前 manifest.json 实际声明为 0.11ten_ai_baseAI 基础能力库提供LLMToolMetadata、LLMRequest/LLMResponse等结构README 标注 0.6.9manifest 实际声明为 0.7。依赖声明方式在扩展的manifest.json的dependencies数组中以system类型声明安装时由 TEN 包管理器自动解析。安装与集成安装该扩展随 TEN Framework 分发布可通过 TEN 包管理器安装ten install main_python在 doodler 示例中扩展位于 ten_packages/extension/main_python其中addon.py通过register_addon_as_extension(main_python)完成 Addon 注册on_create_instance负责实例化MainControlExtension。集成组件该扩展被设计为与以下 TEN 组件协同工作ASR 扩展提供语音识别结果LLM 扩展处理自然语言并生成响应TTS 扩展将文本转为语音RTC 扩展处理实时通信含用户上下线通知与打断Message Collector消息收集器捕获并展示会话数据字幕、推理过程等。在 doodler 的图配置tenapp/property.json中这些组件通过有向连接与main_python组成 Agent 图。工作流一次完整对话的五个阶段README 将一次典型交互拆解为 5 步用户加入User Joins用户上线触发on_user_joined若配置了问候语则先送出欢迎语语音处理Speech ProcessingASR 结果到达后被处理并生成字幕LLM 处理LLM Processing最终语音段finaltrue被送入 LLM 处理响应生成Response GenerationLLM 响应被转为语音并作为字幕展示流式输出Streaming中间与最终结果均被妥善处理保证交互平滑。源码级数据流佐证结合 extension.py 的事件处理器上述流程的底层实现如下ASR 结果处理_on_asr_result更新session_id与stream_id当finaltrue或文本长度大于 2 时先调用_interrupt()打断旧输出finaltrue时turn_id 1并将文本通过agent.queue_llm_input()送入 LLM随后无论中间还是最终结果都会调用_send_transcript(user, ...)发送用户字幕。打断机制_interrupt清空句子碎片调用agent.flush_llm()冲刷 LLM 队列并取消进行中的任务同时向tts发送tts_flushData、向agora_rtc发送flushCmd——这是实现用户一开口就立刻打断机器说话的关键。LLM 响应处理_on_llm_response中间message结果累积到sentence_fragment最终结果时通过_select_tts_text提取首个完整句子借助helper.parse_sentences按中英文标点切句无有效内容时回退为默认提示语Got it. Drawing now!并保证每轮只发送一次 TTS通过_tts_sent_turn_id与turn_id比对推理过程reasoning类型则以data_typeraw的 JSON 形式发送给 message_collector。字幕发送_send_transcript统一构造messageData 发往message_collector携带data_type、role、text、text_ts、is_final、stream_id等字段。架构事件驱动的 Agent 内核README 指出该扩展实现了AsyncExtension接口提供生命周期管理、事件处理、状态管理与数据路由能力。从源码看其内核是一个轻量级事件总线 双异步队列的 Agent 框架1. 事件模型agent/events.py所有事件继承自 Pydantic 的AgentEventBase分为 Cmd 类与 Data 类UserJoinedEvent/UserLeftEventCmd 类用户上下线ToolRegisterEventCmd 类携带LLMToolMetadata与来源扩展名用于注册 LLM 工具ASRResultEventData 类携带text、final、metadataLLMResponseEventData 类携带delta、text、is_final并用type区分普通消息message与推理过程reasoning。统一类型AgentEvent是上述五者的 Union作为事件分发与类型匹配的依据。2. 事件注册与分发agent/agent.pyAgent类维护一个_callbacks注册表支持agent.on(EventType, handler)与agent.on(EventType)两种注册方式。extension.py在on_init中通过扫描实例方法上的_agent_event_handler装饰器元数据完成自动注册。_dispatch按事件类型匹配isinstance并串行执行所有处理器单处理器异常仅记录日志而不中断整体分发。3. 双队列消费者ASR / LLM 分离Agent内置_asr_queue与_llm_queue两个asyncio.Queue并各启动一个消费者任务。LLM 消费端特别设计为可取消_consume_llm将分发逻辑包装为asyncio.create_task以便flush_llm()在打断时能取消进行中的 LLM 处理任务并清空队列——这是实现低延迟打断的并发基础。4. LLM 执行器agent/llm_exec.pyLLMExec是 LLM 交互的具体执行者输入队列queue_input()将用户文本入队_process_input_queue循环消费并构造LLMMessageContent(roleuser, ...)流式请求通过_send_cmd_ex向llm扩展发送chat_completionCmdstreamingTrue模型名传空字符串表示使用 LLM 扩展默认模型temperature0.7并携带toolsself.available_tools响应分发_handle_llm_response用match语句分派LLMResponseMessageDelta增量文本、LLMResponseMessageDone结束、LLMResponseReasoningDelta/Done推理流与LLMResponseToolCall工具调用上下文管理_queue_context/_write_context维护contexts消息列表连续同角色消息自动合并工具调用LLMResponseToolCall触发时根据tool_registry找到注册该工具的扩展向其发送tool_callCmd成功后把function_call与function_call_output写回上下文并继续请求 LLM形成工具增强闭环。5. 图内通信工具helper.py_send_cmd/_send_data是图内便捷通信函数通过Loc(, , dest)指定目标扩展名即可在无需显式连线的情况下向图内其他扩展发送 Cmd 或 Data——这正体现了主控扩展假设目标扩展已存在于图中的编排式设计源码注释明确提示此类写法只适用于特定图通用扩展应避免使用。开发构建与测试构建该扩展使用 TEN Framework 标准构建系统ten build main_python测试运行扩展测试ten test main_python从 manifest.json 的package.include可见发布包会包含manifest.json、property.json、**.tent、**.py、README.md与tests/**测试目录被显式纳入打包范围。生命周期与状态管理小结扩展完整实现了AsyncExtension生命周期钩子on_init加载配置MainControlConfig、创建Agent、自动注册事件处理器on_start记录启动日志on_stop置stopped标志、调用agent.stop()内部依次停止 LLMExec、冲刷 LLM 队列并取消 ASR/LLM 消费者任务on_cmd/on_data把框架层的 Cmd/Data 透传给Agent由Agent转换为领域事件。状态管理方面扩展用_rtc_user_count跟踪在线用户数首个用户上线才触发问候、turn_id标记对话轮次、session_id标识会话、_tts_sent_turn_id防止重复播报——这些字段共同构成了多用户场景下会话编排的状态基础。许可证该扩展属于 TEN Framework 的一部分遵循 Apache License 2.0 开源协议发布如需贡献请参阅 TEN Framework 主仓库的贡献指南AGENTS.md 与 CLAUDE.md。【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址: https://gitcode.com/TEN-framework/ten-framework创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考