我们部门在半年前接手了一套多智能体协同项目名字就叫 Agent-Reach。最开始我以为只是做一个 Agent 之间的消息推送工具结果越深入越发现这里面的坑全在“Reach”这个词上——Agent 之间怎么发现彼此、怎么找到对的节点、怎么把上下文完整递过去每一步都能把自研方案玩崩。折腾了大半年我把整个项目的设计思路、上线过程、踩坑记录整理成这篇东西希望能帮到同样在搞多智能体系统的人。1. 先聊清楚智能体“触达”这件事难在哪1.1 三台AI各干各的为什么连不上过去三个月里我至少被五家不同规模的公司问过同一个问题我们已经有客服机器人、质检助手、知识库问答三个 AI 在线上跑能不能让它们互相调用问的人通常觉得这就是“加个 API 的事”但真上手就发现根本不是。问题在于这三个系统可能来自不同的技术团队用了不同的协议、不同的部署环境甚至连“某个商品的问题”这种基础语义各自的数据库里字段都不一样。A 客服机器人要查库存得知道找哪个服务、传什么参数、怎么处理超时B 质检助手又需要把录音转写结果推给 C 知识库去匹配知识条目。链条一长两两对接的复杂度是指数级上涨的。这种状态我称之为“智能体孤岛”——每个单体 Agent 都有能力但彼此之间没有可靠的触达路径。你没办法像调用普通函数一样去调用另一个 Agent因为它不是你的代码它的身份、接口、上下文都是独立的。Agent-Reach 这个名字的灵感也来自这里我们要做的不是让它们“能聊上天”而是让任何一个 Agent 都能以最低成本、最可靠地“触达”到它需要的另一个 Agent。1.2 Agent-Reach 的定义它是一条连接层而不是聊天框架项目立项的时候产品经理给了一版很漂亮的 PPT说要做“多智能体大脑中枢”。我看了半天发现他想要的是把所有 Agent 聚到一个聊天群里让它们自由对话。这个方向我们讨论后直接砍掉了——不是不好而是不现实。真正的多智能体协同不是大家坐在一起开会而是各司其职的工序衔接。客服机器人完成履约、质检机器人完成评分、知识库完成内容查询它们需要的不是一张聊天室而是一条低延迟、高可靠、语义可达的“总线”。就像城市里的交通系统重点是路网让一辆车能从 A 点准确到达 B 点而不是所有车都停在一个广场上互相喊话。Agent-Reach 的定位是连接层。它不接管 Agent 内部的业务逻辑不做统一的大模型推理只负责三件事让 Agent 可被发现、让消息可被路由、让上下文可被传递。这几点听起来简单实现起来却几乎踩遍了分布式系统里的所有经典坑。1.3 为什么我不建议一上来就搞“万能协议”项目中期技术群里有个同事提议干脆定义一套统一的 Agent 通信协议规定所有接入系统必须用同一种格式问题不就解决了吗这个想法非常诱人因为看起来能一劳永逸。但我们冷静算了一笔账发现推行成本高得吓人。我们接入的六个业务 Agent分别跑在 Java 的 Spring Boot、Python 的 FastAPI、Node.js 的 Express 上数据格式有 JSON、有 XML、甚至有老的 SOAP 接口。逼它们全部改协议意味着每个业务方都要安排一到两周的改造工期而且改完还得重新测试原有功能。当初我们做项目挑战赛时统计过光是把消息格式统一这一项涉及的改造点就有 80 多个。Agent-Reach 没有走这条路。我们选择的是在外层做协议适配——每个 Agent 只需要一个轻量级的接入代理跑一段我们提供的 SDK 或者其他轻量级适配服务把内部的消息格式翻译成统一的路由格式业务代码几乎不用动。这个决策后来被证明是项目能按期落地的关键。任何一个不做统一标准、却试图让异构系统互通的项目最终都会在“改造量”和“兼容性”之间被反复拖累。2. 核心架构是怎么回事注册、寻址、路由、状态2.1 统一身份解析层让每个 Agent 都有“门牌号”如果你做过微服务一定熟悉服务注册与发现。Agent-Reach 的第一层本质上就是“给 Agent 发门牌号”。每个接入的 Agent 上线时会向协调节点注册自己的身份信息包括 Agent ID、能力描述、健康状态、当前地址。但这里有一个和普通微服务很不一样的地方普通微服务的地址是固定的 IP 或域名而 Agent 的能力描述是动态的、语义化的。比如“商品问答Agent”的能力标签可能是product.query、product.detail而不是一个 URL。这意味着寻址不能只看“它在哪”更要看“它能干什么”。我给你们一个实际注册配置的例子这是接入一个商品助手的片段agent: id: product-assistant-01 display_name: 商品助手 capability: - product.query - product.detail - inventory.check transport: type: http endpoint: http://192.168.3.18:9040/invoke ttl: 60每次 Agent 心跳续约协调节点就更新它的存活时间。注册表里存的不只是“谁活着”还有“谁能干什么”。这样一条消息进来时我们不是直接发给某个 IP而是先问协调层谁具备product.query能力然后拿到候选清单再做路由。2.2 语义路由触达不是发广播是找对窗口很多人对 AI Agent 之间的通信有个误解以为发起方把消息群发出去所有 Agent 都看一眼谁合适谁来答。这在只有两三个 Agent 的时候确实可以用但一旦规模到十个以上广播风暴会立刻教你做人。Agent-Reach 的路由层用的是语义路由。一条消息进来先做能力匹配再结合当前各 Agent 的负载、健康状态、上下文关联度加权打分选出最优接收者。整个过程分成两步能力层匹配消息里携带目标能力标签比如inventory.check注册表里筛选出所有声明了这个能力的 Agent。实例层选择在候选实例里按负载最小、最近成功率高、上下文命中度高等维度打分选最高分的那一个。这一步很像你在地图 App 里打车。你输入目的地目标能力平台筛出附近的空闲司机可用的 Agent 实例再根据评分派单。你不会直接给某个司机打电话平台帮你完成了“找谁”这个过程。具体路由决策的时候我们内部的权重是这样的能力匹配占 30%健康状态占 25%上下文关联度占 20%负载情况占 15%响应历史成功率占 10%。这套权重不是拍脑袋定的是跑了一个月线上数据后回归出来的。早期我们只看能力和负载结果经常出现消息发给一个“健康但正在跑大量任务”的 Agent导致排队时间暴涨。后来逐步打磨把响应历史成功率加进来之后整体触达成功率从 91% 提到了 98% 以上。2.3 共享状态与上下文投影连接了还得“接得上话”触达到不代表能接上话。这是 Agent-Reach 踩得最深的一个坑。最初我们的实现很简单把 A 的消息转发给 BB 返回结果A 再引用。但真实业务里A 和 B 协同完成一个任务往往需要共享同一份上下文。举个例子用户问“这款手机有蓝色 256G 吗”客服 Agent 需要把它拆成商品查询和库存查询两个子任务分发给两个不同的 Agent然后聚合结果。这里的问题不是消息传不传得到而是库存 Agent 需要知道“蓝色、256G、这款手机”这些上下文它的回答才有意义。如果不共享上下文你只能每次把用户原话塞进消息里可一旦对话有连续多轮上下文会越带越大最终把消息体撑爆。Agent-Reach 的解决方案是“上下文投影”。我们维护一个分布式上下文存储区每个任务关联一个上下文节点各 Agent 通过路由消息时附带的 context_id按需拉取属于自己的那部分上下文。这很像你去办事大厅窗口工作人员不需要你把全部材料都背下来他们只需要在系统里查到你的档案编号然后取走本次业务需要的几份材料。上下文投影还顺手解决了一个性能问题避免大段历史文本随消息体到处复制。A 发给 B 的不是几十 K 的对话记录而是一个上下文 ID 和一串精简的引用路径。B 收到后再按需加载既不丢信息也压低了带宽。我强烈建议你们在设计类似系统时把“上下文最小粒度匹配”当作核心指标来考虑能省掉后面一大堆性能优化的活儿。3. 主链路是怎么打通的从注册到一次成功触达3.1 一次消息传递的完整时序讲完架构我把主链路里一次完整的消息触达过程写出来。这是你理解 Agent-Reach 最小工作方式的钥匙。Agent A客服助手发起一个inventory.check能力请求。请求发往 Agent-Reach 的协调节点消息体里只带能力标签和 context_id。协调节点查注册表筛选出 3 个具备inventory.check能力的候选 Agent。语义路由模块按权重打分选出得分最高的 Agent B。Agent-Reach 把请求转发给 Agent B 的接入代理并附上 context_id 的访问凭证。Agent B 从上下文存储区加载本次需要的商品信息。Agent B 执行库存查询返回结果给协调节点。协调节点把结果回传给 Agent A并更新上下文节点的状态记录。这整个过程消耗多少时间实测下来在一次本地网络环境里常规业务请求的端到端延迟在 40 到 80 毫秒之间。放到跨地域的云环境会到 150 毫秒上下。这个延迟对于多数 Agent 场景都能接受因为重点不是实时交互而是任务分发和结果聚合。3.2 最小部署先把单机跑起来Agent-Reach 的单机部署很简单一条 docker-compose 就能起一套协调节点 注册表 上下文存储的最小环境。我给你们看下最基础的 compose 文件很多配置项我加上了注释version: 3.8 services: coordinator: image: agentreach/coordinator:0.9.2 ports: - 8500:8500 environment: AR_CLUSTER_MODE: standalone AR_REGISTRY_BACKEND: memory # 单机用内存注册表即可 AR_ROUTE_AFFINITY_DEFAULT: capability,health,context context-store: image: agentreach/context-store:0.9.2 ports: - 8600:8600 volumes: - context_data:/data environment: AR_TTL_DEFAULT: 1800 # 上下文默认保留30分钟 api-gateway: image: agentreach/gateway:0.9.2 ports: - 8700:8700 depends_on: - coordinator这套配置我用了很久稳定得很。你如果想做 POC概念验证直接照抄这一套就能起来。注意AR_TTL_DEFAULT这个值我强烈建议不要设太短。早期我设成 5 分钟结果上下文经常在任务还没跑完时就过期整个链路莫名其妙失败排查了半天才发现是上下文被回收了。3.3 我最想提醒的一个反直觉配置超时与重试很多人在配置 Agent 触达的时候会把超时时间压得很低觉得这样能让系统响应快拖沓的调用早失败早完事。这个思路在普通 API 网关里没毛病但在多智能体场景里会坑死人。因为一个请求可能要经过“路由匹配、上下文加载、Agent 内部推理或查询、结果回传”四个环节其中 Agent 内部推理环节特别耗时间。尤其是大模型 Agent一次推理就可能要两三秒。你把超时设成 500 毫秒等于让所有大模型 Agent 都永远超时。我最终调出来的超时策略是这样的普通查询类 Agent超时 2 秒最多重试 0 次推理型 Agent超时 5 秒最多重试 1 次长任务型 Agent超时 30 秒走异步轮询而不是同步等待。这里的难点在于“重试”。同步重试一次容易造成重复执行——库存查询还好扣款之类的操作要是让同一个 Agent 收到两次指令就会出大事。所以我们给每条消息都加了全局唯一的 request_idAgent 侧在接入代理里做了幂等处理。你拿到任何一套类似系统时第一时间一定要检查它的幂等性设计。我见过不止一个项目因为没有全局 request_id重试机制上线后直接导致线上重复执行了订单操作那个场面真的是灾难。3.4 路由失败后的降级路径比主路径更重要做 Agent-Reach 的时候我们把大量精力花在主链路的优化上但后来让我们在领导面前保住颜面的其实是降级路径。所谓降级路径是当首选 Agent 路由失败时系统自动执行的备选方案。我们的降级顺序是首选 Agent 失败 → 自动切换到同能力标签的次优 Agent。同能力无可用实例 → 检查是否有“通用处理”类 Agent 可以接单。仍然失败 → 把消息转入挂起队列同时触发注册表的健康检查。健康检查发现某 Agent 失联 → 将其标记为离线触发替代实例扩容。这套降级策略最大的价值是让线上系统在面对 Agent 崩溃时不用人工介入。有次我们一个库存查询 Agent 因为被任务压垮而失联路由层在 4 秒内自动把请求转给了同能力的另一个实例业务侧几乎没感知到问题。如果当时没有这套降级逻辑用户就会在 App 上看到“系统繁忙”那又是另一个客服电话爆炸的夜晚了。4. 把它放进真实业务三种典型接入姿势4.1 客服 质检 知识库的三 Agent 联动Agent-Reach 最典型的落地场景是三个不同类型 Agent 的串行协作。我用一个实际业务来拆开讲。用户在线咨询“商品 A 什么时候发货”客服 Agent 收到问题后先分工查询订单状态的任务发给订单 Agent查询最新公告的任务发给知识库 Agent。这个过程里订单 Agent 和知识库 Agent 不需要知道用户是谁它们只需要按能力标签接单。整个链路在 Agent-Reach 内部表现为一个 DAG有向无环图式的任务编排。我们当时用 Python 写了个简单的编排函数大致长这样reply await orchestrator.run(customer_service.task_query, { intent: shipment_query, context_id: current_context, steps: [ {action: order.query, param: {order_no: order_no}}, {action: kb.article.query, param: {keyword: shipment_policy, limit: 3}}, ], fallback: kb.article.query, })这个编排函数的好处是任何一步失败了可以走 fallback 或挂起重试而不是把整个流程丢弃。三 Agent 联动上线后客服场景的首次响应时间从原来的 20 秒降到了 5 秒以内大量重复性的“查发货时间”问题被自动消化。4.2 开发流水线里 Agent 与 Agent 交接第二个场景是开发运维的 CI/CD 流水线。我们有一个代码生成 Agent 和一个部署 Agent。传统做法里代码生成 Agent 产出一个压缩包交给人工去部署。通过 Agent-Reach 后两者可以直接交接。代码生成 Agent 完成后会调起一个deploy.execute能力请求附上构建产物地址、环境标签等上下文。部署 Agent 收到请求后从共享存储里拉取构建包执行部署脚本然后返回部署日志。整个过程里代码生成 Agent 根本不需要知道部署 Agent 的服务器地址或部署方式它只是“发出一个语义请求”剩下的交给路由层。这个小改造让我们的发布耗时从 18 分钟压到了 6 分钟左右。不要小看这个数据在发布频繁的部门每次省 12 分钟一天 20 次发布就是省了 4 个小时的人机等待时间。4.3 与外部系统对接不能只看到 Agent还有一个很容易被忽视的场景Agent-Reach 不只是 Agent 之间的通道也可以作为 Agent 与外部业务系统的桥接层。比如我们要让客服 Agent 能查真正的 ERP 库存不可能让 ERP 系统去部署一套 Agent-Reach SDK。我们是在 Agent-Reach 旁边加了一个“适配器 Agent”这个 Agent 本质上是个翻译官——它暴露一个erp.inventory.query能力标签内部却是封装了对 ERP 系统的 HTTP 调用。这个设计让我明白了一个道理Agent-Reach 的“触达”不局限于智能体之间它完全可以延伸到任何你能抽象成“能力”的服务上。你甚至可以把一个老旧系统的 SOAP 接口包装成一个 Agent轻松接入新体系而不必逼着老系统团队做任何改造。5. 我踩过的几个坑路由风暴、僵尸注册、上下文爆炸5.1 路由风暴两个 Agent 互相踢皮球第一个让我印象深刻的线上事故是客服场景里两个 Agent 陷入了请求循环。起因是客服 Agent 做起重试超时后把同一个请求重新路由给了另一个客服 Agent而那个 Agent 也超时反过来又把请求传了回来。仅仅十几分钟协调节点就累积了几万个重复请求数据库连接被打满整个集群响应延迟暴涨到几十秒。排查过程很有意思。我们的第一反应是“网络问题”看了半天带宽和连接数都没发现异常。后来我把一段时间的路由日志按 request_id 做了聚合才发现同一个 ID 在 20 秒内被路由了 300 多次。根因是重试策略里没有做“跳数限制”也就是一条消息最多能经过多少个 Agent。修复方式很简单在路由消息头里加一个max_hop字段默认 5。每经过一个 Agent计数器减一减到 0 就强制终止并把消息丢入死信队列。这个字段我强烈建议从第一天就加上它像是一张安全网能兜住各种意想不到的死循环。5.2 僵尸注册扩容之后单体失联第二类高频故障是“僵尸注册”。Agent 正常上线时注册到协调节点但如果进程被 kill 而没来得及反注册协调节点会把这个 Agent 长期视为“健康”。尤其是我们当时用 Kubernetes 按流量扩容旧 Pod 死了新 Pod 还没注册完成协调节点依然把流量发给旧 Pod于是大量请求直接超时。这个问题的核心在于注册表里的健康状态不可信。后来我们在注册表之外增加了“探活链路”协调节点每 10 秒主动探测一次 Agent 的接入代理连续 3 次失败就地标记为“可疑”再连续 2 次失败就标记为“离线”并踢出路由池。这里有个经验不要依赖 Agent 主动上报的心跳心跳只能证明“我还活着”不能证明“我还能干活”。主动探活虽然会消耗一点资源但在分布式环境里带来的稳定性收益是巨大的。我把探活间隔从默认的 30 秒调到 10 秒触达成功率又往上走了一些。5.3 上下文爆炸一次会话拖垮整个存储第三个大坑是上下文存储的容量失控。我们的上下文 TTL 设置过短时会有过期问题但设置到 1800 秒后反而出现了新问题存储区被大量长时间未结束的会话撑爆了。原因是很多用户和客服 Agent 的对话不关闭上下文节点一直不释放数据越堆越大。后来我们设计了一套“会话分片 滚动过期”的逻辑。一个长会话可以被拆成多个片段每个片段独立设置过期时间只要对话中止下一个片段就不再创建每隔 60 秒跑一次清扫把没有活跃引用的片段直接删掉。这套改造上线后上下文存储的使用量下降了 40% 左右。你如果自己搭类似系统一定要提前想清楚上下文生命周期管理别等着出问题再补。存储的清理策略最好在设计文档阶段就写清楚。问题根因修复路由风暴重试无跳数限制加 max_hop 上限僵尸注册心跳不可信主动探活 状态迁移上下文爆炸TTL 与管理粒度不合适会话分片 滚动过期5.4 排查触达问题的一条通用思路最后分享一个排查经验。Agent-Reach 这类的连接层出问题最忌讳的是从一面一头扎进去。我们自己的排查顺序是先看路由日志消息有没有被路由出去选中的是哪个 Agent为什么是它这一层能覆盖 60% 的问题。再看注册表状态目标 Agent 是否健康是否还在路由池里有时候问题没那么玄就是 Agent 没心跳了。再看上下文存储如果消息一直路由失败或者结果对不上多半是上下文没带上。最后看业务日志确认目标 Agent 内部到底有没有收到请求、执行结果是什么。这个顺序特别适合新手。因为连接层的问题 90% 是“没找到合适的 Agent”或者“找到了但没送达”而不是业务方“代码写得不对”。照着这个顺序排查一小时能定位绝大多数故障。6. 还没完安全边界与后续扩展6.1 触达能力越强越要管住权限Agent-Reach 把 Agent 之间的触达变得如此容易之后一个副作用是安全边界也变得更模糊。以前外部系统要调我们某个 Agent 的接口得经过一层网关、做鉴权、限流。现在任何接入的 Agent只要注册表里可见理论上都能发起触达请求。我们给 Agent-Reach 加了三层安全控制第一层API Key 鉴权每个接入 Agent 一个独立的 Key。第二层能力标签级权限比如库存 Agent 只能被客服域的 Agent 调用不允许被其他域调用。第三层调用频次配额单个 Agent 对另一个 Agent 的调用不能超过每秒多少条。这三层配置起来不算复杂但能让你在晚上睡得安稳。特别是第二层一定要做。否则你有可能发现某个测试 Agent 因为能力标签写得太宽变成了全网通吃的“特权账号”那是非常危险的。6.2 可观测性建设触达链路可视化我们在项目后期还做了一件看起来不起眼但救过命的事给每个触达请求生成了 trace_id并把整个链路的日志、耗时、上下文变更汇总到一套追踪看板里。看板上能看到一次客服请求经历了哪些 Agent、每个环节耗时多少毫秒、哪一步出现了重试。这样定位问题变得非常直观不用再翻各种日志去拼线索。有一次客户报障说“响应变慢了”我从看板上一眼看到延迟主要卡在知识库 Agent 的大模型推理环节而代理层触达的部分只有 80 毫秒。这个信息直接决定了后续优化方向是给知识库 Agent 换更快的小模型而不是去调 Agent-Reach 的路由超时。6.3 从 Agent-Reach 到 Agent Mesh最后说说这个项目未来的方向。Agent-Reach 目前解决的是“点对点触达和简单编排”但真正复杂的业务场景需要的是“网状互联”——多个 Agent 之间形成动态协作网络任务可以在网络里自动流转、委派、反馈。这有点像从城际公路网点到点的通道升级成城市地铁网多个站点自动换乘、分支。我们在内部已经开展了 Agent Mesh 的预研工作核心思路是在 Agent-Reach 的基础上增加任务编排引擎和动态协商机制。比如客服 Agent 遇到超纲问题能自动把任务“委派”给更专业的 Agent而不是自己死磕超时后失败。这条路我也想清楚了最难的不是技术而是让 Agent 之间能建立信任边界——你委托出去的任务怎么监控它的执行质量怎么防止恶意 Agent 推卸责任这些很可能就是下一阶段的核心难题。写在最后的个人体会Agent-Reach 做下来我最大的体会有两个。第一连接比聪明更重要。很多团队把精力放在调教单个 Agent 的智商上却没有让它们形成合力。没有可靠的触达网络再聪明的 Agent 也只是孤岛上的灯塔照亮不了远方的航船。第二连接层的设计要像修高速路一样留足安全冗余。你修的每条路都可能被超载、被堵塞、被极端天气影响防护措施一定要在动土前就埋好。这套项目跑到现在我每天最担心的已经不是功能怎么实现而是路由表是否健康、上下文是否过期、权限有没有被绕过。这些不起眼的心里有底才是连接层稳定运行的真正底气。