前几天一位做供应链的朋友问我“Agent在测试环境里已经能回答商品知识了但团队就是不用因为还得专门打开一个内部网页去问太麻烦。有没有办法让它直接在钉钉群里被一下就能应答”这个问题背后其实藏着一个很常见的认知差AI Agent的“能力”和“被用起来”是两回事。能力由模型和提示词决定而“被用起来”取决于部署入口是否顺手。绝大多数企业内部消息流的终点就是办公IM——钉钉、飞书、企业微信所以把Agent接进这些群聊让员工在原有协作习惯里完成提问和交互才是真正落地的第一步。这篇文章就以PolarDB Agent Express为例完整讲清楚从零开始把AI Agent一键接入钉钉、飞书、企业微信的完整链路。它适合两类人一类是刚接触Agent、想快速在企业内部做一个可演示原型的产品经理另一类是已经在用LangChain这类框架写Agent但不想为IM适配重复造轮子、想找个托管部署方案的开发者。1. 把 AI Agent 从测试环境搬进工作群IM 入口为什么绕不开1.1 不是“多做一个网页对话框”而是“在协作现场直接应答”我见过太多团队把Agent做成一个独立站点模型调好了、知识库接上了、前端页面也做好了最后发现没人用。原因很简单——用户不愿意为了问一句话从正在聊天的钉钉窗口切到另一个系统。这不是懒而是工作流惯性。群聊才是企业里信息交换最密集的现场订单确认、排班查询、制度疑问、数据核对都发生在群里面。Agent如果不在群聊里响应就必须用户主动“去找它”这一步就劝退了绝大多数非技术同事。接入IM之后Agent的交互方式就变成同事在群里机器人提出自然语言问题Agent在几秒内回一段带格式的答案。整个过程中用户不需要学习任何新工具也不用理解提示词是什么。对一个零基础员工来说“像人一样机器人”是零学习成本的使用方式。1.2 办公IM自带身份体系Agent能知道“谁在提问”还有一个很容易被忽略的技术红利钉钉、飞书、企业微信在把消息推送给后端时都会带上发送者的用户ID、所在群ID、租户ID。这意味着Agent从第一轮对话开始就知道提问者是谁、属于哪个部门、在哪个群里问的。这个身份信息在实际业务里非常值钱。比如企业微信里一个销售问“我上个月业绩达标了吗”Agent可以根据用户ID去关联CRM系统精准查询该销售的数据而不是笼统查全公司。如果没有IM这层身份映射你得在自建前端里再做一整套登录、权限、用户体系工作量立刻上一个台阶。用IM作为入口等于把企业身份认证这个最难啃的基础设施直接复用了。1.3 消息留痕是天然审计优势聊天机器人天然有一条完整的交互记录谁、在什么时间、问了什么问题、Agent怎么回答的。I M 会话记录本身就具备审计属性出现错误回答或数据越权时可以溯源到具体某条消息。在生产环境里这个特性比“技术炫酷”重要得多。尤其在做企业数据问答时运维和合规人员最担心的就是Agent跑出来一个没依据的结论IM留痕给了事后核查的兜底手段。2. PolarDB Agent Express 的定位拆解连接器、记忆、数据源三者如何协同2.1 它到底是什么一个托管式的Agent编排与接入平台PolarDB Agent Express本质上是一个“Agent接入中间层”它在底层模型和上层IM之间补齐了连接器、会话记忆、知识库管理、数据源访问这些基础设施。这样说可能有点抽象我用一个装修的类比解释。假设你要在办公室里装一个智能前台大模型相当于前台人员的“大脑”但光有大脑还不够她得能接到访客按门铃的讯号消息入口得能记住昨天来过谁记忆得能查到会议室预订记录数据源还得把事情记录在案存储。这些都不是大脑本身能单独完成的需要一整套外围设施。Express做的就是把这些外围设施提前搭好消息从钉钉/飞书/企微进来后经过它的连接器转换交给大模型推理再通过它配置的数据源和知识库去检索信息最后生成回复通过同一连接器返回IM。全程通过控制台可视化配置不需要写一行消息接收代码。2.2 数据库层在Agent链路里承担的不是“存数据”而是“记忆和事实来源”很多人在搭Agent时默认把数据库当成“可选配件”只在涉及订单查询时才想到它。但实际生产环境中数据库承担了两个更关键的职责。第一个是会话记忆。多轮对话如果每次都要把全部历史塞给大模型成本和延迟都会失控。Express会把会话记录持久化到PolarDB每次请求只取最近几轮关键上下文。这样既能控制Token开销又能在Agent重启后恢复对话现场。第二个是事实依据。大模型容易出现一本正经地胡说八道也就是幻觉。一个有效的抑制手段就是让它先查库再回答。PolarDB里存的业务表就是Agent的“事实来源”模型不再凭训练时的记忆回答而是根据实时查询结果生成回复。这也是我坚持要求把Agent和数据库做连接的原因——只靠提示词约束效果远不如“让它先看到数据”。2.3 零代码的边界能覆盖80%常见场景但不是万能的需要把话说透一点零代码不等于“什么都能做”。PolarDB Agent Express擅长的是对话问答、知识检索、数据库查询、工单处理这类以“自然语言进结构化答案出”的交互。它的配置方式是把连接器、模型参数、知识库、数据源、提示词模板做成可选项用户像填表一样完成组装。但如果你需要Agent在对话过程中调用多个业务系统并编排复杂状态流转比如“先查库存→再创建采购单→等待审批→审批通过后通知仓库”那仍然建议用LangGraph这类代码框架来做流程控制完成后通过API方式挂到Express上。用Express承接对话入口用代码处理复杂编排是我比较推荐的分工方式。3. 钉钉通道完整实操从创建企业内部应用到群内首条对话3.1 在钉钉开放平台创建企业内部应用拿到第一组凭证第一步去钉钉开发者后台open-dev.dingtalk.com在“应用开发”里选“企业内部应用”点击创建应用。应用名称建议直接叫“XX智能助手”图标可以随便传一个后续能改。创建完成后在“凭证与基础信息”页面你会看到两个关键字段AppKey和AppSecret。AppKey是应用的公开标识AppSecret相当于密码两者是后续Express接入钉钉时要用到的核心凭证。这里有个新手最容易搞混的点钉钉有两种“机器人”。一种是群内自定义机器人通过Webhook发消息只能单向推送不能接收用户回复另一种是企业内部应用添加的机器人通过事件订阅或Stream模式接收消息这才是Agent要用的。所以请务必走“企业内部应用”这条路不要用群里那种自定义机器人。3.2 在 Express 控制台完成Agent的创建和模型选择登录PolarDB Agent Express控制台点击“新建Agent”会进入一个配置页主要几项基础信息Agent名称、头像、简介这些会同步展示到IM机器人上。模型服务选择底层大模型。常见选项包括通义千问、DeepSeek等如果企业有自己的模型网关也可以填自定义API地址。首次使用建议先选一个响应速度快的轻量模型跑通链路再换更强模型。提示词模板给Agent设定角色和行为边界。我的建议是先写一句话“你是XX企业的智能助手请用中文简洁作答信息不足时请明确说明”不要一上来就写长篇复杂的System Prompt先跑通再迭代。渠道配置选择“钉钉”把刚才的AppKey和AppSecret粘贴进来。保存之后Express会生成一个回调地址格式类似https://agentexpress.example.com/webhook/dingtalk/{appId}。这个地址在下一步要贴到钉钉后台。3.3 配置事件订阅完成消息通道握手回到钉钉开发者后台进入你创建的应用左侧菜单找到“事件订阅”。这里的核心动作是配置“请求地址”也就是把Express生成的那个回调URL粘贴进去。钉钉会立即对该地址发起一次验证请求确认这个回调地址是有效且可控的。验证通过后你需要勾选要订阅的事件。对Agent场景来说最关键的是群消息和单聊消息事件不同版本后台叫法略有区别认准“消息”分类下的事件即可。接着往下看“安全设置”区域钉钉提供三种安全校验方式关键词、加签、IP白名单。建议至少启用“加签”并把签名密钥保存下来同步到Express侧对应配置项。如果为了快速验证可以只启用“自定义关键词”并把机器人名称设为关键词但生产环境不要偷懒加签是必须的。全部保存后去钉钉里建一个测试群把应用发布到群中并添加机器人。在群里机器人说“你好”如果收到回复说明钉钉通道已经全链路打通。3.4 上线后立刻要做的三件事看到机器人能回消息只是起点有三件事建议当天就做第一在Express里开启会话日志确认每条消息的消息来源、用户ID、群ID都有记录。第二检查钉钉后台的机器人权限范围明确哪些部门和成员可以使用避免所有人都能调用。第三把“失败兜底回复”这段话改了——默认可能比较生硬改成“我没有理解这个问题请联系IT支持”避免用户在群里反复尝试后失去耐心。4. 飞书与企业微信的配置差异同一套 Agent三种打开方式4.1 飞书先花两分钟理解“URL验证”和“版本发布”这两道坎飞书的接入逻辑和钉钉相似但有两个显著不同的地方。第一步同样是去飞书开放平台创建“企业自建应用”然后在“应用能力”里启用机器人。在“事件与回调”页面配置订阅方式时飞书要求填写“请求地址”并且默认启用Encrypt Key和Verification Token两种校验机制。Encrypt Key用于消息体加密Verification Token用于验证回调来源。Express控制台会要求你把这几个值同步过来然后生成一个带签名校验的接收端点。第二个关键差异是飞书做了完整的“版本发布”流程。你在开发环境把机器人配置好了不代表立即生效必须创建版本、填写版本说明、提交发布然后由企业管理员在管理后台审核通过后机器人才算正式对外可用。很多人在飞书里折腾半天代码、回调、加密全配好了机器人就是不回话最后发现是版本没有发布。这是个极其常见又隐蔽的坑。4.2 企业微信出口IP和可见范围少了哪一个都不行企业微信走的是另一套逻辑。你要在企业微信管理后台的“应用管理”里创建“自建应用”创建后拿到三个关键凭证Corp ID企业ID、AgentId应用ID、Secret应用密钥。然后在“接收消息”设置页面配置URL、Token和EncodingAESKey。这里的URL同样是Express生成的企微回调地址Token和EncodingAESKey由Express生成后填进来。企业微信的URL校验机制是微信服务器会向你的URL发起一次GET请求携带echostr参数你的服务端需要完成解密并把明文echostr返回给微信校验才算通过。企微有两个极易踩坑的独特点一是企业可信IP。企业微信出于安全考虑要求调用API的服务器IP必须添加到应用的“企业可信IP”白名单里否则接口调用会报错。如果Agent部署在云服务器上就把该服务器的公网出口IP填进去。如果IP是动态的建议先部署到固定IP的服务器上再接企微。二是可见范围。开发者创建自建应用并配置完消息接收后必须设置应用可见范围指定哪些部门或成员可以使用。如果可见范围设置为空或者你自己的测试账号不在范围内应用看起来已经启用但实际不会给任何人推送消息。这两个问题几乎是企微接入失败的前两大原因。4.3 一张表看懂三家平台的接入差异对比项钉钉飞书企业微信核心凭证AppKey AppSecretApp ID App SecretCorp ID AgentId Secret消息接收方式事件订阅/Stream模式事件订阅接收消息服务器回调验证时是否需要响应加密串需要需要需要端上生效是否要“发布版本”不需要保存即生效必须发布版本并审核不需要但需设置可见范围最容易漏掉的配置安全设置里的“加签”版本发布企业可信IP、可见范围特殊限制自定义机器人只能推不能收加密Key必须两端匹配出口IP必须在白名单内这张表建议收藏平时排障时对照着看能省不少时间。三个平台的共同点也很明显都要求HTTPS回调地址、都有消息签名或加密校验、都强调应用权限必须显式开启。5. 消息链路排查实录机器人“已上线却不回话”的常见根因5.1 现象一飞书机器人配好了私聊和群里都没任何反应这是我在实际部署中遇到过最多次的飞书问题。排查顺序应该是先看飞书后台“事件订阅”里那条订阅记录是否显示“验证通过”再看“应用发布”里是不是存在一个已通过审核的正式版本最后打开Express的日志页面看有没有收到来自飞书的回调打卡。如果前两项都正常但Express没日志问题大概率出在Encrypt Key或Verification Token不一致。飞书在推送消息时会用这两个值做签名和加密任何一项对不上回调都会被丢弃而且飞书后台不一定给你明确报错只显示“推送失败”。建议把飞书后台的值和Express连接配置里的值逐字符核对一遍。如果日志里有请求记录但Agent没有回复再看是不是飞书要求3秒内响应回调。如果Agent的问题链路涉及复杂数据库查询容易超过这个时限。解决办法是把Express的接收模式改成“先回执、后处理”Express收到消息后立即向飞书返回{code:0}表示已接收然后后台异步调用模型和数据库生成答案后再通过主动推送接口发到群里。5.2 现象二钉钉群里了机器人它像没听见一样钉钉出现这个现象通常有三层原因。第一层是“安全设置”拦截。钉钉后台的机器人安全设置里有“关键词”“加签”“IP白名单”三个选项如果你只配置了“关键词”而群里那条消息里没有包含关键词钉钉会直接不把消息推给你机器人当然没反应。解决方案是测试群里机器人时带上机器人名称或者干脆在生产环境启用“加签”。第二层是“事件订阅范围”。钉钉事件订阅支持按消息类型订阅如果只订阅了单聊消息没订阅群消息那么群里它就没用。检查一下订阅列表里是否包含了“群消息”相关事件。第三层是“消息接收模式”的选择。钉钉企业内部应用机器人支持HTTP回调也支持Stream长连接模式。如果你在Express配置里用回调模式但钉钉后台坚持走Stream模式两边对不上消息就丢了。用哪个取决于你在Express里选择了哪一种两边必须一致。5.3 现象三企业微信里Agent对同一条消息回了多次这个坑比较隐蔽。企业微信的“接收消息服务器”本质上是把消息推送到你的HTTP回调而企业微信对回调失败的策略是重试推送。如果你发现Agent对一条问题回复了两三次多数时候不是重复消息而是第一次回复超时或校验失败企微自动重推了一次。另一个常见情况是消息加密串重复消费。Express内部需要做幂等处理对同一MsgId的消息只处理一次。绝大多数情况下平台的托管服务已经处理好了这个逻辑但如果你自研过类似服务一定要自己判断这个去重逻辑。处理方式在Express的日志里找到对应消息的MsgId看它是被处理了几次。如果是两次且两次时间间隔约等于你设置的回调超时时间那就是超时重推如果间隔很短很可能是接入配置里出现双通道同时订阅了消息。5.4 一套通用的排查思路无论哪个IM平台排查顺序遵循“从外到内”的原则先确认消息是否到达平台官方后台看订阅记录/推送状态再确认平台是否成功回调到Express看日志中的HTTP请求记录然后确认Agent是否完成处理和回复看日志最后一条类型是否包含answer最后确认回复是否被IM接口接受看IM后台API调用记录。你不需要记住所有具体的报错码只要定位到是哪一个环节断了问题就解决了一半。6. 接入 PolarDB 数据源让 Agent 用业务数据回答问题的落地方案6.1 零代码接入业务库先从只读账号说起Agent要回答业务数据问题就必须能访问数据库。这一环节我强烈建议从“最小权限”开始在PolarDB里新建一个专用的只读账号只授予查询权限不允许任何写操作。在Express控制台的“数据源”页面选择PolarDB MySQL兼容版填入连接地址、端口、数据库名以及这个只读账号的密码。保存并测试连接通过后Agent就拥有了读取该数据库的通道。剩下的所有操作包括SQL生成、执行、结果格式化都由Express在后台替你完成。可能有人会问为什么不用管理员账号因为Agent在自然语言转SQL时哪怕模型再稳也有极小概率生成有问题的语句。只读账号保证了最坏情况下也只是“查错数据”而不是“改坏数据”。这个安全红线一定不能省。6.2 用“表注释字段说明”把SQL幻觉压到最低大模型生成SQL并不总能准确理解表结构。举个例子一张订单表里有个字段叫order_status如果值是0、1、2这种数字模型很难猜到这个到底代表“已提交”“已完成”还是“已取消”。解决办法是给字段加上注释让Agent看到明确语义。在PolarDB里执行类似COMMENT ON COLUMN order_table.order_status IS 订单状态0-已提交1-已支付2-已完成3-已取消这样的语句。模型在生成SQL前会先读取表结构字段注释会被一并传入有了这些注释它能“猜中”业务的概率会大幅提升。还有一个技巧是在Express的数据源配置页面维护表的业务名称和别名。比如告诉它“sku_info就是商品表sku_name是商品名”这种配置比全让模型自己领会要稳得多。6.3 让知识库支持语义检索把向量化内容存在PolarDB里除了结构化数据企业里还有大量非结构化知识制度文档、操作手册、产品FAQ。Agent直接把这些原文发送给大模型既费Token又容易超上下文窗口正确做法是走RAG检索增强生成路线。Express的知识库管理功能允许你上传PDF、Word、Markdown等格式文档。上传后它会自动做切片和向量化处理向量数据存放在PolarDB中。当用户在群里问“年假制度是什么”Agent先在向量库里做语义相似度检索找出最相关的几个文本切片再连同问题一起交给大模型生成答案。这里特别提一下把向量放回关系型数据库的好处你可以把“文档所属部门”“文档版本”“上传人”这类业务属性也存成PolarDB的表字段检索时通过SQL的WHERE条件做权限过滤。比如一个销售制度文档只允许销售部门检索普通员工的提问虽然命中了语义但因为权限过滤被直接挡掉。这是独立向量数据库很难直接做到的。6.4 权限与审计哪些数据能查不能完全失控数据源接上了能回答的业务问题变多了权限失控风险也随之上升。我建议至少做三件事第一在PolarDB侧建只读账号时通过GRANT SELECT ON 具体数据库名.* TO agent%明确限定它只能查哪些库。不要把整个实例的全部库表一次性授权给它。第二在Express的“数据源策略”里开启“SQL执行前预览”或“敏感操作拦截”如果Agent生成的SQL里出现了DROP、DELETE、UPDATE这类非查询关键词直接拒绝执行。特别是当你只授了SELECT权限后这个拦截只是第二道保险。第三打开PolarDB的SQL审计日志。每当Agent执行一条查询审计日志里会记录完整的SQL语句。这样一旦出现数据泄露或误答可以精确回溯是哪个用户、在哪个时间、让Agent执行了什么查询。这也是IM入口那个“天然留痕”特性在数据层的延伸。7. 最后聊几句实在话Agent 上线后的第一周该怎么管前面把技术链路讲完了最后我想说点不太会写进官方文档的经验。第一个建议第一个Agent的上线场景不要选那些“看起来酷但没人真用”的。最佳选择是每个部门每天都会被问到的问题比如人事制度问答、IT支持指南、订单物流状态查询。让同事们在真实工作流里连续用一周你才会知道提示词哪里写得不清、哪些表结构描述容易让它答错、哪个IM平台的消息格式展示最难看。第二个建议上线之后不要只看“它回答了吗”要抽几条真实对话人工复核。把群里的问题、Agent的回答、实际数据三条放在一起做对照。错一次可能是模型的偶发问题错三次以上就说明某个环节配置有问题得回头调整字段注释或提示词。第三个建议给Agent留一条人工兜底的口子。比如在回答结尾附带一句“以上结果仅供参考如需人工确认请联系xxx”。这既是给用户安全感也是给自己留出容错空间。AI Agent的生产落地从来不是“一锤子买卖”IM接入只是起点真正有价值的工作是在上线后把每一个错误回答变成下一次对话的质量改进素材。 把AI Agent一键接入钉钉飞书企微：PolarDB Agent Express实战
前几天一位做供应链的朋友问我“Agent在测试环境里已经能回答商品知识了但团队就是不用因为还得专门打开一个内部网页去问太麻烦。有没有办法让它直接在钉钉群里被一下就能应答”这个问题背后其实藏着一个很常见的认知差AI Agent的“能力”和“被用起来”是两回事。能力由模型和提示词决定而“被用起来”取决于部署入口是否顺手。绝大多数企业内部消息流的终点就是办公IM——钉钉、飞书、企业微信所以把Agent接进这些群聊让员工在原有协作习惯里完成提问和交互才是真正落地的第一步。这篇文章就以PolarDB Agent Express为例完整讲清楚从零开始把AI Agent一键接入钉钉、飞书、企业微信的完整链路。它适合两类人一类是刚接触Agent、想快速在企业内部做一个可演示原型的产品经理另一类是已经在用LangChain这类框架写Agent但不想为IM适配重复造轮子、想找个托管部署方案的开发者。1. 把 AI Agent 从测试环境搬进工作群IM 入口为什么绕不开1.1 不是“多做一个网页对话框”而是“在协作现场直接应答”我见过太多团队把Agent做成一个独立站点模型调好了、知识库接上了、前端页面也做好了最后发现没人用。原因很简单——用户不愿意为了问一句话从正在聊天的钉钉窗口切到另一个系统。这不是懒而是工作流惯性。群聊才是企业里信息交换最密集的现场订单确认、排班查询、制度疑问、数据核对都发生在群里面。Agent如果不在群聊里响应就必须用户主动“去找它”这一步就劝退了绝大多数非技术同事。接入IM之后Agent的交互方式就变成同事在群里机器人提出自然语言问题Agent在几秒内回一段带格式的答案。整个过程中用户不需要学习任何新工具也不用理解提示词是什么。对一个零基础员工来说“像人一样机器人”是零学习成本的使用方式。1.2 办公IM自带身份体系Agent能知道“谁在提问”还有一个很容易被忽略的技术红利钉钉、飞书、企业微信在把消息推送给后端时都会带上发送者的用户ID、所在群ID、租户ID。这意味着Agent从第一轮对话开始就知道提问者是谁、属于哪个部门、在哪个群里问的。这个身份信息在实际业务里非常值钱。比如企业微信里一个销售问“我上个月业绩达标了吗”Agent可以根据用户ID去关联CRM系统精准查询该销售的数据而不是笼统查全公司。如果没有IM这层身份映射你得在自建前端里再做一整套登录、权限、用户体系工作量立刻上一个台阶。用IM作为入口等于把企业身份认证这个最难啃的基础设施直接复用了。1.3 消息留痕是天然审计优势聊天机器人天然有一条完整的交互记录谁、在什么时间、问了什么问题、Agent怎么回答的。I M 会话记录本身就具备审计属性出现错误回答或数据越权时可以溯源到具体某条消息。在生产环境里这个特性比“技术炫酷”重要得多。尤其在做企业数据问答时运维和合规人员最担心的就是Agent跑出来一个没依据的结论IM留痕给了事后核查的兜底手段。2. PolarDB Agent Express 的定位拆解连接器、记忆、数据源三者如何协同2.1 它到底是什么一个托管式的Agent编排与接入平台PolarDB Agent Express本质上是一个“Agent接入中间层”它在底层模型和上层IM之间补齐了连接器、会话记忆、知识库管理、数据源访问这些基础设施。这样说可能有点抽象我用一个装修的类比解释。假设你要在办公室里装一个智能前台大模型相当于前台人员的“大脑”但光有大脑还不够她得能接到访客按门铃的讯号消息入口得能记住昨天来过谁记忆得能查到会议室预订记录数据源还得把事情记录在案存储。这些都不是大脑本身能单独完成的需要一整套外围设施。Express做的就是把这些外围设施提前搭好消息从钉钉/飞书/企微进来后经过它的连接器转换交给大模型推理再通过它配置的数据源和知识库去检索信息最后生成回复通过同一连接器返回IM。全程通过控制台可视化配置不需要写一行消息接收代码。2.2 数据库层在Agent链路里承担的不是“存数据”而是“记忆和事实来源”很多人在搭Agent时默认把数据库当成“可选配件”只在涉及订单查询时才想到它。但实际生产环境中数据库承担了两个更关键的职责。第一个是会话记忆。多轮对话如果每次都要把全部历史塞给大模型成本和延迟都会失控。Express会把会话记录持久化到PolarDB每次请求只取最近几轮关键上下文。这样既能控制Token开销又能在Agent重启后恢复对话现场。第二个是事实依据。大模型容易出现一本正经地胡说八道也就是幻觉。一个有效的抑制手段就是让它先查库再回答。PolarDB里存的业务表就是Agent的“事实来源”模型不再凭训练时的记忆回答而是根据实时查询结果生成回复。这也是我坚持要求把Agent和数据库做连接的原因——只靠提示词约束效果远不如“让它先看到数据”。2.3 零代码的边界能覆盖80%常见场景但不是万能的需要把话说透一点零代码不等于“什么都能做”。PolarDB Agent Express擅长的是对话问答、知识检索、数据库查询、工单处理这类以“自然语言进结构化答案出”的交互。它的配置方式是把连接器、模型参数、知识库、数据源、提示词模板做成可选项用户像填表一样完成组装。但如果你需要Agent在对话过程中调用多个业务系统并编排复杂状态流转比如“先查库存→再创建采购单→等待审批→审批通过后通知仓库”那仍然建议用LangGraph这类代码框架来做流程控制完成后通过API方式挂到Express上。用Express承接对话入口用代码处理复杂编排是我比较推荐的分工方式。3. 钉钉通道完整实操从创建企业内部应用到群内首条对话3.1 在钉钉开放平台创建企业内部应用拿到第一组凭证第一步去钉钉开发者后台open-dev.dingtalk.com在“应用开发”里选“企业内部应用”点击创建应用。应用名称建议直接叫“XX智能助手”图标可以随便传一个后续能改。创建完成后在“凭证与基础信息”页面你会看到两个关键字段AppKey和AppSecret。AppKey是应用的公开标识AppSecret相当于密码两者是后续Express接入钉钉时要用到的核心凭证。这里有个新手最容易搞混的点钉钉有两种“机器人”。一种是群内自定义机器人通过Webhook发消息只能单向推送不能接收用户回复另一种是企业内部应用添加的机器人通过事件订阅或Stream模式接收消息这才是Agent要用的。所以请务必走“企业内部应用”这条路不要用群里那种自定义机器人。3.2 在 Express 控制台完成Agent的创建和模型选择登录PolarDB Agent Express控制台点击“新建Agent”会进入一个配置页主要几项基础信息Agent名称、头像、简介这些会同步展示到IM机器人上。模型服务选择底层大模型。常见选项包括通义千问、DeepSeek等如果企业有自己的模型网关也可以填自定义API地址。首次使用建议先选一个响应速度快的轻量模型跑通链路再换更强模型。提示词模板给Agent设定角色和行为边界。我的建议是先写一句话“你是XX企业的智能助手请用中文简洁作答信息不足时请明确说明”不要一上来就写长篇复杂的System Prompt先跑通再迭代。渠道配置选择“钉钉”把刚才的AppKey和AppSecret粘贴进来。保存之后Express会生成一个回调地址格式类似https://agentexpress.example.com/webhook/dingtalk/{appId}。这个地址在下一步要贴到钉钉后台。3.3 配置事件订阅完成消息通道握手回到钉钉开发者后台进入你创建的应用左侧菜单找到“事件订阅”。这里的核心动作是配置“请求地址”也就是把Express生成的那个回调URL粘贴进去。钉钉会立即对该地址发起一次验证请求确认这个回调地址是有效且可控的。验证通过后你需要勾选要订阅的事件。对Agent场景来说最关键的是群消息和单聊消息事件不同版本后台叫法略有区别认准“消息”分类下的事件即可。接着往下看“安全设置”区域钉钉提供三种安全校验方式关键词、加签、IP白名单。建议至少启用“加签”并把签名密钥保存下来同步到Express侧对应配置项。如果为了快速验证可以只启用“自定义关键词”并把机器人名称设为关键词但生产环境不要偷懒加签是必须的。全部保存后去钉钉里建一个测试群把应用发布到群中并添加机器人。在群里机器人说“你好”如果收到回复说明钉钉通道已经全链路打通。3.4 上线后立刻要做的三件事看到机器人能回消息只是起点有三件事建议当天就做第一在Express里开启会话日志确认每条消息的消息来源、用户ID、群ID都有记录。第二检查钉钉后台的机器人权限范围明确哪些部门和成员可以使用避免所有人都能调用。第三把“失败兜底回复”这段话改了——默认可能比较生硬改成“我没有理解这个问题请联系IT支持”避免用户在群里反复尝试后失去耐心。4. 飞书与企业微信的配置差异同一套 Agent三种打开方式4.1 飞书先花两分钟理解“URL验证”和“版本发布”这两道坎飞书的接入逻辑和钉钉相似但有两个显著不同的地方。第一步同样是去飞书开放平台创建“企业自建应用”然后在“应用能力”里启用机器人。在“事件与回调”页面配置订阅方式时飞书要求填写“请求地址”并且默认启用Encrypt Key和Verification Token两种校验机制。Encrypt Key用于消息体加密Verification Token用于验证回调来源。Express控制台会要求你把这几个值同步过来然后生成一个带签名校验的接收端点。第二个关键差异是飞书做了完整的“版本发布”流程。你在开发环境把机器人配置好了不代表立即生效必须创建版本、填写版本说明、提交发布然后由企业管理员在管理后台审核通过后机器人才算正式对外可用。很多人在飞书里折腾半天代码、回调、加密全配好了机器人就是不回话最后发现是版本没有发布。这是个极其常见又隐蔽的坑。4.2 企业微信出口IP和可见范围少了哪一个都不行企业微信走的是另一套逻辑。你要在企业微信管理后台的“应用管理”里创建“自建应用”创建后拿到三个关键凭证Corp ID企业ID、AgentId应用ID、Secret应用密钥。然后在“接收消息”设置页面配置URL、Token和EncodingAESKey。这里的URL同样是Express生成的企微回调地址Token和EncodingAESKey由Express生成后填进来。企业微信的URL校验机制是微信服务器会向你的URL发起一次GET请求携带echostr参数你的服务端需要完成解密并把明文echostr返回给微信校验才算通过。企微有两个极易踩坑的独特点一是企业可信IP。企业微信出于安全考虑要求调用API的服务器IP必须添加到应用的“企业可信IP”白名单里否则接口调用会报错。如果Agent部署在云服务器上就把该服务器的公网出口IP填进去。如果IP是动态的建议先部署到固定IP的服务器上再接企微。二是可见范围。开发者创建自建应用并配置完消息接收后必须设置应用可见范围指定哪些部门或成员可以使用。如果可见范围设置为空或者你自己的测试账号不在范围内应用看起来已经启用但实际不会给任何人推送消息。这两个问题几乎是企微接入失败的前两大原因。4.3 一张表看懂三家平台的接入差异对比项钉钉飞书企业微信核心凭证AppKey AppSecretApp ID App SecretCorp ID AgentId Secret消息接收方式事件订阅/Stream模式事件订阅接收消息服务器回调验证时是否需要响应加密串需要需要需要端上生效是否要“发布版本”不需要保存即生效必须发布版本并审核不需要但需设置可见范围最容易漏掉的配置安全设置里的“加签”版本发布企业可信IP、可见范围特殊限制自定义机器人只能推不能收加密Key必须两端匹配出口IP必须在白名单内这张表建议收藏平时排障时对照着看能省不少时间。三个平台的共同点也很明显都要求HTTPS回调地址、都有消息签名或加密校验、都强调应用权限必须显式开启。5. 消息链路排查实录机器人“已上线却不回话”的常见根因5.1 现象一飞书机器人配好了私聊和群里都没任何反应这是我在实际部署中遇到过最多次的飞书问题。排查顺序应该是先看飞书后台“事件订阅”里那条订阅记录是否显示“验证通过”再看“应用发布”里是不是存在一个已通过审核的正式版本最后打开Express的日志页面看有没有收到来自飞书的回调打卡。如果前两项都正常但Express没日志问题大概率出在Encrypt Key或Verification Token不一致。飞书在推送消息时会用这两个值做签名和加密任何一项对不上回调都会被丢弃而且飞书后台不一定给你明确报错只显示“推送失败”。建议把飞书后台的值和Express连接配置里的值逐字符核对一遍。如果日志里有请求记录但Agent没有回复再看是不是飞书要求3秒内响应回调。如果Agent的问题链路涉及复杂数据库查询容易超过这个时限。解决办法是把Express的接收模式改成“先回执、后处理”Express收到消息后立即向飞书返回{code:0}表示已接收然后后台异步调用模型和数据库生成答案后再通过主动推送接口发到群里。5.2 现象二钉钉群里了机器人它像没听见一样钉钉出现这个现象通常有三层原因。第一层是“安全设置”拦截。钉钉后台的机器人安全设置里有“关键词”“加签”“IP白名单”三个选项如果你只配置了“关键词”而群里那条消息里没有包含关键词钉钉会直接不把消息推给你机器人当然没反应。解决方案是测试群里机器人时带上机器人名称或者干脆在生产环境启用“加签”。第二层是“事件订阅范围”。钉钉事件订阅支持按消息类型订阅如果只订阅了单聊消息没订阅群消息那么群里它就没用。检查一下订阅列表里是否包含了“群消息”相关事件。第三层是“消息接收模式”的选择。钉钉企业内部应用机器人支持HTTP回调也支持Stream长连接模式。如果你在Express配置里用回调模式但钉钉后台坚持走Stream模式两边对不上消息就丢了。用哪个取决于你在Express里选择了哪一种两边必须一致。5.3 现象三企业微信里Agent对同一条消息回了多次这个坑比较隐蔽。企业微信的“接收消息服务器”本质上是把消息推送到你的HTTP回调而企业微信对回调失败的策略是重试推送。如果你发现Agent对一条问题回复了两三次多数时候不是重复消息而是第一次回复超时或校验失败企微自动重推了一次。另一个常见情况是消息加密串重复消费。Express内部需要做幂等处理对同一MsgId的消息只处理一次。绝大多数情况下平台的托管服务已经处理好了这个逻辑但如果你自研过类似服务一定要自己判断这个去重逻辑。处理方式在Express的日志里找到对应消息的MsgId看它是被处理了几次。如果是两次且两次时间间隔约等于你设置的回调超时时间那就是超时重推如果间隔很短很可能是接入配置里出现双通道同时订阅了消息。5.4 一套通用的排查思路无论哪个IM平台排查顺序遵循“从外到内”的原则先确认消息是否到达平台官方后台看订阅记录/推送状态再确认平台是否成功回调到Express看日志中的HTTP请求记录然后确认Agent是否完成处理和回复看日志最后一条类型是否包含answer最后确认回复是否被IM接口接受看IM后台API调用记录。你不需要记住所有具体的报错码只要定位到是哪一个环节断了问题就解决了一半。6. 接入 PolarDB 数据源让 Agent 用业务数据回答问题的落地方案6.1 零代码接入业务库先从只读账号说起Agent要回答业务数据问题就必须能访问数据库。这一环节我强烈建议从“最小权限”开始在PolarDB里新建一个专用的只读账号只授予查询权限不允许任何写操作。在Express控制台的“数据源”页面选择PolarDB MySQL兼容版填入连接地址、端口、数据库名以及这个只读账号的密码。保存并测试连接通过后Agent就拥有了读取该数据库的通道。剩下的所有操作包括SQL生成、执行、结果格式化都由Express在后台替你完成。可能有人会问为什么不用管理员账号因为Agent在自然语言转SQL时哪怕模型再稳也有极小概率生成有问题的语句。只读账号保证了最坏情况下也只是“查错数据”而不是“改坏数据”。这个安全红线一定不能省。6.2 用“表注释字段说明”把SQL幻觉压到最低大模型生成SQL并不总能准确理解表结构。举个例子一张订单表里有个字段叫order_status如果值是0、1、2这种数字模型很难猜到这个到底代表“已提交”“已完成”还是“已取消”。解决办法是给字段加上注释让Agent看到明确语义。在PolarDB里执行类似COMMENT ON COLUMN order_table.order_status IS 订单状态0-已提交1-已支付2-已完成3-已取消这样的语句。模型在生成SQL前会先读取表结构字段注释会被一并传入有了这些注释它能“猜中”业务的概率会大幅提升。还有一个技巧是在Express的数据源配置页面维护表的业务名称和别名。比如告诉它“sku_info就是商品表sku_name是商品名”这种配置比全让模型自己领会要稳得多。6.3 让知识库支持语义检索把向量化内容存在PolarDB里除了结构化数据企业里还有大量非结构化知识制度文档、操作手册、产品FAQ。Agent直接把这些原文发送给大模型既费Token又容易超上下文窗口正确做法是走RAG检索增强生成路线。Express的知识库管理功能允许你上传PDF、Word、Markdown等格式文档。上传后它会自动做切片和向量化处理向量数据存放在PolarDB中。当用户在群里问“年假制度是什么”Agent先在向量库里做语义相似度检索找出最相关的几个文本切片再连同问题一起交给大模型生成答案。这里特别提一下把向量放回关系型数据库的好处你可以把“文档所属部门”“文档版本”“上传人”这类业务属性也存成PolarDB的表字段检索时通过SQL的WHERE条件做权限过滤。比如一个销售制度文档只允许销售部门检索普通员工的提问虽然命中了语义但因为权限过滤被直接挡掉。这是独立向量数据库很难直接做到的。6.4 权限与审计哪些数据能查不能完全失控数据源接上了能回答的业务问题变多了权限失控风险也随之上升。我建议至少做三件事第一在PolarDB侧建只读账号时通过GRANT SELECT ON 具体数据库名.* TO agent%明确限定它只能查哪些库。不要把整个实例的全部库表一次性授权给它。第二在Express的“数据源策略”里开启“SQL执行前预览”或“敏感操作拦截”如果Agent生成的SQL里出现了DROP、DELETE、UPDATE这类非查询关键词直接拒绝执行。特别是当你只授了SELECT权限后这个拦截只是第二道保险。第三打开PolarDB的SQL审计日志。每当Agent执行一条查询审计日志里会记录完整的SQL语句。这样一旦出现数据泄露或误答可以精确回溯是哪个用户、在哪个时间、让Agent执行了什么查询。这也是IM入口那个“天然留痕”特性在数据层的延伸。7. 最后聊几句实在话Agent 上线后的第一周该怎么管前面把技术链路讲完了最后我想说点不太会写进官方文档的经验。第一个建议第一个Agent的上线场景不要选那些“看起来酷但没人真用”的。最佳选择是每个部门每天都会被问到的问题比如人事制度问答、IT支持指南、订单物流状态查询。让同事们在真实工作流里连续用一周你才会知道提示词哪里写得不清、哪些表结构描述容易让它答错、哪个IM平台的消息格式展示最难看。第二个建议上线之后不要只看“它回答了吗”要抽几条真实对话人工复核。把群里的问题、Agent的回答、实际数据三条放在一起做对照。错一次可能是模型的偶发问题错三次以上就说明某个环节配置有问题得回头调整字段注释或提示词。第三个建议给Agent留一条人工兜底的口子。比如在回答结尾附带一句“以上结果仅供参考如需人工确认请联系xxx”。这既是给用户安全感也是给自己留出容错空间。AI Agent的生产落地从来不是“一锤子买卖”IM接入只是起点真正有价值的工作是在上线后把每一个错误回答变成下一次对话的质量改进素材。