基于钉钉/飞书/企微的办公 Agent 开发指南引言办公 IM 即 Agent 的“操作系统”钉钉、飞书、企业微信以下简称“企微”已成为国内企业的数字办公底座。将 AI Agent 接入这些平台意味着员工无需切换系统在聊天窗口中即可完成审批、查询、代办等复杂操作。本指南将提供一套跨平台兼容的 Agent 开发框架覆盖从消息接收、意图识别到业务处理的完整闭环。技术背景三大平台机器人机制对比平台消息接收方式消息发送方式核心认证机制钉钉回调 URL (加签验证)SessionWebhook / 服务端 APIAppKey/Secret 签名飞书回调 URL (加签验证)服务端 API (Tenant Token)App ID/Secret 签名企微回调 URL (URL 验证)Webhook / 回调 Response URLCorp ID/Secret核心差异点钉钉提供临时的sessionWebhook在回复消息时无需重新获取 Token效率高。飞书权限体系最复杂需通过tenant_access_token调用 API。企微支持简单的 Webhook 推送也支持智能机器人回调的主动回复。应用使用场景场景一智能审批 Agent痛点员工记不住审批路径经常填错表单。Agent 方案用户 机器人说“报销差旅费 500 元”Agent 自动识别意图调用 OA 接口创建审批单并返回“已帮你创建审批单编号 REIMB-001”。场景二知识库问答 Agent痛点公司制度文档分散新人找不到信息。Agent 方案用户问“年假有多少天”Agent 调用 RAG 检索知识库返回“根据《员工手册》正式员工年假为 5 天”。场景三数据查询 Agent痛点业务数据需登录 ERP 系统查询操作繁琐。Agent 方案项目经理问“项目 A 的预算还剩多少”Agent 调用 ERP API 查询并返回“项目 A 预算 100 万已使用 60 万剩余 40 万”。不同场景下详细代码实现架构核心统一消息适配器Adapter Pattern# core/adapters/im_adapter.pyfromabcimportABC,abstractmethodfromtypingimportDict,AnyclassBaseIMAdapter(ABC):IM 平台适配器基类abstractmethoddefverify_signature(self,headers:Dict,body:str)-bool:验证回调签名passabstractmethoddefparse_message(self,body:Dict)-Dict:解析消息体提取关键字段passabstractmethoddefsend_message(self,session_id:str,content:str)-Dict:发送消息passclassDingTalkAdapter(BaseIMAdapter):钉钉适配器defverify_signature(self,headers:Dict,body:str)-bool:# 钉钉签名验证逻辑timestampheaders.get(timestamp,)signheaders.get(sign,)# 计算签名 (timestamp \n app_secret) 的 HmacSHA256# 与实际 sign 对比returnTrue# 简化示例defparse_message(self,body:Dict)-Dict:# 提取钉钉消息return{sender_id:body.get(senderId,),text:body.get(text,{}).get(content,),session_id:body.get(conversationId,),session_webhook:body.get(sessionWebhook,)# 钉钉特有}defsend_message(self,session_id:str,content:str)-Dict:# 使用 sessionWebhook 发送推荐无需 Token# 或调用服务端 APIreturn{code:0}# 工厂类classIMAdapterFactory:staticmethoddefcreate_adapter(platform:str)-BaseIMAdapter:ifplatformdingtalk:returnDingTalkAdapter()elifplatformfeishu:returnFeishuAdapter()# 需实现elifplatformwecom:returnWeComAdapter()# 需实现raiseValueError(fUnsupported platform:{platform})场景一代码钉钉智能报销 Agent# scenarios/dingtalk_reimb_agent.pyimportjsonfromcore.adapters.im_adapterimportIMAdapterFactoryfromcore.llm_clientimportLLMClient# 假设的 LLM 客户端classDingTalkReimbAgent:钉钉报销 Agent完整可运行示例def__init__(self):self.adapterIMAdapterFactory.create_adapter(dingtalk)self.llmLLMClient(modelgpt-4o-mini)defhandle_callback(self,headers:dict,body:dict)-dict:处理钉钉回调入口# 1. 验签ifnotself.adapter.verify_signature(headers,json.dumps(body)):return{code:401,msg:签名错误}# 2. 解析消息msg_infoself.adapter.parse_message(body)user_textmsg_info[text]# 3. 意图识别与槽位填充promptf 用户输入{user_text}请判断是否为报销意图并提取以下字段 - 金额必选 - 事由可选 - 报销类型差旅、日常等可选 返回 JSON 格式 {{intent: reimb, amount: 500, reason: 差旅费, type: travel}} 若不是报销返回 {{intent: other}} llm_resultself.llm.chat(prompt)try:intent_datajson.loads(llm_result)except:intent_data{intent:error}# 4. 业务处理ifintent_data.get(intent)reimb:# 模拟调用 OA 系统创建审批reimb_codeself.create_oa_reimbursement(intent_data)reply_textf✅ 已帮你创建报销审批单\n编号{reimb_code}\n金额{intent_data[amount]}元else:reply_text 我是报销助手请告诉我你要报销的金额和事由例如报销差旅费 500 元# 5. 回复消息resultself.adapter.send_message(session_idmsg_info[session_id],contentreply_text)returnresultdefcreate_oa_reimbursement(self,data:dict)-str:调用 OA 系统创建报销单模拟# 实际应调用 HTTP APIimportuuidreturnREIMB-str(uuid.uuid4())[:8].upper()# 使用示例FastAPI 路由fromfastapiimportFastAPI,Request appFastAPI()agentDingTalkReimbAgent()app.post(/dingtalk/callback)asyncdefding_callback(request:Request):headersdict(request.headers)bodyawaitrequest.json()returnagent.handle_callback(headers,body)场景二代码飞书知识库 AgentRAG# scenarios/feishu_rag_agent.pyfromcore.adapters.im_adapterimportIMAdapterFactoryfromcore.vector_storeimportVectorStore# 假设的向量库classFeishuRAGAgent:飞书知识库问答 Agentdef__init__(self):self.adapterIMAdapterFactory.create_adapter(feishu)self.vector_storeVectorStore(index_path./data/faiss_index)defanswer_question(self,question:str)-str:# 1. 向量检索docsself.vector_store.search(question,top_k3)context\n.join([doc.contentfordocindocs])# 2. LLM 生成答案promptf 基于以下公司制度文档片段回答问题。如果文档中没有相关信息请说“未找到相关规定”。 文档内容{context}问题{question}答案 returnself.llm.chat(prompt)defhandle_message(self,body:dict)-dict:msg_infoself.adapter.parse_message(body)questionmsg_info[text]# 过滤非问答意图ifnotquestion.endswith()andnotquestion.endswith(?):return{code:0,msg:忽略非问答消息}answerself.answer_question(question)returnself.adapter.send_message(msg_info[session_id],answer)原理解释办公 Agent 的核心机制核心特性无状态性Agent 不保存会话状态每次请求独立处理适合云函数部署。异步处理耗时操作如调用 OA API应异步化先回复“处理中”再通过推送通知结果。安全验证必须实现签名验证防止伪造 IM 平台请求。原理流程图以钉钉为例用户 机器人发送消息 ↓ 钉钉服务器 → 回调你的服务端 URL ↓ Agent 验签并解析消息 ↓ LLM 进行意图识别与槽位填充 ↓ 调用内部系统 APIOA/ERP ↓ 通过 sessionWebhook 回复结果环境准备开发环境Python 3.10# 安装核心依赖pipinstallfastapi uvicorn httpx python-dotenv# 钉钉 SDK可选pipinstalldingtalk-sdk# 飞书 SDK可选pipinstallfeishu-sdk# 企微 SDK可选pipinstallwecom-sdk平台应用配置钉钉开发者后台 → 应用开发 → 机器人 → 获取appKey/appSecret设置回调 URL。飞书开发者后台 → 创建应用 → 启用机器人 → 获取app_id/app_secret配置事件订阅。企微企业微信后台 → 应用管理 → 创建应用 → 获取corp_id/corp_secret设置回调模式。实际详细应用企微数据查询 Agent完整可运行示例# examples/wecom_data_agent.pyimportosimportjsonfromfastapiimportFastAPI,Requestfromcore.adapters.im_adapterimportIMAdapterFactory appFastAPI()classWeComDataAgent:企微数据查询 Agent查询项目预算def__init__(self):self.adapterIMAdapterFactory.create_adapter(wecom)# 模拟项目数据self.project_data{项目A:{budget:1000000,used:600000},项目B:{budget:500000,used:300000}}defhandle_callback(self,body:dict)-dict:# 企微回调验证首次需返回 echostrifbody.get(echostr):return{code:200,msg:body.get(echostr)}msg_infoself.adapter.parse_message(body)querymsg_info[text]# 简单规则匹配实际可用 LLMif预算inqueryand项目inquery:forpj_name,datainself.project_data.items():ifpj_nameinquery:remaindata[budget]-data[used]replyf【{pj_name}】预算情况\n总预算{data[budget]}元\n已使用{data[used]}元\n剩余{remain}元breakelse:reply未找到对应项目请检查项目名称else:reply请发送如“查询项目A的预算”格式的消息returnself.adapter.send_message(msg_info[session_id],reply)agentWeComDataAgent()app.post(/wecom/callback)asyncdefwecom_callback(request:Request):bodyawaitrequest.json()returnagent.handle_callback(body)if__name____main__:importuvicorn uvicorn.run(app,host0.0.0.0,port8000)运行结果示例用户输入查询项目A的预算 Agent 回复 【项目A】预算情况 总预算1000000元 已使用600000元 剩余400000元测试步骤与验证单元测试Pytest# test_im_agent.pyimportpytestfromscenarios.dingtalk_reimb_agentimportDingTalkReimbAgentclassTestDingTalkAgent:deftest_intent_parsing(self):agentDingTalkReimbAgent()# 测试 LLM 意图解析test_cases[(报销差旅费 500 元,{intent:reimb,amount:500}),(今天天气怎么样,{intent:other})]forinput_text,expectedintest_cases:# 模拟 LLM 返回resultagent.parse_intent(input_text)assertresult[intent]expected[intent]端到端测试使用 ngrok 内网穿透启动服务uvicorn examples.wecom_data_agent:app --reload使用 ngrok 暴露公网 URLngrok http 8000在企微后台设置回调 URL 为https://xxx.ngrok.io/wecom/callback在企微群中 机器人发送消息验证回复部署场景云函数部署推荐阿里云函数计算FC天然适合钉钉回调无需管理服务器。腾讯云函数SCF适合企微支持 Python 环境。飞书云函数Lark Cloud飞书生态原生支持。服务器部署Docker# Dockerfile FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8000]疑难解答QAQ1回调 URL 验证失败A1钉钉/飞书要求首次验证时返回echostr参数企微要求返回encrypt字段的明文。需在代码中处理验证逻辑。Q2消息发送频率受限A2钉钉机器人默认限频 20 条/分钟。解决方案合并消息内容或使用“应用机器人”而非“群自定义机器人”。Q3如何保证 OA 系统调用安全A3不要在客户端暴露 OA 接口。Agent 应部署在内网或通过 VPN 调用内部系统IM 平台回调需严格验签。未来展望与技术趋势多模态交互支持发送图片、语音、卡片消息Agent 可识别图片中的发票并自动填写报销单。长上下文记忆结合向量数据库Agent 能记住用户的历史习惯如“默认报销项目”。低代码编排通过图形化界面配置 Agent 的意图和回复逻辑非技术人员也能定制。总结开发办公 IM Agent 的核心是**“适配器 意图识别”**。通过统一的适配器层屏蔽平台差异利用 LLM 将自然语言转化为结构化指令再调用后端系统完成业务闭环。本文提供的代码框架已覆盖三大主流平台的核心场景企业可在此基础上扩展更多办公自动化能力让 AI 真正成为员工的得力助手。