TEN Framework main_python 扩展深度解析：Plivo 电话语音助手的核心编排引擎

人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载在 TEN Framework 的语音助手示例voice-assistant-sip-plivo中main_python扩展扮演着总控大脑的角色它接收来自 ASR 的语音识别结果协调 LLM 生成回复驱动 TTS 合成语音并通过内嵌的 HTTP/WebSocket 服务与 Plivo 电话平台完成双向音频流的收发。本文以该扩展的 README 为骨架结合其源码实现extension.py、agent/agent.py、server.py 等深入讲解其 API 契约、配置体系、事件驱动架构与音频处理链路帮助读者掌握如何在 TEN Framework 中构建面向 PSTN 电话场景的实时语音对话 Agent。扩展定位AI Agent 对话的总控编排器main_python是一个基于 TEN FrameworkAsyncExtension接口实现的 Python 扩展其核心职责是充当 AI Agent 对话的编排器orchestrator把实时语音处理ASR、大语言模型交互LLM与语音合成输出TTS串联成一条完整的通话对话流水线。从源码类注释可以清晰看到它的定位The entry point of the agent module. Consumes semantic AgentEvents from the Agent class and drives the runtime behavior.即MainControlExtension是 Agent 模块的入口它消费来自Agent类的语义化事件AgentEvent并驱动整个运行时行为。同时它还负责管理用户会话状态session state跟踪用户在场与退出在同一个进程内启动 Plivo 呼叫服务器HTTP API WebSocket 媒体流完成 μ-law 与 PCM 音频格式的互转以及 16 kHz / 8 kHz 采样率的双向转换把 ASR 结果和 LLM 输出以字幕caption形式转发给消息收集器message_collector用于实时展示与日志。功能特性总览原文档列举了该扩展的六项核心能力结合源码可以逐一对应到具体实现特性说明源码依据实时语音处理处理 ASR 结果管理流式文本_on_asr_result处理器见 extension.pyLLM 集成协调语言模型完成理解与回复生成LLMExec执行chat_completion命令见 agent/llm_exec.pyTTS 协调管理文本转语音请求_send_to_tts发送tts_text_input数据见 extension.py会话管理跟踪用户在场与对话状态UserJoinedEvent/UserLeftEvent见 agent/events.py流式支持同时处理中间结果与最终结果final/is_final标志贯穿 ASR、LLM、TTS 全链路字幕生成实时字幕用于可访问性与日志_send_transcript转发message数据见 extension.py音频采样率转换下行 16000 Hz → 8000 Hz上行 8000 Hz → 16000 Hz_downsample_audio与_forward_audio_to_ten见 extension.py其中音频采样率转换是面向电话PSTN场景的关键适配TTS 生成的音频为 16000 Hz而 Plivo 媒体流要求 8000 Hz μ-law 编码README 中标注为 for Twilio compatibility从当前仓库源码看实际目标平台为 Plivosend_audio_to_plivo中明确注释target_rate 8000 # Plivo required sample rate反方向上Plivo 上传的 8000 Hz μ-law 音频需解码为 16-bit PCM 并按 8000 Hz 标注后送入 TEN 图graph由下游 ASR 扩展消费。API 接口契约输入数据Input Data扩展通过on_data接收名称为asr_result的数据见 agent/agent.py载荷结构与 README 定义一致{ text: string, final: bool, metadata: { session_id: string } }text识别出的文本内容final是否为最终结果false表示中间结果/部分识别metadata.session_id会话标识扩展用它生成stream_idint(self.session_id)并用于后续 TTS 请求的元数据见 extension.py。LLM 结果是流式到达的由LLMExec通过回调转为内部事件其增量载荷对应{ text: string, end_of_segment: bool }在实现中对应LLMResponseEvent的delta增量文本、text累计文本与is_final是否结束字段见 agent/events.py。输出数据Output Data扩展向图中其他扩展发送的文本数据例如发给message_collector的字幕或发给tts的tts_text_input遵循如下结构{ text: string, is_final: bool, end_of_segment: bool, stream_id: uint32 }命令Commands输入命令由Agent.on_cmd解析处理见 agent/agent.pyon_user_joined用户加入会话时触发转换为UserJoinedEventon_user_left用户离开会话时触发转换为UserLeftEvent此外还支持tool_register将外部扩展注册的 LLM 工具元数据LLMToolMetadata转换为ToolRegisterEvent再调用register_llm_tool注入 LLM 执行器。输出命令flush向 LLM、TTS 与 RTCagora_rtc组件发送冲刷指令。源码中_interrupt方法展示了完整的打断链路清空句子残片 →agent.flush_llm()→ 发送tts_flush数据 → 发送flush命令给agora_rtc见 extension.py。配置详解README 仅列出一个配置项但结合 config.py 与 manifest.json该扩展实际支持 8 个配置属性。扩展在on_init中通过ten_env.get_property_to_json(None)读取全部属性并用 Pydantic 模型MainControlConfig.model_validate_json完成校验见 extension.py。配置参数类型默认值说明greetingstringHello there, Im TEN AgentREADMEconfig.py中实际默认Hello, I am your AI assistant.首位用户加入或 WebSocket 建立时播放的问候语plivo_auth_idstringPlivo 账户 Auth IDplivo_auth_tokenstringPlivo 账户 Auth Tokenplivo_from_numberstring发起外呼所使用的 Plivo 电话号码plivo_server_portint329000内嵌服务器端口同时承载 HTTP API 与 WebSocket 媒体流plivo_public_server_urlstring公网可达的服务器地址不含协议如your-domain.com:9000用于 Plivo 回推 webhook 与建立媒体流连接plivo_use_httpsbooltrueconfig.pyproperty.json中为falsewebhook 是否使用 HTTPSplivo_use_wssbooltrueconfig.pyproperty.json中为false媒体流是否使用 WSS扩展包内的 property.json 展示了属性如何与环境变量绑定TEN Framework 的${env:XXX}语法{ greeting: Hello, I am your AI assistant., plivo_auth_id: ${env:PLIVO_AUTH_ID}, plivo_auth_token: ${env:PLIVO_AUTH_TOKEN}, plivo_from_number: ${env:PLIVO_FROM_NUMBER}, plivo_server_port: 9000, plivo_public_server_url: ${env:PLIVO_PUBLIC_SERVER_URL}, plivo_use_https: false, plivo_use_wss: false }这些属性的类型声明也同步登记在扩展 manifest.json 的api.property.properties中string/int32/bool供 TMAN 等工具进行 schema 校验。在示例应用的图配置中见 voice-assistant-sip-plivo 的 READMEmain_control节点通过property段将plivo_*环境变量注入扩展。值得注意plivo_use_https/plivo_use_wss与 ngrok 本地开发存在联动——server.py 中use_ssl为 True 时仍以 HTTP 启动 uvicorn注释明确说明 ngrok will handle SSL termination。依赖关系README 声明扩展依赖ten_runtime_python0.10TEN Framework 核心运行时ten_ai_base0.6.9AI 基础能力LLM 消息结构、工具元数据、AsyncQueue等。需要说明的是当前仓库中 manifest.json 记录的实际依赖版本为ten_runtime_python 0.11与ten_ai_base 0.7以仓库实际内容为准。ten_ai_base提供了LLMToolMetadata、LLMRequest/LLMResponse等类型以及CMD_PROPERTY_RESULT、AsyncQueue等基础设施LLMExec与Agent均直接依赖它们见 agent/llm_exec.py。安装与集成README 给出的安装命令为ten install main_python构建与测试ten build main_python ten test main_python作为示例应用的一部分该扩展也可以随整个voice-assistant-sip-plivo应用安装运行在ai_agents/agents/examples/voice-assistant-sip-plivo目录下执行task install与task run详见 voice-assistant-sip-plivo README。该扩展被设计为与以下 TEN Framework 组件协作ASR 扩展如deepgram_asr_python提供语音识别结果asr_result数据LLM 扩展如openai_llm2_python处理自然语言并生成流式回复chat_completion命令TTS 扩展如elevenlabs_tts2_python将文本转为语音tts_text_input数据、tts_flush数据RTC 扩展接收flush命令用于通话中断言时的音频冲刷Message Collector接收message数据展示对话记录role、文本、时间戳、is_final、stream_id。扩展借助 helper.py 中的_send_cmd、_send_cmd_ex、_send_data便捷函数通过Loc(, , dest)按扩展名定位目标并直接发送命令/数据无需显式声明连接——正如其注释所强调这种方式仅适用于本图graph内已存在目标扩展的场景。核心工作流程README 定义了五步工作流结合源码可以还原每个步骤的底层实现用户加入User Joins当 Plivo 媒体流 WebSocket 建立后server.py的 WebSocket 端点收到start事件并解析出call_uuid随后回调extension_instance.on_websocket_connected(call_uuid)见 server.py。扩展随即把配置的greeting文本发给 TTS 合成并播放见 extension.py。语音处理Speech ProcessingPlivo 上传 μ-law 音频帧 →_forward_audio_to_ten将 base64 解码、audioop.ulaw2lin转成 16-bit PCM封装为名为pcm_frame的AudioFrame8000 Hz、单声道、2 字节/样本、INTERLEAVE 格式并定向发送给streamid_adapter扩展进入 TEN 图见 extension.py。ASR 结果到达后_on_asr_result依据final标志决定是否打断当前回复并送入 LLM。LLM 处理LLM Processingfinal结果到达时turn_id自增并通过agent.queue_llm_input(text)将文本投入LLMExec的输入队列队列消费者逐条构造LLMRequeststreamingTrue默认temperature0.7携带已注册工具执行chat_completion命令并流式解析LLMResponseMessageDelta/LLMResponseMessageDone/LLMResponseReasoningDelta/LLMResponseToolCall等响应类型见 agent/llm_exec.py。工具调用LLMResponseToolCall会被路由回注册该工具的扩展执行tool_call命令结果以function_call_output回灌 LLM 上下文。回复生成Response GenerationLLM 的流式增量经parse_sentences按中英文标点,.。?!切分成完整句子逐句发给 TTSis_finalFalse最终残片在is_finalTrue时以text_input_end收尾见 extension.py 与 helper.py。同时_send_transcript把 assistant 侧文本含reasoning类型的思维链输出转发给 message_collector。流式交互Streaming中间结果与最终结果全程区分处理保证用户在语音识别与 LLM 生成过程中获得低延迟、平滑的体验检测到用户新语音时通过_interrupt打断 LLM/TTS/RTC 的旧输出见 extension.py。事件驱动架构剖析main_python的核心设计是一套轻量级事件总线AgentEvent由 agent/agent.py 中的Agent类实现事件类型见 agent/events.pyUserJoinedEvent、UserLeftEvent、ToolRegisterEvent命令类ASRResultEvent、LLMResponseEvent数据类。注册机制MainControlExtension.on_init中扫描自身所有方法凡带有_agent_event_type标记由agent_event_handler装饰器写入见 agent/decorators.py的处理器都会自动注册到Agent.on(event_type, handler)。队列化处理ASR 与 LLM 事件分别进入独立的asyncio.Queue由后台消费者任务串行派发_consume_asr/_consume_llmLLM 消费任务以asyncio.create_task运行从而支持中途取消打断场景。生命周期Agent.stop()依次停止LLMExec、冲刷队列并取消消费者任务与扩展的on_stop形成完整清理链路见 extension.py。这一架构将框架事件Cmd/Data/AudioFrame与业务事件AgentEvent解耦MainControlExtension只负责框架层收发与音频转发而对话策略全部收敛在事件处理器中。内嵌 Plivo 呼叫服务器扩展在on_init阶段就于同进程内启动PlivoCallServer基于 FastAPI uvicorn见 server.py一个端口同时提供REST APIPOST /api/call创建外呼需plivo_public_server_url拼装 answer/status webhook 地址、GET /api/calls、GET /api/call/{call_uuid}、DELETE /api/call/{call_uuid}、GET /health、GET /api/configPlivo webhook/webhook/answer返回含Stream bidirectionaltrue的 Plivo XML指向wss://public_url/media、/webhook/status媒体流 WebSocket/media端点接收 Plivo 的start/media/stop事件维护active_call_sessions以call_uuid为键记录stream_id与 WebSocket 连接并把上行音频交给扩展实例转发进 TEN 图。下行方向TEN 图产生的pcm_frame音频帧在on_audio_frame中被广播给所有活动通话先由_downsample_audio将 16000 Hz 降采样到 8000 Hz16k→8k 采用简单抽取每 4 字节取前 2 字节其他比例则用audioop.ratecv再经audioop.lin2ulaw转为 μ-law 并 base64 编码最后以{event: playAudio, media: {contentType: audio/x-mulaw;rate8000, payload: ...}}消息发送见 extension.py。开发、许可与贡献该扩展遵循 TEN Framework 标准构建系统GN可通过ten build main_python构建、ten test main_python运行测试。代码中所有文件均带有 Apache License, Version 2.0 头注释与仓库根目录 LICENSE 一致。贡献者请参照 TEN Framework 主仓库的贡献指南见仓库根目录 AGENTS.md 与 CLAUDE.md。小结main_python是 TEN Framework 电话语音助手的核心控制扩展向外它通过内嵌 FastAPI 服务器与 Plivo 完成呼叫、webhook 与媒体流对接向内它以 AgentEvent 事件总线串联 ASR → LLM → TTS并以stream_id/session_id/turn_id维系多轮会话状态。理解该扩展的 API 契约、配置体系与事件驱动实现是二次开发面向 PSTN 场景的 TEN Agent例如替换 STT/LLM/TTS 供应商、增加自定义 LLM 工具、调整打断策略的最佳切入点。赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐TEN Framework 主控扩展 main_python 源码深度解析AI Agent 会话编排的核心引擎TEN Framework 主控扩展 main_python 源码深度解析AI Agent 会话编排的核心引擎 导读 main_python 是 TEN Fr人工智能AI Agent多模态语音AI 应用TEN Framework main_python 主控扩展深度解析语音 AI 智能体的中央编排引擎TEN Framework main_python 主控扩展深度解析语音 AI 智能体的中央编排引擎 main_python 是 TEN Framework人工智能AI Agent多模态语音AI 应用TEN Framework main_python 扩展解析语音 AI Agent 的中央编排与控制核心TEN Framework main_python 扩展解析语音 AI Agent 的中央编排与控制核心 导读 main_python 是 TEN Frame人工智能AI Agent多模态语音AI 应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考