TEN Agent 集成 Coze 大模型：coze_llm2_python 扩展源码解析与实战接入指南

TEN Agent 集成 Coze 大模型coze_llm2_python 扩展源码解析与实战接入指南【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址: https://gitcode.com/TEN-framework/ten-framework导读coze_llm2_python是 TEN AgentTEN-framework中用于对接 Coze扣子Bot 服务的 Python LLM 扩展它将 Coze 的/v3/chat流式对话接口封装为 TEN 标准的 LLM2 扩展接口让开发者可以在语音 Agent 的图graph中像使用其他 LLM 一样直接挂载 Coze Bot。本文以 coze_llm2_python/README.md 为主体结合包内源码、清单与演示应用配置讲解该扩展的配置参数、消息流、流式解析原理、错误处理以及如何在真实 TEN Agent 应用中完成接入。一、扩展概览Coze 服务如何接入 TEN该扩展是 Coze 服务Coze / Coze China / 自建 Coze 兼容端点的 Python 实现其定位与openai_llm2_python、dify_llm2_python、anthropic_llm2_python等同类扩展一致统一实现AsyncLLM2BaseExtensionten_ai_base提供的 LLM2 基类从而在 TEN 的消息图上以标准 LLM 节点身份工作。README 中该包的自述标题仍是coze_python_async而包的实际名称已演进为coze_llm2_python见 manifest.json 中的name: coze_llm2_python版本0.2.1阅读时需要注意这一命名差异。1.1 包结构一览文件作用manifest.json扩展声明依赖ten_runtime_python 0.11与ten_ai_base 0.7导入 LLM2 接口定义声明属性 Schemaproperty.json默认配置支持${env:XXX}环境变量注入addon.pyAddon 入口注册coze_llm2_python扩展并创建实例extension.py扩展主体生命周期管理、配置加载、LLM2 回调实现coze.pyCoze 客户端aiohttp 会话、SSE 流式解析、错误处理requirements.txt / pyproject.toml依赖声明cozepy0.6.2Python 版本要求3.101.2 核心能力流式对话将 TEN 的LLMRequest映射为 Coze/v3/chat的stream: true请求并把 Coze 的 SSE 事件流反向翻译为 TEN 的LLMResponseMessageDelta/LLMResponseMessageDone流式响应。多轮历史通过additional_messages字段把请求中的历史消息回传给 CozeREADME 中描述为按max_history数量记录历史当前实现的开关是auto_save_history见下文配置项差异说明。Bearer 认证使用Authorization: Bearer token请求头完成默认鉴权。flush 支持README 明确说明扩展支持 flush 信号——收到 flush 后关闭当前存在的 HTTP 会话对应CozeChatClient.aclose()中的aiohttp.ClientSession.close()用于打断或重置连接。二、配置参数详解从 manifest 到运行时2.1 属性 Schemamanifest.jsonmanifest.json 在api.property.properties中声明了 4 个字符串属性这是 TEN 框架校验扩展配置的依据property: { properties: { base_url: { type: string }, bot_id: { type: string }, token: { type: string }, user_id: { type: string } } }同时该扩展通过import_uri: ../../system/ten_ai_base/api/llm-interface.json导入ten_ai_base系统包的 LLM2 接口定义表明它对外暴露的是标准 LLM 消息接口该接口文件属于 tman 安装的系统包不随本仓库源码分发。2.2 默认配置property.jsonproperty.json 给出的默认值为{ token: ${env:COZE_TOKEN}, bot_id: ${env:COZE_BOT_ID}, base_url: https://api.coze.com }可见token与bot_id采用${env:COZE_TOKEN}、${env:COZE_BOT_ID}形式从环境变量注入base_url固定指向国际版 Coze 端点https://api.coze.com。需要对接国内版https://api.coze.cn或自建兼容端点时只需在应用配置中覆盖base_url即可。2.3 运行时配置结构coze.pycoze.py 中CozeLLM2ConfigPydantic 模型定义了扩展实际解析的全部字段与默认值dataclass class CozeLLM2Config(BaseModel): base_url: str https://api.acoze.com bot_id: str token: str user_id: str TenAgent connect_timeout_s: float 15.0 total_timeout_s: float 90.0 auto_save_history: bool True各字段含义字段类型默认值说明base_urlstrhttps://api.acoze.comCoze 服务地址最终请求 URL 为{base_url}/v3/chatbot_idstrCoze Bot 的 ID必填项tokenstrCoze API Token用于Bearer鉴权必填项user_idstrTenAgent传给 Coze 的用户标识Coze 侧用于会话隔离与数据统计connect_timeout_sfloat15.0aiohttp 连接超时秒total_timeout_sfloat90.0aiohttp 整体请求超时秒auto_save_historyboolTrue是否让 Coze 自动保存会话历史配置项差异说明README 中提到的必填项写作api_url而当前 manifest 与源码中的实际属性名为base_urlREADME 提到的历史条数参数max_history在实现中对应为auto_save_history布尔开关。以源码与 manifest 为准配置base_url、bot_id、token即可运行user_id与超时参数均有合理默认值。2.4 配置加载与校验extension.pyextension.py 在on_start中一次性读取扩展的全部 property 并校验async def on_start(self, async_ten_env: AsyncTenEnv) - None: async_ten_env.log_info(on_start) await super().on_start(async_ten_env) cfg_json, _ await self.ten_env.get_property_to_json() self.config CozeLLM2Config.model_validate_json(cfg_json) if not self.config.bot_id or not self.config.token: async_ten_env.log_info(Missing bot_id or token, exiting on_start) return try: self.client CozeChatClient(async_ten_env, self.config) ...关键点get_property_to_json()拉取扩展的完整 JSON 配置再交给 Pydantic 校验bot_id或token缺失时只是记录日志并提前退出on_start不会抛出异常导致整个应用崩溃。这也呼应了 README 中 token(must have) 的说明——实际表现为缺失则扩展不初始化客户端。三、消息流与 LLM2 接口README 的 API 章节给出了扩展的输入输出契约Intext_data[data]ASR语音识别结果文本作为用户消息进入 LLMflush[cmd]flush 信号用于打断当前会话/关闭 HTTP 连接。Outflush[cmd]flush 信号向下游如 TTS传播打断指令。运行时层面由于实现了AsyncLLM2BaseExtension扩展内部实际消费的是LLMRequest含messages列表产出的是LLMResponseMessageDelta增量与LLMResponseMessageDone结束两类流式响应。on_retrieve_prompt在 extension.py 中被实现为返回空字符串并注释说明 Coze doesnt use system prompts——Coze 的系统提示词在 Bot 控制台配置不走 TEN 的 prompt 检索链路。四、核心实现原理CozeChatClient 源码级拆解4.1 HTTP 会话与认证CozeChatClient使用aiohttp.ClientSession管理连接会话在首次请求时惰性创建并应用connect_timeout_s默认 15s与total_timeout_s默认 90s两个超时timeout aiohttp.ClientTimeout( connectself.config.connect_timeout_s, totalself.config.total_timeout_s, ) self._session aiohttp.ClientSession(timeouttimeout)每个请求都携带Authorization: Bearer {token}对应 README 的 use Bearer token to support default auth。aclose()负责关闭会话并置空引用供on_stop与 flush 场景调用。4.2 消息映射LLMRequest → Coze additional_messages_build_additional_messages将 TEN 的LLMRequest.messages映射为 Coze 的additional_messages简单文本消息中user角色转换为Message.build_user_question_text(content)assistant角色转换为Message.build_assistant_answer(content)多模态的 list 内容如音视频分段则退化为拼接其中的text字段作为纯文本消息无法提取文本的分段会被跳过。4.3 请求体与流式解析核心请求在get_chat_completions中构造并 POST 到{base_url}/v3/chatpayload { bot_id: self.config.bot_id, user_id: self.config.user_id, additional_messages: additional_messages, stream: True, auto_save_history: self.config.auto_save_history, }响应采用 SSEServer-Sent Events逐行读取解析逻辑位于 coze.pyevent:行记录当前事件类型遇到done直接终止读取data:行是 JSON 载荷交由_event_to_chatevent通过cozepy的ChatEvent/Message/Chat模型解析CONVERSATION_MESSAGE_DELTA事件提取message.content增量累加到full_content后以LLMResponseMessageDelta产出content为累计全文、delta为本次增量CONVERSATION_MESSAGE_COMPLETED为无操作事件流结束后统一发出LLMResponseMessageDone作为终止消息非 SSE 格式的 JSON 响应视为错误信封code 4000表示 Coze bot is not publishedBot 未发布。4.4 错误处理可操作的失败提示扩展对两类高频错误给出了明确提示CONVERSATION_CHAT_FAILED事件中last_error.code 4011时抛出RuntimeError(The Coze token has been depleted. Please check your token usage.)——Token 额度耗尽错误信封code 4000时抛出RuntimeError(Coze bot is not published.)——Bot 未发布需要先在 Coze 控制台发布。这两条信息在实际排障中非常有用前者提示检查/续费 Token后者提示回 Coze 控制台完成发布流程。五、实战接入在 TEN Agent 应用中挂载 Coze LLM仓库自带的演示应用demo已包含一个完整的 Coze 语音 Agent 图va_coze_azure可直接作为接入模板见 demo/tenapp/property.json。5.1 声明依赖应用 manifest.json 通过本地路径声明依赖{ path: ../../../ten_packages/extension/coze_llm2_python }5.2 图中配置 LLM 节点在va_coze_azure图中LLM 节点配置如下节选{ type: extension, name: llm, addon: coze_llm2_python, extension_group: chatgpt, property: { token: ${env:COZE_TOKEN}, bot_id: ${env:COZE_BOT_ID}, base_url: https://api.coze.com } }该图同时串联了 RTC 音频输入agora_rtc、ASRazure_asr_python将识别文本送入llm节点即 README 中的text_data输入与 TTSazure_tts_python构成完整的语音输入 → 识别 → Coze Bot 对话 → 语音合成链路。接入步骤归纳在 Coze 平台创建并发布Bot取得BOT_ID生成 API Token 作为TOKEN在应用 property 中为llm节点指定addon: coze_llm2_python并设置token/bot_id/base_url默认https://api.coze.com国内版改https://api.coze.cn在启动环境导出环境变量export COZE_TOKEN... export COZE_BOT_ID...运行应用将 ASR 节点的输出连接到llm节点输入。5.3 运行 README 中的示例包装服务README 附带了一个 OpenAI 兼容包装服务的示例说明对应examples/openai_wrapper.py用于把 Coze 以 OpenAI 风格接口暴露给外部调用方默认监听 8000 端口export API_TOKENxxx export OPENAI_API_KEYxxx python3 openai_wrapper.py启动后预期输出INFO: Started server process [162886] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRLC to quit)说明README 引用的schema.yml与examples/openai_wrapper.py属于文档描述的附件当前仓库快照中未随包分发示例命令与端口信息以 README 为准。API_TOKEN对应 Coze TokenOPENAI_API_KEY对应包装层向调用方暴露的密钥。六、生命周期与资源管理扩展完整实现了 TEN 扩展的生命周期回调extension.py回调行为on_init记录日志调用基类初始化on_start加载配置、校验bot_id/token、创建CozeChatClienton_stop调用client.aclose()关闭 aiohttp 会话再执行基类收尾on_deinit记录日志调用基类反初始化会话的生命周期集中在CozeChatClient上_ensure_session()在会话为空或已关闭时按配置重建aclose()关闭并置空会话。这正是 README 所述 The extension support flush that will close the existing http session 的落地实现——flush 语义通过关闭底层 HTTP 会话实现连接中断后续请求会由_ensure_session自动重建新会话。七、常见问题排查清单现象可能原因处理方式启动日志出现Missing bot_id or token, exiting on_start未配置token/bot_id或环境变量未注入检查${env:COZE_TOKEN}/${env:COZE_BOT_ID}是否导出或直接在 property 中写入明文值报错The Coze token has been depletedToken 额度耗尽Coze 错误码 4011检查 Coze 控制台 Token 用量并续费/更换 Token报错Coze bot is not publishedBot 未发布错误码 4000到 Coze 控制台完成 Bot 发布报错chat failed且 HTTP 状态非 200base_url指向错误、Token 无效或网络不可达核对base_url国际api.coze.com/ 国内api.coze.cn、Token 有效性并检查connect_timeout_s/total_timeout_s是否过短长时间无响应后超时默认整体超时 90s 触发按需调大total_timeout_s结语coze_llm2_python是一个小而完整的 LLM2 扩展范本通过 manifest 声明接口、property 提供默认值、Pydantic 承载配置、aiohttp 承载流式传输、cozepy承载事件模型最终以标准LLMResponseMessageDelta/LLMResponseMessageDone融入 TEN 的图执行体系。读者既可以直接在语音 Agent 应用中挂载 Coze Bot也可以对照 extension.py 与 coze.py 的代码理解外部 LLM 服务如何接入 TEN的完整模式并迁移到其他服务OpenAI、Anthropic、Dify 等的同类扩展实现中。【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址: https://gitcode.com/TEN-framework/ten-framework创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考