人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载本文围绕 TEN Framework 仓库内的 dingtalk_bot_tool_python 扩展 展开讲解如何将钉钉DingTalk群机器人封装为可被 LLM 调用的工具扩展让语音/文本 AI Agent 在对话中自动触发钉钉群消息通知。读完本文你将掌握该扩展的完整配置流程、在voice-assistant示例中的三步集成方法以及其底层基于 HMAC-SHA256 加签与异步工具注册的实现原理。扩展概述dingtalk_bot_tool_python是一个面向 TEN Framework 的 Python 扩展核心能力是让 AI Agent 通过钉钉群自定义机器人 Webhook 向群聊推送文本消息。它不是一个独立的 HTTP 服务而是以LLM 可调用工具LLM Tool的身份注册进 Agent 的工具列表——当用户对话中出现需要通知团队成员的场景时LLM 会自动决策并调用该工具完成消息发送。该扩展的特性包括LLM 工具集成作为 LLM-callable tool支持智能消息发送消息推送向钉钉群聊发送文本消息msgtype: text安全认证支持钉钉机器人的access_token与加签HMAC-SHA256双重校验异步处理基于AsyncLLMToolBaseExtension异步架构非阻塞操作详细日志完整日志输出便于调试与监控。系统要求根据扩展的 manifest.json 与 README运行该扩展需要满足依赖版本要求说明Python 3.8扩展运行语言环境TEN Runtime Python 0.11扩展运行依赖的 TEN 运行时manifest 中声明为ten_runtime_python0.11TEN AI Base 0.7LLM 工具基类与类型定义ten_ai_base0.7钉钉群机器人有效的 Webhook需要已在钉钉群中添加自定义机器人扩展对外部 Python 依赖非常轻量requirements.txt 中仅有requestsrequests用于向钉钉开放平台 API 发送 HTTP POST 请求。安装依赖pip install -r requirements.txt配置扩展获取钉钉机器人凭证在开始配置前需要先完成钉钉侧的准备在钉钉群中添加一个自定义机器人选择「自定义」机器人类型配置安全设置官方建议同时启用「自定义关键词」和「加签」两种方式本扩展原生支持其中的加签校验从机器人 Webhook 地址中提取access_token即https://oapi.dingtalk.com/robot/send?access_tokenxxx中的xxx部分若启用了加签还需获取机器人的secret密钥。配置文件设置编辑扩展包内的 property.json{ access_token: your_dingtalk_access_token_here, secret: your_dingtalk_secret_here }扩展在启动时通过DingTalkBotConfig.create_async(ten_envten_env)加载该配置字段定义位于 extension.pydataclass class DingTalkBotConfig(BaseConfig): Configuration for DingTalk Bot extension access_token: str secret: str 安全提示⚠️ 不要将包含真实凭证的property.json提交到版本控制系统建议使用环境变量或密钥管理服务存储敏感信息。仓库示例中其他扩展普遍采用${env:VAR_NAME}语法注入环境变量如voice-assistant的property.json中api_key: ${env:WEATHERAPI_API_KEY|}可参照该模式管理钉钉凭证。环境变量可选README 提供了环境变量方式作为备选配置入口export DINGTALK_ACCESS_TOKENyour_access_token export DINGTALK_SECRETyour_secret在 voice-assistant 示例中集成钉钉扩展仓库中的 voice-assistant 示例 是一个完整的语音 Agent 应用其main_controlmain_python扩展负责接收各工具扩展通过tool_register命令注册的 LLM 工具。以下三步完成钉钉扩展的接入。说明本文所有路径均以仓库根目录为基准示例应用的实际配置文件位于 ai_agents/agents/examples/voice-assistant/tenapp/manifest.json 与 ai_agents/agents/examples/voice-assistant/tenapp/property.json。步骤 1添加扩展依赖编辑manifest.json在dependencies数组中追加钉钉扩展的本地路径依赖{ dependencies: [ // ... 其他依赖 ... { path: ../../../ten_packages/extension/dingtalk_bot_tool_python } ] }参考位置当前示例的 manifest.json 中weatherapi_tool_python依赖位于约第 157 行可在同类扩展依赖之后添加。安装依赖后需运行task install使新依赖生效。步骤 2添加扩展节点编辑property.json在ten.predefined_graphs[].graph.nodes数组中添加钉钉扩展节点。参考现有工具扩展如weatherapi_tool_python节点位于 nodes 数组中的结构{ type: extension, name: dingtalk_bot_tool_python, addon: dingtalk_bot_tool_python, extension_group: default, property: { access_token: your_dingtalk_access_token_here, secret: your_dingtalk_secret_here } }关键字段说明字段取值说明typeextension节点类型namedingtalk_bot_tool_python节点实例名与 addon 保持一致addondingtalk_bot_tool_python对应 addon 注册名见 addon.py 中register_addon_as_extension(dingtalk_bot_tool_python)extension_groupdefault扩展组与同组工具扩展保持一致property.access_tokenstring必填钉钉机器人 access tokenproperty.secretstring必填钉钉机器人加签密钥步骤 3注册工具到主控制器在property.json的connections部分找到main_control的cmd配置在其tool_register命令的source数组中追加钉钉扩展。当前示例的tool_register连接结构如下weatherapi_tool_python已注册在此基础上追加即可{ extension: main_control, cmd: [ { names: [ tool_register ], source: [ { extension: weatherapi_tool_python }, { extension: dingtalk_bot_tool_python } ] } ] }完整配置示例关键片段将以上改动汇总到property.json的predefined_graphs中{ ten: { predefined_graphs: [ { name: voice_assistant, auto_start: true, graph: { nodes: [ // ... 其他节点agora_rtc, stt, llm, tts 等... // 添加钉钉扩展节点 { type: extension, name: dingtalk_bot_tool_python, addon: dingtalk_bot_tool_python, extension_group: default, property: { access_token: your_dingtalk_access_token_here, secret: your_dingtalk_secret_here } } ], connections: [ { extension: main_control, cmd: [ // 注册工具到主控制器 { names: [tool_register], source: [ {extension: weatherapi_tool_python}, {extension: dingtalk_bot_tool_python} ] } ] } // ... 其他连接配置 ... ] } } ] } }必须修改的文件汇总manifest.json添加扩展路径依赖../../../ten_packages/extension/dingtalk_bot_tool_pythonproperty.json两处修改nodes数组添加钉钉扩展节点配置connections中main_control的tool_registersource添加钉钉扩展。使用效果配置完成后当用户对 AI 助手说话并触发需要发送钉钉通知的场景时LLM 会自动调用钉钉扩展发送消息用户: 帮我通知团队今天下午3点开会 AI: 好的我已经向钉钉群发送了会议通知钉钉群内将收到今天下午3点开会验证配置启动 voice-assistant 应用查看日志确认钉钉扩展已加载并完成工具注册[DingTalkBotExtension] on_start BEGIN [DingTalkBotExtension] Config loaded successfully [DingTalkBotExtension] Tool registration result: ...与 AI 对话触发钉钉消息发送场景验证功能。源码级原理剖析扩展生命周期与工具注册扩展核心类DingTalkBotExtension继承自AsyncLLMToolBaseExtension来自ten_ai_base.llm_tool这是其成为 LLM 工具的关键。完整生命周期在 extension.py 中实现on_init记录初始化日志on_start加载配置 → 校验access_token/secret是否设置只打印长度不泄露明文→ 构造工具元数据 → 通过Cmd.create(tool_register)发送注册命令到main_controlon_stop/on_deinit记录停止与销毁日志。工具元数据定义了唯一的工具名与参数TOOL_NAME send_message TOOL_DESCRIPTION Send a message to DingTalk group chat. Use this when user wants to notify team members or send information to DingTalk.on_start中注册给main_control的元数据使用参数数组格式符合LLMToolMetadata定义并将整个元数据以 JSON 形式挂到tool_register命令的tool属性上与 manifest.json 中声明的cmd_out: tool_register接口tool对象含name、description、parameters数组严格对应。工具调用链路当 LLM 决定调用该工具时main_control会向扩展发送tool_call命令对应 manifest 中cmd_in声明的接口name为必填属性on_cmd收到tool_call从命令属性中读取工具名name与argumentsobject 类型当name send_message时调用run_tool执行实际发送逻辑通过Cmd.create(tool_call_result)返回执行结果content属性携带结果文本给调用方LLM 据此向用户播报发送成功或失败其余命令则回退到基类AsyncLLMToolBaseExtension.on_cmd处理。get_tool_metadata方法extension.py同样以LLMToolMetadata结构暴露工具定义参数contentstring必填为要发送的群消息内容。钉钉消息发送与加签实现run_tool内部调用_send_dingtalk_messageextension.py完成真正的 HTTP 推送其实现要点构造 Webhook URLhttps://oapi.dingtalk.com/robot/send?access_token{access_token}加签若配置了 secret按钉钉官方算法计算签名并拼接到 URLtimestamp str(round(time.time() * 1000)) secret_enc secret.encode(utf-8) string_to_sign {}\n{}.format(timestamp, secret) hmac_code hmac.new(secret_enc, string_to_sign.encode(utf-8), digestmodhashlib.sha256).digest() sign urllib.parse.quote_plus(base64.b64encode(hmac_code)) webhook_url f{webhook_url}timestamp{timestamp}sign{sign}发送文本消息requests.post以 JSON 请求体发送timeout10秒请求头为Content-Type: application/json;charsetutf-8data {msgtype: text, text: {content: content}}结果判定以钉钉返回的errcode 0判定成功否则将errcode/errmsg拼接为错误信息返回给 LLM网络层异常则返回{errcode: -1, errmsg: ...}。消息格式与长度约束扩展固定使用钉钉「文本消息」类型msgtype: text。钉钉开放平台对文本消息的 content 长度限制为不超过 5000 字节超长内容建议在调用前由 LLM 或上层逻辑先行截断/摘要。常见问题排查Q配置后扩展没有加载检查manifest.json中的path是否正确相对路径应从示例应用 tenapp 目录指向ten_packages/extension/dingtalk_bot_tool_python确认已运行task install安装依赖查看启动日志中是否出现[DingTalkBotExtension] on_start BEGIN。Q消息发送失败检查access_token和secret是否正确日志会打印其长度以便核对是否为空查看日志中的errcode与errmsg对照钉钉官方错误码文档定位原因常见如 token 失效、加签时间戳偏差、IP 白名单限制确认钉钉机器人的安全设置与代码加签逻辑匹配本扩展实现的是「加签」方式。Q工具未注册到 LLM检查connections中是否正确添加了钉钉扩展到main_control的tool_registersource 列表确认tool_register命令连接配置正确且扩展与main_control处于同一 graph 内可达。小结dingtalk_bot_tool_python以极低的接入成本单一requests依赖为 TEN Framework 的 AI Agent 提供了钉钉群通知能力。通过理解其「异步工具注册 tool_call命令分发 HMAC-SHA256 加签推送」的实现链路开发者可以在voice-assistant等示例基础上快速扩展出会议提醒、告警通知、任务汇报等各类群消息场景并将相同的「LLM Tool 扩展」模式复用到其他 IM 平台如飞书、企业微信的机器人接入中。进一步阅读源码可参考 extension.py、addon.py 与 manifest.json。赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐TEN Framework 钉钉机器人扩展集成指南让 AI 助手通过 LLM 工具向钉钉群推送消息TEN Framework 钉钉机器人扩展集成指南让 AI 助手通过 LLM 工具向钉钉群推送消息 本指南围绕 TEN Framework 开源仓库中的 di人工智能AI Agent多模态语音AI 应用Prometheus告警系统与钉钉机器人Webhook集成实战指南Prometheus告警系统与钉钉机器人Webhook集成实战指南 在现代化监控体系中Prometheus告警系统与钉钉机器人的Webhook集成能够实现告警钉钉告警终极指南ElastAlert群机器人集成与提及功能详解想要实现企业级监控告警的快速推送与精准提醒吗ElastAlert 与钉钉的完美结合让告警管理变得前所未有的简单高效作为一款基于 ElasticSearch告警异常检测上一篇3个核心问题告诉你为什么AnythingLLM是搭建私有AI助手的最佳选择下一篇XUnity.AutoTranslatorUnity游戏实时汉化的终极解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考