去年做企业内部智能助手的时候我一直被一个问题卡住助手能聊天、能总结、能推荐但真要让它“办成一件事”却特别费劲。后来我自研了一套叫 Agent-Reach 的轻量框架核心思路就是把 Agent 的“思考能力”和“触达能力”拆开——你脑子再灵手不够长也干不了活。这套东西现在已经稳定跑在公司内部的几条业务链路上今天就把它的设计思路、实现细节、踩坑记录全部分享出来。这套框架解决的是真实业务里最头疼的“系统孤岛”问题客户邮件来了要手动录入 CRM运营数据要手动汇总成日报工单要手动同步到任务看板。Agent-Reach 做的事就是让智能体能够按统一规则触达这些系统像是给 Agent 装上了一套标准化的“手脚”让它能把想法变成实际业务动作。适合正在做企业内部智能助手、RPA 替代方案、或想把大模型接进业务系统的团队参考不论你是后端开发还是技术负责人都能从里面找到可以直接抄作业的部分。1. Agent-Reach 的整体设计思路把思考和手脚拆开1.1 这个项目到底要解决什么问题先说背景。我们内部有个智能助手项目早期版本的架构很简单大模型负责理解用户意图然后直接调用各种 API。表面看挺顺实际上问题一堆。今天接上了企业微信明天又要接钉钉后天还要接内部 OA每个系统的接口风格完全不同认证方式也五花八门有的是 OAuth2有的是签名密钥有的干脆就是个老掉牙的 HTTP 接口。助手代码里写满了各种 if-else 判断今天加一个系统明天就得改一轮主逻辑维护成本越来越高。更要命的是业务方对助手的期待远不止“回答问题”这么简单。市场部的人说你能不能帮我把客户发来的报价需求自动录入到 CRM再给我推送一条企业微信通知运营部的人说你能不能每天晚上十点自动把各渠道的转化数据拉出来生成一张日报发到群里这些需求本质上都不是“对话”问题而是“触达”问题——让 Agent 能安全、稳定、可控地操作外部系统。Agent-Reach 的核心设计就是从这个痛点出发的。我给它的定位不是一个大模型框架而是一层“触达中间层”。大模型只负责输出意图和决策参数真正去调用外部系统的动作全部由这一层完成。这样做的好处非常直接大模型不需要关心某个系统的接口格式是什么、密钥怎么传、失败怎么重试它只需要说清楚“我要做什么”剩下的脏活累活全部被触达层接管。这就像给一个人配了个专职助理——你不用管助理是坐地铁还是打车去办事你只需要告诉他要办什么最后结果能带回来就行。模型不再兼任“思考者”和“执行者”两个角色而是专注思考执行能力被沉淀成一个独立的、可复用的基础设施。1.2 为什么不用现成的 Agent 框架非要自己搭市面上的 Agent 框架我调研过不少比如 LangChain、AutoGen 这类主流的工具。它们的优势很明显生态丰富、组件多、上手快。但我最终没有直接采用它们作为 Agent-Reach 的底座原因主要有三个。第一个原因是“重”。这些框架往往自带一套完整的内存、工具调用、任务编排体系而我们内部系统连了一堆自研的存量平台很多是十几年前的老系统接口文档都不全拿标准的框架去适配反倒要大改。我只需要一个极简的“意图到动作”的通道杀鸡用牛刀反而是负担。第二个原因是“黑盒”。这些框架把很多东西封装得太好可出了问题你也很难定位。在实际生产环境里外部系统调用失败是家常便饭我需要的是每一步都可观测、可追踪、可重放而不是一个“魔法黑箱”出了问题只能重启进程。第三个原因是“控制权”。企业内部系统涉及权限、审计、风控我不希望 Agent 在自主执行的时候绕过这些规则。自研一层薄薄的触达层反而可以完全掌控每一次外部调用的认证、授权和审计日志出事了知道是谁、在哪一步、调了哪个系统、传了什么参数。所以我决定自研 Agent-Reach它不是一个“大而全”的 Agent 平台而是一个“小而专”的触达基础设施。你要理解它的设计哲学不抢框架的活不抢模型的大脑只做最脏最累的系统连接器。这样一来前面的 Agent 可以是任何框架后面的系统也可以是任何系统中间这层反而成了最稳定、最值得沉淀的部分。2. 核心机制拆解触达层到底怎么工作2.1 三层结构决策、路由、执行Agent-Reach 的内部逻辑被我清晰地分成了三层决策层、路由层、执行层。三层各司其职任何一层出问题都不会拖垮整个链路。决策层面对的是大模型产出。我规定了大模型输出的统一格式不要求它直接给出“调用哪个 API”这种具体指令而是要求它输出一个标准化的意图对象。比如意图是“创建任务”字段可能包括任务标题、截止日期、优先级、负责人。这个意图对象是平台无关的大模型不需要知道公司用的是哪个任务管理系统。路由层拿到意图对象后开始干活。它维护着一张触达路由表相当于整个系统的手脚经络图。每个外部系统在路由表里注册了一组“能力描述”比如 CRM 系统提供“创建线索”“更新客户”“查询合同”任务系统提供“建任务”“改状态”“归档任务”。路由层根据意图对象匹配对应的能力项再把意图参数映射成对应系统的输入参数。执行层是最底层。它负责真正发起 HTTP 调用、处理认证、解析响应、按需重试。执行层的每个环节都会输出结构化日志包括请求时间、耗时、状态码、响应摘要。这些日志是后续排查问题的主要依据。如果调用失败执行层会根据可以配置的重试策略进行有限次数的重试重试仍然失败则把错误信息原样返回给路由层再由路由层决定是否抛给上层 Agent。这里有一个我特别坚持的设计无论哪一层失败都不能让 Agent 自己去猜测发生了什么。所有错误都会被翻译成统一的错误码和可读信息再原样返回给用户或上层流程。这个设计在实际项目中救了我无数次——你知道那么多系统每个系统的报错风格都不同有的返回 XML有的返回 JSON有的干脆就给你一个 502。统一错误翻译机制让排查时间至少缩短了一半。2.2 触达路由表每个系统都是一组“动词”路由表是整个 Agent-Reach 的灵魂。它的设计灵感其实很像 RESTful API 的语义化设计——每个外部系统不是被暴露为一堆杂乱无章的接口地址而是被抽象成一组“动词”。以我们的 CRM 系统为例它在路由表里的注册信息大致长这样系统标识是crm提供的能力包括create_lead、update_lead_status、query_customer。每个能力对应一个执行器函数函数内部封装了具体的 HTTP 调用、参数组装和响应解析。路由表只暴露“做了什么”不暴露“怎么做的”这让上层 Agent 的工作变得异常简单。路由表还有一个重要的作用参数映射。同一个字段在不同系统里的名字完全不同。比如“截止日期”在 CRM 里叫due_date在任务系统里叫expire_time在 OA 里叫deadline。如果让大模型去学习所有这些命名规则不仅浪费 token还容易出错。路由表把这些差异全部屏蔽掉了大模型输出的标准化字段会被映射成各个系统的原始字段名这一层像一个“通用翻译器”。路由注册采用的是声明式配置。每新增一个外部系统团队只需要写一个配置文件声明系统提供哪些能力、每个能力的入参出参、需要什么权限。不需要改任何上层逻辑。我们团队加入一个新的业务系统从开始开发到跑通最小链路大概只需要两天时间这在以前是不可想象的。2.3 统一上下文盒别再让记忆失联Agent 类系统有一个老毛病多轮对话上下文太长容易“迷失自我”。尤其当 Agent 需要连续操作多个系统时它得记住自己在第一步干了什么、第二步拿到了什么结果、第三步该怎么变化。如果这些中间结果散落在各个阶段里要么相互覆盖要么被截断。Agent-Reach 里我设计了一个叫“上下文盒”的东西英文叫 Context Box你可以把它理解成一次任务执行期间的公用便签本。整个任务从头到尾的所有关键中间结果都会被写入这个上下文盒并且每个结果都有唯一的索引标识。上层 Agent 在需要决策时可以从上下文盒里精准取用某一段信息而不是把所有历史都重新塞给模型。比如在一次“客户邮件处理”流程中第一步从邮件里提取出客户公司名和需求第二步根据公司名在 CRM 里查到客户编号第三步在任务系统里创建任务并把客户编号作为关联字段。如果没有上下文盒第三步的大模型就得重新回忆或重新读取第一步的邮件原文和第二步的查询结果既浪费 token 又容易出错。有了上下文盒之后第二步的执行器直接把“客户编号CL-2024-0801”写入盒中第三步执行器直接引用这个索引干净利落。上下文盒的设计细则也很关键。存储在里面的数据必须带上时间戳和执行器标识这样即使后面出了问题需要回放我们也能知道这个数据是谁在什么时间写入的。盒子的存储我会根据任务规模选择小任务直接放内存大任务或长周期任务放 Redis避免占用太多进程内存。到任务结束时整个上下文盒的生命周期也结束不会留下脏数据也不会产生内存泄漏。3. 实操过程跑通一条完整的业务链路3.1 我选的场景一封邮件引发的任务闭环理论讲了一堆不如直接上一段实操记录。我在开发 Agent-Reach 时用的第一个测试场景是“客户邮件自动触发任务创建”这也是我认为最容易理解、也最实用的一条链路一封客户邮件进来自动提取关键信息录入 CRM创建跟进任务最后给业务员推送通知。整个流程分四段。第一段是邮件网关收到新邮件第二段是大模型读取邮件内容提取客户公司、联系人、需求摘要、紧急程度第三段是 Agent-Reach 路由层匹配“录入 CRM”和“创建任务”两个动作并依次执行第四段是企业微信通知业务员。表面上这个流程可能很多人觉得“不就是调几个 API 嘛”但当你真正做下去就会发现每个环节都有大量的边界问题需要处理。我没有让 Agent 一次性完成所有步骤而是严格控制“一步一确认”。每一步执行完都要把结果反馈回决策层决策层确认无误后才发下一步指令。这样做虽然会损失一些速度但换来的是极强的可控性。尤其是第一版上线的时候业务方最怕的就是 Agent 自作主张把事办砸了。你宁可多花 0.5 秒确认一次也别等到事后再去挽回。3.2 配置路由和执行器的具体过程先看路由表的配置文件这是整个接入过程中最典型的一段配置我简化了一下routes: - system: crm capability: create_lead executor: crm_create_lead_executor parameters: company_name: source: context_box key: extracted.company_name contact_person: source: context_box key: extracted.contact_person requirement_summary: source: context_box key: extracted.requirement_summary required_permission: crm_lead_write retry_policy: max_retries: 3 backoff_seconds: [1, 5, 15]这段配置的意思是路由表中注册了一条能力叫“在 CRM 中创建线索”对应的执行器是crm_create_lead_executor入参从上下文盒中按指定 key 取值。如果出错了最多重试三次间隔分别是 1 秒、5 秒、15 秒。这是很典型的声明式配置风格。真正执行逻辑都封装在执行器里例如创建线索的核心代码我用 Python 伪代码来描述关键部分def crm_create_lead_executor(params): token auth_manager.get_token(crm, permissioncrm_lead_write) payload { name: params[company_name], contact: params[contact_person], description: params[requirement_summary], source: agent_reach, } resp http_client.post( urlhttps://crm.internal.example.com/api/v1/leads, headers{Authorization: fBearer {token}}, jsonpayload, timeout15, ) if resp.status_code ! 201: raise ExecutorError( codeCRM_CREATE_LEAD_FAILED, messagefCRM 返回非预期状态码: {resp.status_code}, raw_responseresp.text, ) lead_id resp.json()[data][id] context_box.set(crm.lead_id, lead_id, ttl3600) return {lead_id: lead_id}这里面的几个细节值得展开讲讲。token 管理我单独封装了一层执行器不会自己保管密钥而是统一向认证中心申请临时凭证。凭证有过期时间通常设置为一小时。为什么要这么做因为如果执行器散落各处各自保管自己的密钥一旦密钥泄漏排查范围根本没法控制。集中管理后密钥轮换只要在认证中心改一次所有执行器立即生效。另外请注意代码里明确设置了超时时间这是很多第一次写集成代码的人会忽略的重要参数。外部系统一旦崩溃或假死如果没有超时机制整个 Agent 线程会被活活卡住。我们线上环境发生过不止一次这种事故加了超时之后单次调用最长不超过 15 秒整个任务再慢也能在可控时间内结束。3.3 幂等设计防止重复执行把订单发两遍说到实操里最有价值的设计教训我首推“幂等性设计”。外部调用面临的最隐蔽的坑就是——请求确实发出了但响应超时了。这时你咋办重试吧有可能系统已经创建了两条线索不重试吧又可能这条线索根本没建上。Agent-Reach 的解决办法是给每个外部调用生成一个全局唯一的幂等键跟着请求一并发给目标系统。目标系统支持幂等的情况下相同幂等键的重复请求不会造成重复创建。我在配置里给每条路由增加了idempotency_key的字段它的值来自任务 ID 加操作序号idempotency: key_source: task_id route_order header_name: X-Idempotency-Key实测下来效果非常明显。以前邮件处理流程上线后客户反馈说同一条线索在 CRM 里出现了两条我们排查了半天发现就是五秒超时后自动重试导致的。加上幂等键之后再怎么重试系统里都只有一条记录。这个设计一定要在最初就做进去否则后面系统已经积累了重复数据清洗的成本高到你怀疑人生。3.4 现场记录一次全链路联调的运行日志这里放一段当天联调时执行器打出来的日志摘要你可以看到每一步都留下了可追踪的痕迹[2024-11-20 10:02:01] ROUTE matched: crm.create_lead [2024-11-20 10:02:01] CONTEXT read: extracted.company_name 观澜科技 [2024-11-20 10:02:02] AUTH acquired: crm token valid_for3600s [2024-11-20 10:02:03] HTTP POST crm/api/v1/leads status201 elapsed620ms [2024-11-20 10:02:03] CONTEXT write: crm.lead_id 77821 [2024-11-20 10:02:04] ROUTE matched: task.create_task [2024-11-20 10:02:04] CONTEXT read: crm.lead_id 77821 [2024-11-20 10:02:05] HTTP POST task/api/tasks status201 elapsed310ms [2024-11-20 10:02:05] CONTEXT write: task.task_id T-2024-1102-05 [2024-11-20 10:02:06] NOTIFY sent: wecom group业务一组这份日志看起来简单其实含金量很高。它完整记录了“路由匹配—上下文读取—认证获取—外部调用—上下文写入—下一步路由匹配—再次调用—通知发送”的全过程。每行日志都有精确的时间戳可以精确分析瓶颈在哪。比如这条链路里 CRM 调用花了 620 毫秒任务系统花了 310 毫秒通知发送只花了几十毫秒那么整体性能瓶颈很明确地指向 CRM 系统。后面优化时可以针对性地去查。日志的另一个价值体现在用户投诉时。业务方反馈“有一条数据怎么没同步过去”我只要拿到这个任务的 ID在日志系统里按 ID 一查立刻就能看到卡在哪个环节、报了什么错、重试了没有、最终给用户的错误信息是什么。不用再像以前那样人肉翻各个系统的操作日志效率提升是压倒性的。4. 常见问题与排查技巧实录4.1 高频问题速查表这一节我整理了一份高频问题速查表都是 Agent-Reach 运行半年以来真实遇到的每一类我都附上了排查思路和解决方案。问题现象根本原因排查方法解法Agent 长时间无响应外部系统调用未设置超时查看执行日志中有没有「请求挂起」所有执行器强制要求设置超时时间建议 10-15 秒任务重复创建响应超时后触发了自动重试检查目标系统里是否有相同时间戳的重复记录增加幂等键并确认目标系统真的支持幂等中途报 401 凭证失效长任务执行过程中凭证过期查看认证日志中 token 的签发时间与实际执行时间执行器内增加「凭证即将过期时自动刷新」的逻辑大模型输出格式不稳定提示词对输出格式约束不足查看决策层日志确认模型输出是否漏字段改用结构化输出约束比如 JSON Schema 校验某些系统偶发超时目标系统单点故障或负载高对比不同时间段的调用耗时分布配置重试策略并把故障系统从路由表中暂时摘除这张速查表本质上是排查手册的精简版。我在团队内部把它贴在了文档首页新人上手时遇到问题先查表大概率能解决八成问题剩下两成再根据日志深挖。它不是什么高深理论但实际价值非常高。4.2 定问题的一招链路追踪标识分布式系统排查问题最怕的是上下文丢失。你说你调了一次 CRM我说我发了一条企业微信通知两边各自都有日志但怎么证明它们是同一次任务里的操作如果不做关联排查一次跨系统问题可能要花掉半天。Agent-Reach 在任务启动时生成一个全局唯一的追踪标识叫trace_id。这个标识会随任务的生命周期传递到每一个执行器、每一次外部调用。所有日志都必须带上这个trace_id日志中心按它聚合之后你就可以看到一次任务在整个生命周期里的完整轨迹。这个设计真的非常值得我安利一下。我见过太多团队做了好几年系统集成查一个问题还得跑到各个系统的后台去手动对照时间戳痛苦得不行。有了统一的trace_id所有日志集合成一条完整链路从前端邮件输入一直到后端通知发送每一步耗时和出错点都在一条线上清晰可见。这套东西做起来成本极低收益却极高强烈建议所有做类似项目的团队都搞一个。4.3 给折腾过这个方向的同行几句实话最后说说心里话。Agent-Reach 这个方向做下来我有几点比较深的体会与你分享。第一不要迷信“一个 Agent 解决所有问题”。真实业务里系统之间的差异远比模型能力更消耗精力。你不把触达这层做扎实再聪明的大模型也发挥不出价值。Agent-Reach 的定位就是承认现实模型可以随时换但你的业务系统往往十几年都换不了触达层的价值恰恰在于弥合这种代差。第二稳定性比华丽更重要。我见过有些团队把 Agent 做得非常炫酷但一次全网抖动就能让整个 Agent 服务全线崩溃。Agent-Reach 的重试策略、幂等设计、超时控制全部都是“不太好展示但事关生死”的基础功夫。如果预算有限优先保稳定性再考虑更多炫酷功能的扩展。第三后期扩展不必推倒重来。Agent-Reach 现在的设计完全可以往更多场景复制比如把邮件网关换成企微机器人把 CRM 换成财务系统把任务看板换成项目甘特图只要路由表重新配置执行器重新写一层薄薄的适配即可。我不需要改决策层、也不需要改上下文盒整个迁移成本非常可控。根据我个人实际操作下来的感受Agent-Reach 最值钱的不是某段代码而是“把系统和模型真正解耦”的这套思路。它让 Agent 不再被某一个具体业务系统绑架也让系统的每一次触达都清清楚楚、可追溯。你如果在做类似的事情可以从最小的场景开始——选一条业务链路画出大致的意图模版把路由层和执行层跑通你就会发现Agent 的能力边界一下子被拓宽了不少。