多智能体项目做到第三个月的时候我发现我们最头疼的问题不再是某个Agent的推理能力不行而是Agent之间互相“找不到人”。费了很大劲把十几个Agent都跑起来了结果消息在系统里转了几圈没人处理调用方等不到结果日志里全是超时和重试。也就是从那时候起我开始认真琢磨Agent-Reach这件事——一个专门负责智能体之间触达与调度的中间层。这篇东西就是我把它从零搭起来之后的完整复盘包括架构思路、核心模块的拆解、参数怎么定、踩过哪些坑希望能给正在做多Agent系统的朋友一点参考。Agent-Reach这个项目要解决的核心问题可以用一句话讲清楚当一个系统里同时跑着十几个、几十个甚至上百个Agent的时候Agent之间以及Agent与外部系统之间的请求到底怎么才能可靠、高效、可治理地送达对方手里。它不是一个具体的业务Agent而是所有Agent共同依赖的“门厅”和“邮局”。如果你刚接触这个概念可以先把它理解成微服务架构里的注册中心加消息队列加网关的结合体只不过服务单元从“接口”变成了“具备能力的Agent”。这篇文章适合三类人看一是已经在做多Agent应用、正在被协作问题折磨的开发者二是准备从单体Agent往多Agent架构演进、想提前设计好基础设施的架构师三是纯粹对Agent工程化感兴趣、想看看这个方向实际落地长什么样的朋友。1. 为什么需要Agent触达层1.1 单体Agent时代不需要Reach先退一步说个直观的事当你的项目只有一个Agent比如一个对接了知识库的问答机器人这个阶段根本不需要触达层。所有请求走一个入口模型调用、工具调用、上下文管理逻辑都是一条链路上的事情出了问题顺着调用栈往下查就行哪里需要什么“触达”概念。但项目一旦多Agent化情况就完全变了。我们团队最初做了一个三Agent的Demo一个负责意图识别一个负责检索资料一个负责生成回复。跑的阶段一切正常等真正接到业务里把检索能力扩展成三个不同的专业接口、把生成逻辑拆成两套风格模型之后协作立刻变成了灾难。意图识别Agent需要问检索Agent要资料检索Agent不知道用户上下文又想回头找意图Agent确认生成Agent又需要同时等两个上游的结果。每个Agent都像一间独立的办公室中间没有任何约定俗成的寻址和投递机制结果就是互相找不到、消息丢失、等待超时。这时候你才发现Agent和Agent之间最需要的不是更强的推理能力而是一套类似“城市交通系统”的东西让大家知道往哪走、怎么走、走不通了怎么办。这就是Reach层的价值。1.2 多Agent协作的三大痛点把团队踩过的坑抽象一下多Agent协作主要就三个痛点第一个是寻址问题。一个请求说自己需要“查天气”但系统里有三个Agent都声称自己能查天气选哪一个是按能力选还是按位置选还是按负载选这跟在多台服务器前面做负载均衡是一个道理只是维度更复杂——能力本身也要参与匹配。第二个是可靠性问题。A和B两个Agent都是独立进程A把任务发给BB处理到一半挂了怎么办A怎么知道这个消息到底送达没有B处理完之后的结果怎么回传给A这就远不是发一个HTTP请求那么简单了涉及投递语义、超时区分、重试策略、结果回执整个链路。第三个是治理问题。几十个Agent在跑谁调了谁、调用频率多高、哪个Agent经常失败、哪些消息在队列里堵了多久这些东西如果没有统一观测出问题的时候基本靠猜。我们在没有触达层的阶段排查过一次线上问题花了四个小时才定位到是一个Agent的配置把另一个Agent的队列前缀抢占了——纯粹因为没有任何路由规则做隔离这种问题靠人肉很难扛。这三个痛点的本质是一样的Agent网络需要一套独立的“调度与触达基建”而不是让每个Agent自己用乱糟糟的HTTP调用互相连接。于是我们决定自己动手做Agent-Reach。2. Agent-Reach 的整体架构与设计思路2.1 Reach在架构中的位置先画一下我们最终落地的架构分层你就能直观理解Agent-Reach的角色。最上层是业务调度层负责接收用户请求、编排多步任务流程你可以理解成整个系统的“项目经理”。中间层就是Agent-Reach它提供的是Agent的注册发现、路由寻址、消息投递、回执跟踪这四个核心能力。最下层就是实际干活的各类Agent它们只需要做一件事启动时把自己注册到Reach然后按规范处理进来请求。这个分层有个重要的隐含设计业务调度层不直接持有任何Agent地址它只把请求交给Reach由Reach决定把请求触达给哪个Agent实例。这样一来Agent上下线、扩容缩容对上层就完全透明了。我们曾经在双11一样的业务高峰前临时扩了两个检索Agent实例调度层改都没改——因为Reach会在路由时自动把流量分布到新实例上。为了让这个分层真正落地Agent-Reach内部拆成了四个模块注册中心节点维护所有在线Agent的身份、能力、地址、健康状态类似电话簿。路由引擎节点根据请求特征和Agent元数据计算出目标Agent支持多策略组合。消息总线负责实际的消息传递、持久化和回执关联底层我们用的是带持久化的消息中间件。治理控制台负责配置路由策略、查看链路追踪、管理限流与降级是运营和排障的窗口。这四个模块分工也很自然注册中心解决“谁在线、能干什么”路由引擎解决“该给谁”消息总线解决“怎么可靠送到”治理控制台解决“怎么管起来”。2.2 为什么采用注册发现而非直连在设计Agent-Reach的过程中我们有一段时间纠结过一个问题让Agent之间直接通过HTTP/GRPC互联Redis存一份实例列表就完了为什么要花力气做一个独立的触达层这个纠结很真实毕竟直连方案看起来更轻、延迟更低。但后来我们做了一次压力测试模拟直接把方案否掉了。场景是这样假设15个Agent如果每个Agent都要能跟其他Agent互相调用就需要维护14×14多条两两连接每加一个Agent连接数就指数级上涨。连接多了以后健康检查、超时配置、重试逻辑就完全失控了——A重试了3次B那边可能已经处理了2次重复执行得不可开交。更关键的是Agent的“能力”不是静态的。同一个Agent在不同时间点可能具备不同的可用工具或模型版本直连方案里调用方根本无法知道对方当前的能力状态。而这些信息在注册中心里可以统一维护、动态更新。所以最终架构选择了“注册发现消息触达”模式端到端长这样Agent启动后向注册中心上报能力声明和能力参数并不断发送心跳。调用方请求进入Reach后路由引擎从注册中心拿到候选Agent列表。路由引擎根据路由策略打分排序选出最佳触达目标。消息总线将请求投递给目标AgentAgent执行完把回执写回Reach关联链路。整套过程都有trace记录控制台可以实时查看。这套链路前期多花了一点开发时间但后续扩容和排查故障省下来的时间完全值回票价。3. 核心模块拆解与实现要点3.1 Agent注册与心跳机制Agent-Reach的注册中心模块第一大要素就是“Agent注册”。每一个Agent在启动时都需要向注册中心发起注册请求注册内容是三类信息身份信息Agent ID、名称、实例所在的机器/容器/地域。能力声明这个Agent能提供哪些能力。比如阅读Agent声明自己能处理PDF解析和OCR写作Agent声明自己能做文案生成每个能力可以附带参数字段说明。服务等级权重、最大并发数、QPS上限、可用性级别这些会参与路由打分。注册成功之后Agent并不是一劳永逸。它的状态分为在线和离线之间靠心跳维持。这里的核心设计点是TTL和阈值我们设置120秒心跳间隔允许连续3次心跳失败再标记该Agent为离线。这个数字不是拍脑袋定的而是结合了Agent的冷启动时间和网络抖动两个因素折中的结果——太短容易把偶发抖动误判为宕机太长又会让路由打到僵死实例上。具体实现上注册中心采用内存表加持久化双写。所有在线Agent的元数据缓存在内存里路由引擎直接读内存保证微秒级别的寻址速度同时异步把注册变更事件写入日志存储用于后续审计和故障回溯。如果你要自己实现最简单的版本可以用Redis的Hash结构加过期时间模拟TTL但要小心存量清理和心跳续期的并发问题。关于注册这块我特别想补充一个血泪教训能力声明一定要做版本管理。我们早期的能力字段就是一个自然语言的描述串比如“我能做复杂文档解析”路由匹配全靠字符串相似度结果经常把请求送给不对口的Agent。后来改成结构化能力名称加参数约束加上“能力签名”校验情况才好起来。Agent能力在升级时要明确是兼容变更还是不兼容变更不兼容的必须换新能力名称不然老实例和新实例混在一起很容易出乱子。3.2 路由策略从“能处理”到“最合适”有了注册中心的基础数据之后路由引擎就是真正决定“触达给谁”的部分。如果把Agent系统比作出租车调度平台注册中心是司机名单路由策略就是派单算法。Agent-Reach的路由引擎默认采用多因子加权打分而不是单一规则。完整的选择过程分三步第一步候选过滤。所有候选Agent必须匹配请求中的能力要求同时要满足“允许被调用”的状态标记。这一层把不可能响应请求的Agent直接淘汰打个比方就是先在出租车App里筛掉“休息中”的司机。第二步多因子打分。这个阶段会对每个候选实例计算一个综合分我们预设了四个打分维度能力契合度请求中的结构化参数和Agent声明的参数约束匹配度。地域亲和性请求来源和目标Agent是否在同一机房或同城优先本地。负载水位Agent当前的在途请求数超过其声明最大并发数的比率水位越低分越高。会话亲和性同一用户或同一任务链路的请求尽量保持打到同一个Agent避免频繁切换导致上下文丢失。四个维度得分加权求和权重在控制台里可配。初期我们采用的是固定权重后来发现业务高峰时负载因子权重需要临时加大否则流量容易压垮单个实例。第三步选择与降级。默认选择综合分最高的实例如果最高分的实例触达失败会按分值依次尝试下一个最多尝试3个候选3个都失败则触发降级直接返回失败或走预设的兜底逻辑。这里有一个值得单独说的设计决策我们当时反复讨论过要不要用“轮询”这种简单策略替代多因子打分。轮询实现起来当然简单但它完全不感知Agent的健康状况和能力差异经常出现“两个健康实例分配了均等流量其中一个处理快一个处理慢”的局面慢的Agent就会变成瓶颈。所以最终坚持用了打分路由虽然复杂一点但调度质量明显更高。3.3 投递语义与回执确认路由决定“给谁”之后消息总线要回答一个更深刻的问题消息到底怎么算“送达”了这里涉及分布式系统里经典的投递语义至少一次、至多一次、精确一次。在实际的Agent触达场景里我们选了“至少一次”作为默认语义。原因很务实Agent任务执行有副作用的风险比如“生成了一个文件”或者“扣减了一个库存”这种场景下丢消息的后果比重复执行更严重。你可以想想账单系统漏扣一笔款和重复扣一笔款前者是安全隐患后者顶多是用户投诉——所以宁可重复不可丢失。“至少一次”的落地并不复杂关键是两个机制持久化消息队列加ACK确认。消息总线收到请求后先落盘然后把消息推送给目标AgentAgent执行完毕后需要显式回执一条ACK消息总线收到ACK才把这条消息从待确认队列里删除如果等待超时没有ACK消息总线会重新投递最多重试N次。这里的难点是超时和重试的配合。我们为每条消息设置了“触达超时”和“执行超时”两套时钟触达超时指的是投递环节执行超时指的是Agent拿到消息后的处理时间。两者要分开因为网络慢和Agent算得慢完全是两个问题混淆了排查起来格外痛苦。而且重试的时候一定要在消息里带上幂等键让Agent端可以去重否则“至少一次”就会变成实际上的“多次执行”。3.4 超时、限流与重试的取舍聊到重试就必须把超时限流一起说这三个参数在Agent-Reach里是配套使用的孤立的配置往往会在故障时放大问题。先说超时。消息总线的超时设置有五个相关参数连接超时、请求排队超时、触达超时、处理超时、总超时。我建议你不管用不用Agent-Reach都要养成这种“分阶段设超时”的习惯。只设一个总的调用超时的系统在故障时几乎是无法判断是哪一段卡住了——到底是没连上还是在队列里排队还是Agent在处理根本没有线索。我们最终调的一组基准超时配置送给你参考参数数值配置考量连接超时500ms同机房连接一般几十毫秒留到500ms足够宽裕排队超时3s消息在总线缓冲区等待超过3s说明Agent已经过载触达超时1s消息从总线到Agent进程的网络传输上限处理超时8s基于实测P99的3倍经验值幂等窗口30s与最大重试间隔的3倍对齐限流这边我们用的是令牌桶加并发窗口双限流。令牌桶保护总线自身不被突发流量冲垮并发窗口保护单个Agent不被过量请求压垮。具体实现就是在路由结果出来之后对目标Agent的在途请求数做一次计数检查超过声明并发上限就排队等。这个限制在链路里是一个“只挡不杀”的软机制避免了直接把请求打回去让上层疯狂重试的恶性循环。重试策略也是一个有学问的地方。我们的设置是触达类失败比如目标Agent离线不重试直接选下一个候选执行类超时消息到达Agent但没有在限定时间返回回执最多重试一次并且重试前要等待指数退避业务类失败Agent明确返回错误码不重试直接走降级。这样分类处理的核心逻辑是重试解决的是“不确定性”问题而不是“确定性问题”。已经确定失败的业务请求重试一万次也还是失败还会给下游添乱。4. 实操过程与关键参数计算4.1 路由打分策略的落地与权重调优前面说了路由引擎是四维打分实操中这个打分公式是最值得花时间调的部分。我们采用的简化加权公式是score w1 * capability w2 * locality w3 * (1 - load_ratio) w4 * affinity其中load_ratio是Agent当前在途请求数除以它的最大并发声明值所以(1 - load_ratio)代表着空闲程度数值越高说明越空闲。默认权重我们设为w10.4, w20.2, w30.3, w40.1。为什么不把能力契合度设成1.0直接一票否决其他因子因为在候选过滤阶段已经淘汰了能力不合规的Agent进入打分阶段的所有Agent能力匹配度都不差这时候再拉大权重差距意义不大反而会让负载和地域因子完全失去作用。真正让打分策略稳定下来我们做了三件小事一是把打分计算做成可监控项每个候选的得分和最终选择都会记录到日志里二是给每个权重配置了“控制台手动调整加A/B对比”的通道让运维可以在高峰前临时加大负载因子三是把打分做成纯函数入参是Agent元数据和请求特征这样单测和复盘都非常方便。实操时还有一个容易忽略的小坑候选列表里如果有多个实例的分数非常接近默认取最高分会导致请求总往同一个实例打。我们后来加了一个“微抖动”机制在分值差距小于0.05的候选里做一次轻度随机选择相当于打破平局。这个细节看似不起眼但对实例间的负载均衡效果帮助很大。4.2 一条触达消息的完整生命周期为了让你更直观地看Agent-Reach怎么工作我拿一条真实消息走一遍全流程。比如用户端提交了一个“分析合同条款”的请求。第一步业务调度层调用Reach的API传入结构化请求体里面带着目标能力名contract.analysis和原始文档的存储路径。第二步路由引擎从注册中心拉取所有声明了contract.analysis能力的Agent发现有A、B两个实例在线A实例经能力过滤后匹配度95%负载水位30%B实例匹配度90%负载水位70%。打分结果是A高一些微抖动也没打破这个差距于是消息的最终触达目标确定为A。第三步消息总线生成一条带trace_id和幂等键的消息写入持久化队列然后开始向A投递。A解析出文档路径调用LLM进行条款分析和关键风险识别生成结果后把回执写回Reach的存储节点。Reach将消息状态标记为“已完成”并把结果返回给业务调度层。这一整条链路的平均延迟我们压测出来大概在2.8秒左右其中LLM推理占了2秒Reach自身引入的额外延迟只有几十毫秒量级。这个数据说明了触达层的设计原则它必须尽量薄不应该变成业务链路里的显著延迟放大器。如果你实现出来的Reach让每次触达都多花费几百毫秒甚至一秒那一定是什么环节设计出了问题。4.3 关键性能指标与参数计算做触达层必须要有一套量化指标来衡量做得好不好不然优化无从谈起。我们在Agent-Reach上线后一直盯四个指标触达成功率成功收到回执的消息数除以总发送消息数。P99触达时延从消息进入总线到Agent收到消息并开始处理的时延。队列积压数消息总线上待投递和待确认的消息总量。路由降级率兜底到降级逻辑的请求占比过高说明系统健康度不佳。在调优过程中我算过一组并发场景的参数这里把计算方法记录下来。假设单个Agent的实测处理峰值是每秒200个请求单个请求平均处理耗时500毫秒。那么这个Agent的理想并发承载量为200×0.5100个在途请求。这符合Littles Law系统中平均请求数等于吞吐率乘以驻留时间。所以我们在Agent的声明配置里就写max_concurrency100路由引擎打分时只要在途超过80就认为负载偏高。再看队列深度。如果最差情况下Agent处理慢到每秒50个请求而我们希望压在队列里的等待时间不超过10秒那么队列缓冲深度就需要50×10500条消息。这个数字再乘以消息体平均大小就是消息总线的内存缓冲规划依据。实际的队列缓冲我们定得比计算值大3倍因为还要容忍下游Agent短时间无响应的极端场景。压测的最终表现一个由15个Agent、4类路由策略组成的集群在每秒5000条触达请求的压力下P99投递时延稳定在120毫秒左右触达成功率99.98%Redis和消息集群的CPU水位都在35%以下。这个结果基本符合我们对一个轻量触达层的预期。5. 常见问题与排查技巧实录5.1 触达超时到底卡在哪一段实际运行Agent-Reach之后遇到最多的一个问题就是“触达超时”。有一回上游反馈“调用某某Agent经常要等10秒以上”但查看这个Agent本身的监控又一切正常。这种问题在没有trace系统的时候非常难查因为超时的原因可能发生在调用方、路由引擎、消息总线、目标Agent四个不同环节。我们的排查套路是三步走。第一步看trace里的分段耗时确定超时发生在哪一段——是排队超时还是处理超时第二步如果是处理超时进Agent日志看它是否收到了触达请求收到的话是停在“排队等模型返回”还是“执行工具调用”第三步如果是排队超时上消息总线看这个Agent的并发窗口是不是被占满了用脚本把在途请求数拉出来看看。按这个流程操作大概率能在十分钟内定位问题。最典型的案例是某个Agent声明处理能力是5并发但业务方临时导入了大批量数据导致每个请求处理时间从500ms涨到5秒并发窗口被占满后后续请求全部排队看起来就像“触达超时”了。最后把该Agent的处理能力声明上调同时给批量任务单独配置了更长的处理超时问题立刻缓解。我强烈建议你在设计早期就把trace作为必选项而非可选项。第一次踩坑的时候我们没有trace全靠打印日志人工对时间线效率低到令人崩溃。后来我们给每一条消息都打下trace_id和span记录任何一次触达都可以在控制台里展开完整的时间线排障效率直接提升了一个数量级。5.2 重复触达导致的副作用问题第二个高频问题是重复触达。选择“至少一次”投递语义后消息在超时重试场景下会产生重复投递。有一次我们一个调用Agent的接口不是幂等的重复执行导致业务侧生成了两份重复订单记录。排查下来发现是这样一个链路消息总线第一次投递后Agent执行写库慢了导致回执迟迟没有确认触发了总线的超时重试。重试的那条消息进入Agent后被再次执行业务逻辑又没有做幂等校验最终出现了脏数据。解决这个问题有两个层面的动作。在Agent-Reach层面我们把幂等键设成请求内容哈希加业务时间窗组合并确保同一幂等键在30秒窗口内只投递一次。在业务Agent层面我们在Agent的连接器基类里强制要求实现幂等处理器——通过Redis记录每个幂等键的执行状态。这两个动作双管齐下重复触达的问题才算彻底根治。这里有个通用经验值得分享设计Agent触达时默认任何消息都可能被投递多次接口没有幂等就等于系统里埋了雷。幂等处理要从最开始就纳入接口规范不能等出事了再补。5.3 消息积压与背压处理第三个典型问题是消息积压。某次一个Agent因为依赖的第三方API限流处理速度从每秒200个骤降到每秒20个而Reach还在按原来的速率投递结果队列里消息越积越多最终把消息集群的内存打到了告警线。面对积压问题单纯扩容队列空间只是治标真正的解法是背压。我们在Reach里实现了“动态降速”机制当某个Agent的在途请求数超过声明的80%时路由引擎会降低对该Agent的投递速率把流量分摊到其他候选实例如果所有候选实例都过载则对新的请求直接快速失败并返回“稍后重试”的提示让上游自行退避。这套机制上线后类似的积压场景再没有出现过。关键是你要接受一个现实触达层不应该无限容忍下游变慢。它任期是保证系统不退化成雪崩而不是无限制地把每个请求都硬塞给慢吞吞的目标。6. 写在最后Agent-Reach从设计到落地我最大的体会是构建多Agent系统最容易低估的恰恰不是智商而是基础设施。模型能力现在卷得厉害聪明的Agent不难找真正难的是一群聪明的Agent之间如何不吵架地协作。触达层表面上看是技术组件实际上它定义了整个Agent网络的协作秩序——谁能被找到、谁有资格被选中、消息怎么流动、出错了怎么兜底。如果你也要做一个类似的触达层我的核心建议只有八个字越薄越好观测优先。不要试图在Reach里塞太多业务逻辑它会变成另一个更复杂的Agent反而拖累整条链路但任何一次触达的可观测性一定要做足因为你不可能靠猜去运维一个几十个Agent的网络。还有一个很实际的小技巧Agent-Reach这类组件不要在项目后期再强行引入。如果Agent网络只有两三个节点时你确实可以用野蛮直连把业务跑通但一旦规模到了十个以上再把触达层嵌入进来搬迁和改造的成本会成倍上升。最好从设计阶段就给Agent网络留一个路由层的位置前期哪怕只用最简单的配置实现也比没有好。后面你会感谢当初多留了这个口子。
多智能体项目做到第三个月的时候我发现我们最头疼的问题不再是某个Agent的推理能力不行而是Agent之间互相“找不到人”。费了很大劲把十几个Agent都跑起来了结果消息在系统里转了几圈没人处理调用方等不到结果日志里全是超时和重试。也就是从那时候起我开始认真琢磨Agent-Reach这件事——一个专门负责智能体之间触达与调度的中间层。这篇东西就是我把它从零搭起来之后的完整复盘包括架构思路、核心模块的拆解、参数怎么定、踩过哪些坑希望能给正在做多Agent系统的朋友一点参考。Agent-Reach这个项目要解决的核心问题可以用一句话讲清楚当一个系统里同时跑着十几个、几十个甚至上百个Agent的时候Agent之间以及Agent与外部系统之间的请求到底怎么才能可靠、高效、可治理地送达对方手里。它不是一个具体的业务Agent而是所有Agent共同依赖的“门厅”和“邮局”。如果你刚接触这个概念可以先把它理解成微服务架构里的注册中心加消息队列加网关的结合体只不过服务单元从“接口”变成了“具备能力的Agent”。这篇文章适合三类人看一是已经在做多Agent应用、正在被协作问题折磨的开发者二是准备从单体Agent往多Agent架构演进、想提前设计好基础设施的架构师三是纯粹对Agent工程化感兴趣、想看看这个方向实际落地长什么样的朋友。1. 为什么需要Agent触达层1.1 单体Agent时代不需要Reach先退一步说个直观的事当你的项目只有一个Agent比如一个对接了知识库的问答机器人这个阶段根本不需要触达层。所有请求走一个入口模型调用、工具调用、上下文管理逻辑都是一条链路上的事情出了问题顺着调用栈往下查就行哪里需要什么“触达”概念。但项目一旦多Agent化情况就完全变了。我们团队最初做了一个三Agent的Demo一个负责意图识别一个负责检索资料一个负责生成回复。跑的阶段一切正常等真正接到业务里把检索能力扩展成三个不同的专业接口、把生成逻辑拆成两套风格模型之后协作立刻变成了灾难。意图识别Agent需要问检索Agent要资料检索Agent不知道用户上下文又想回头找意图Agent确认生成Agent又需要同时等两个上游的结果。每个Agent都像一间独立的办公室中间没有任何约定俗成的寻址和投递机制结果就是互相找不到、消息丢失、等待超时。这时候你才发现Agent和Agent之间最需要的不是更强的推理能力而是一套类似“城市交通系统”的东西让大家知道往哪走、怎么走、走不通了怎么办。这就是Reach层的价值。1.2 多Agent协作的三大痛点把团队踩过的坑抽象一下多Agent协作主要就三个痛点第一个是寻址问题。一个请求说自己需要“查天气”但系统里有三个Agent都声称自己能查天气选哪一个是按能力选还是按位置选还是按负载选这跟在多台服务器前面做负载均衡是一个道理只是维度更复杂——能力本身也要参与匹配。第二个是可靠性问题。A和B两个Agent都是独立进程A把任务发给BB处理到一半挂了怎么办A怎么知道这个消息到底送达没有B处理完之后的结果怎么回传给A这就远不是发一个HTTP请求那么简单了涉及投递语义、超时区分、重试策略、结果回执整个链路。第三个是治理问题。几十个Agent在跑谁调了谁、调用频率多高、哪个Agent经常失败、哪些消息在队列里堵了多久这些东西如果没有统一观测出问题的时候基本靠猜。我们在没有触达层的阶段排查过一次线上问题花了四个小时才定位到是一个Agent的配置把另一个Agent的队列前缀抢占了——纯粹因为没有任何路由规则做隔离这种问题靠人肉很难扛。这三个痛点的本质是一样的Agent网络需要一套独立的“调度与触达基建”而不是让每个Agent自己用乱糟糟的HTTP调用互相连接。于是我们决定自己动手做Agent-Reach。2. Agent-Reach 的整体架构与设计思路2.1 Reach在架构中的位置先画一下我们最终落地的架构分层你就能直观理解Agent-Reach的角色。最上层是业务调度层负责接收用户请求、编排多步任务流程你可以理解成整个系统的“项目经理”。中间层就是Agent-Reach它提供的是Agent的注册发现、路由寻址、消息投递、回执跟踪这四个核心能力。最下层就是实际干活的各类Agent它们只需要做一件事启动时把自己注册到Reach然后按规范处理进来请求。这个分层有个重要的隐含设计业务调度层不直接持有任何Agent地址它只把请求交给Reach由Reach决定把请求触达给哪个Agent实例。这样一来Agent上下线、扩容缩容对上层就完全透明了。我们曾经在双11一样的业务高峰前临时扩了两个检索Agent实例调度层改都没改——因为Reach会在路由时自动把流量分布到新实例上。为了让这个分层真正落地Agent-Reach内部拆成了四个模块注册中心节点维护所有在线Agent的身份、能力、地址、健康状态类似电话簿。路由引擎节点根据请求特征和Agent元数据计算出目标Agent支持多策略组合。消息总线负责实际的消息传递、持久化和回执关联底层我们用的是带持久化的消息中间件。治理控制台负责配置路由策略、查看链路追踪、管理限流与降级是运营和排障的窗口。这四个模块分工也很自然注册中心解决“谁在线、能干什么”路由引擎解决“该给谁”消息总线解决“怎么可靠送到”治理控制台解决“怎么管起来”。2.2 为什么采用注册发现而非直连在设计Agent-Reach的过程中我们有一段时间纠结过一个问题让Agent之间直接通过HTTP/GRPC互联Redis存一份实例列表就完了为什么要花力气做一个独立的触达层这个纠结很真实毕竟直连方案看起来更轻、延迟更低。但后来我们做了一次压力测试模拟直接把方案否掉了。场景是这样假设15个Agent如果每个Agent都要能跟其他Agent互相调用就需要维护14×14多条两两连接每加一个Agent连接数就指数级上涨。连接多了以后健康检查、超时配置、重试逻辑就完全失控了——A重试了3次B那边可能已经处理了2次重复执行得不可开交。更关键的是Agent的“能力”不是静态的。同一个Agent在不同时间点可能具备不同的可用工具或模型版本直连方案里调用方根本无法知道对方当前的能力状态。而这些信息在注册中心里可以统一维护、动态更新。所以最终架构选择了“注册发现消息触达”模式端到端长这样Agent启动后向注册中心上报能力声明和能力参数并不断发送心跳。调用方请求进入Reach后路由引擎从注册中心拿到候选Agent列表。路由引擎根据路由策略打分排序选出最佳触达目标。消息总线将请求投递给目标AgentAgent执行完把回执写回Reach关联链路。整套过程都有trace记录控制台可以实时查看。这套链路前期多花了一点开发时间但后续扩容和排查故障省下来的时间完全值回票价。3. 核心模块拆解与实现要点3.1 Agent注册与心跳机制Agent-Reach的注册中心模块第一大要素就是“Agent注册”。每一个Agent在启动时都需要向注册中心发起注册请求注册内容是三类信息身份信息Agent ID、名称、实例所在的机器/容器/地域。能力声明这个Agent能提供哪些能力。比如阅读Agent声明自己能处理PDF解析和OCR写作Agent声明自己能做文案生成每个能力可以附带参数字段说明。服务等级权重、最大并发数、QPS上限、可用性级别这些会参与路由打分。注册成功之后Agent并不是一劳永逸。它的状态分为在线和离线之间靠心跳维持。这里的核心设计点是TTL和阈值我们设置120秒心跳间隔允许连续3次心跳失败再标记该Agent为离线。这个数字不是拍脑袋定的而是结合了Agent的冷启动时间和网络抖动两个因素折中的结果——太短容易把偶发抖动误判为宕机太长又会让路由打到僵死实例上。具体实现上注册中心采用内存表加持久化双写。所有在线Agent的元数据缓存在内存里路由引擎直接读内存保证微秒级别的寻址速度同时异步把注册变更事件写入日志存储用于后续审计和故障回溯。如果你要自己实现最简单的版本可以用Redis的Hash结构加过期时间模拟TTL但要小心存量清理和心跳续期的并发问题。关于注册这块我特别想补充一个血泪教训能力声明一定要做版本管理。我们早期的能力字段就是一个自然语言的描述串比如“我能做复杂文档解析”路由匹配全靠字符串相似度结果经常把请求送给不对口的Agent。后来改成结构化能力名称加参数约束加上“能力签名”校验情况才好起来。Agent能力在升级时要明确是兼容变更还是不兼容变更不兼容的必须换新能力名称不然老实例和新实例混在一起很容易出乱子。3.2 路由策略从“能处理”到“最合适”有了注册中心的基础数据之后路由引擎就是真正决定“触达给谁”的部分。如果把Agent系统比作出租车调度平台注册中心是司机名单路由策略就是派单算法。Agent-Reach的路由引擎默认采用多因子加权打分而不是单一规则。完整的选择过程分三步第一步候选过滤。所有候选Agent必须匹配请求中的能力要求同时要满足“允许被调用”的状态标记。这一层把不可能响应请求的Agent直接淘汰打个比方就是先在出租车App里筛掉“休息中”的司机。第二步多因子打分。这个阶段会对每个候选实例计算一个综合分我们预设了四个打分维度能力契合度请求中的结构化参数和Agent声明的参数约束匹配度。地域亲和性请求来源和目标Agent是否在同一机房或同城优先本地。负载水位Agent当前的在途请求数超过其声明最大并发数的比率水位越低分越高。会话亲和性同一用户或同一任务链路的请求尽量保持打到同一个Agent避免频繁切换导致上下文丢失。四个维度得分加权求和权重在控制台里可配。初期我们采用的是固定权重后来发现业务高峰时负载因子权重需要临时加大否则流量容易压垮单个实例。第三步选择与降级。默认选择综合分最高的实例如果最高分的实例触达失败会按分值依次尝试下一个最多尝试3个候选3个都失败则触发降级直接返回失败或走预设的兜底逻辑。这里有一个值得单独说的设计决策我们当时反复讨论过要不要用“轮询”这种简单策略替代多因子打分。轮询实现起来当然简单但它完全不感知Agent的健康状况和能力差异经常出现“两个健康实例分配了均等流量其中一个处理快一个处理慢”的局面慢的Agent就会变成瓶颈。所以最终坚持用了打分路由虽然复杂一点但调度质量明显更高。3.3 投递语义与回执确认路由决定“给谁”之后消息总线要回答一个更深刻的问题消息到底怎么算“送达”了这里涉及分布式系统里经典的投递语义至少一次、至多一次、精确一次。在实际的Agent触达场景里我们选了“至少一次”作为默认语义。原因很务实Agent任务执行有副作用的风险比如“生成了一个文件”或者“扣减了一个库存”这种场景下丢消息的后果比重复执行更严重。你可以想想账单系统漏扣一笔款和重复扣一笔款前者是安全隐患后者顶多是用户投诉——所以宁可重复不可丢失。“至少一次”的落地并不复杂关键是两个机制持久化消息队列加ACK确认。消息总线收到请求后先落盘然后把消息推送给目标AgentAgent执行完毕后需要显式回执一条ACK消息总线收到ACK才把这条消息从待确认队列里删除如果等待超时没有ACK消息总线会重新投递最多重试N次。这里的难点是超时和重试的配合。我们为每条消息设置了“触达超时”和“执行超时”两套时钟触达超时指的是投递环节执行超时指的是Agent拿到消息后的处理时间。两者要分开因为网络慢和Agent算得慢完全是两个问题混淆了排查起来格外痛苦。而且重试的时候一定要在消息里带上幂等键让Agent端可以去重否则“至少一次”就会变成实际上的“多次执行”。3.4 超时、限流与重试的取舍聊到重试就必须把超时限流一起说这三个参数在Agent-Reach里是配套使用的孤立的配置往往会在故障时放大问题。先说超时。消息总线的超时设置有五个相关参数连接超时、请求排队超时、触达超时、处理超时、总超时。我建议你不管用不用Agent-Reach都要养成这种“分阶段设超时”的习惯。只设一个总的调用超时的系统在故障时几乎是无法判断是哪一段卡住了——到底是没连上还是在队列里排队还是Agent在处理根本没有线索。我们最终调的一组基准超时配置送给你参考参数数值配置考量连接超时500ms同机房连接一般几十毫秒留到500ms足够宽裕排队超时3s消息在总线缓冲区等待超过3s说明Agent已经过载触达超时1s消息从总线到Agent进程的网络传输上限处理超时8s基于实测P99的3倍经验值幂等窗口30s与最大重试间隔的3倍对齐限流这边我们用的是令牌桶加并发窗口双限流。令牌桶保护总线自身不被突发流量冲垮并发窗口保护单个Agent不被过量请求压垮。具体实现就是在路由结果出来之后对目标Agent的在途请求数做一次计数检查超过声明并发上限就排队等。这个限制在链路里是一个“只挡不杀”的软机制避免了直接把请求打回去让上层疯狂重试的恶性循环。重试策略也是一个有学问的地方。我们的设置是触达类失败比如目标Agent离线不重试直接选下一个候选执行类超时消息到达Agent但没有在限定时间返回回执最多重试一次并且重试前要等待指数退避业务类失败Agent明确返回错误码不重试直接走降级。这样分类处理的核心逻辑是重试解决的是“不确定性”问题而不是“确定性问题”。已经确定失败的业务请求重试一万次也还是失败还会给下游添乱。4. 实操过程与关键参数计算4.1 路由打分策略的落地与权重调优前面说了路由引擎是四维打分实操中这个打分公式是最值得花时间调的部分。我们采用的简化加权公式是score w1 * capability w2 * locality w3 * (1 - load_ratio) w4 * affinity其中load_ratio是Agent当前在途请求数除以它的最大并发声明值所以(1 - load_ratio)代表着空闲程度数值越高说明越空闲。默认权重我们设为w10.4, w20.2, w30.3, w40.1。为什么不把能力契合度设成1.0直接一票否决其他因子因为在候选过滤阶段已经淘汰了能力不合规的Agent进入打分阶段的所有Agent能力匹配度都不差这时候再拉大权重差距意义不大反而会让负载和地域因子完全失去作用。真正让打分策略稳定下来我们做了三件小事一是把打分计算做成可监控项每个候选的得分和最终选择都会记录到日志里二是给每个权重配置了“控制台手动调整加A/B对比”的通道让运维可以在高峰前临时加大负载因子三是把打分做成纯函数入参是Agent元数据和请求特征这样单测和复盘都非常方便。实操时还有一个容易忽略的小坑候选列表里如果有多个实例的分数非常接近默认取最高分会导致请求总往同一个实例打。我们后来加了一个“微抖动”机制在分值差距小于0.05的候选里做一次轻度随机选择相当于打破平局。这个细节看似不起眼但对实例间的负载均衡效果帮助很大。4.2 一条触达消息的完整生命周期为了让你更直观地看Agent-Reach怎么工作我拿一条真实消息走一遍全流程。比如用户端提交了一个“分析合同条款”的请求。第一步业务调度层调用Reach的API传入结构化请求体里面带着目标能力名contract.analysis和原始文档的存储路径。第二步路由引擎从注册中心拉取所有声明了contract.analysis能力的Agent发现有A、B两个实例在线A实例经能力过滤后匹配度95%负载水位30%B实例匹配度90%负载水位70%。打分结果是A高一些微抖动也没打破这个差距于是消息的最终触达目标确定为A。第三步消息总线生成一条带trace_id和幂等键的消息写入持久化队列然后开始向A投递。A解析出文档路径调用LLM进行条款分析和关键风险识别生成结果后把回执写回Reach的存储节点。Reach将消息状态标记为“已完成”并把结果返回给业务调度层。这一整条链路的平均延迟我们压测出来大概在2.8秒左右其中LLM推理占了2秒Reach自身引入的额外延迟只有几十毫秒量级。这个数据说明了触达层的设计原则它必须尽量薄不应该变成业务链路里的显著延迟放大器。如果你实现出来的Reach让每次触达都多花费几百毫秒甚至一秒那一定是什么环节设计出了问题。4.3 关键性能指标与参数计算做触达层必须要有一套量化指标来衡量做得好不好不然优化无从谈起。我们在Agent-Reach上线后一直盯四个指标触达成功率成功收到回执的消息数除以总发送消息数。P99触达时延从消息进入总线到Agent收到消息并开始处理的时延。队列积压数消息总线上待投递和待确认的消息总量。路由降级率兜底到降级逻辑的请求占比过高说明系统健康度不佳。在调优过程中我算过一组并发场景的参数这里把计算方法记录下来。假设单个Agent的实测处理峰值是每秒200个请求单个请求平均处理耗时500毫秒。那么这个Agent的理想并发承载量为200×0.5100个在途请求。这符合Littles Law系统中平均请求数等于吞吐率乘以驻留时间。所以我们在Agent的声明配置里就写max_concurrency100路由引擎打分时只要在途超过80就认为负载偏高。再看队列深度。如果最差情况下Agent处理慢到每秒50个请求而我们希望压在队列里的等待时间不超过10秒那么队列缓冲深度就需要50×10500条消息。这个数字再乘以消息体平均大小就是消息总线的内存缓冲规划依据。实际的队列缓冲我们定得比计算值大3倍因为还要容忍下游Agent短时间无响应的极端场景。压测的最终表现一个由15个Agent、4类路由策略组成的集群在每秒5000条触达请求的压力下P99投递时延稳定在120毫秒左右触达成功率99.98%Redis和消息集群的CPU水位都在35%以下。这个结果基本符合我们对一个轻量触达层的预期。5. 常见问题与排查技巧实录5.1 触达超时到底卡在哪一段实际运行Agent-Reach之后遇到最多的一个问题就是“触达超时”。有一回上游反馈“调用某某Agent经常要等10秒以上”但查看这个Agent本身的监控又一切正常。这种问题在没有trace系统的时候非常难查因为超时的原因可能发生在调用方、路由引擎、消息总线、目标Agent四个不同环节。我们的排查套路是三步走。第一步看trace里的分段耗时确定超时发生在哪一段——是排队超时还是处理超时第二步如果是处理超时进Agent日志看它是否收到了触达请求收到的话是停在“排队等模型返回”还是“执行工具调用”第三步如果是排队超时上消息总线看这个Agent的并发窗口是不是被占满了用脚本把在途请求数拉出来看看。按这个流程操作大概率能在十分钟内定位问题。最典型的案例是某个Agent声明处理能力是5并发但业务方临时导入了大批量数据导致每个请求处理时间从500ms涨到5秒并发窗口被占满后后续请求全部排队看起来就像“触达超时”了。最后把该Agent的处理能力声明上调同时给批量任务单独配置了更长的处理超时问题立刻缓解。我强烈建议你在设计早期就把trace作为必选项而非可选项。第一次踩坑的时候我们没有trace全靠打印日志人工对时间线效率低到令人崩溃。后来我们给每一条消息都打下trace_id和span记录任何一次触达都可以在控制台里展开完整的时间线排障效率直接提升了一个数量级。5.2 重复触达导致的副作用问题第二个高频问题是重复触达。选择“至少一次”投递语义后消息在超时重试场景下会产生重复投递。有一次我们一个调用Agent的接口不是幂等的重复执行导致业务侧生成了两份重复订单记录。排查下来发现是这样一个链路消息总线第一次投递后Agent执行写库慢了导致回执迟迟没有确认触发了总线的超时重试。重试的那条消息进入Agent后被再次执行业务逻辑又没有做幂等校验最终出现了脏数据。解决这个问题有两个层面的动作。在Agent-Reach层面我们把幂等键设成请求内容哈希加业务时间窗组合并确保同一幂等键在30秒窗口内只投递一次。在业务Agent层面我们在Agent的连接器基类里强制要求实现幂等处理器——通过Redis记录每个幂等键的执行状态。这两个动作双管齐下重复触达的问题才算彻底根治。这里有个通用经验值得分享设计Agent触达时默认任何消息都可能被投递多次接口没有幂等就等于系统里埋了雷。幂等处理要从最开始就纳入接口规范不能等出事了再补。5.3 消息积压与背压处理第三个典型问题是消息积压。某次一个Agent因为依赖的第三方API限流处理速度从每秒200个骤降到每秒20个而Reach还在按原来的速率投递结果队列里消息越积越多最终把消息集群的内存打到了告警线。面对积压问题单纯扩容队列空间只是治标真正的解法是背压。我们在Reach里实现了“动态降速”机制当某个Agent的在途请求数超过声明的80%时路由引擎会降低对该Agent的投递速率把流量分摊到其他候选实例如果所有候选实例都过载则对新的请求直接快速失败并返回“稍后重试”的提示让上游自行退避。这套机制上线后类似的积压场景再没有出现过。关键是你要接受一个现实触达层不应该无限容忍下游变慢。它任期是保证系统不退化成雪崩而不是无限制地把每个请求都硬塞给慢吞吞的目标。6. 写在最后Agent-Reach从设计到落地我最大的体会是构建多Agent系统最容易低估的恰恰不是智商而是基础设施。模型能力现在卷得厉害聪明的Agent不难找真正难的是一群聪明的Agent之间如何不吵架地协作。触达层表面上看是技术组件实际上它定义了整个Agent网络的协作秩序——谁能被找到、谁有资格被选中、消息怎么流动、出错了怎么兜底。如果你也要做一个类似的触达层我的核心建议只有八个字越薄越好观测优先。不要试图在Reach里塞太多业务逻辑它会变成另一个更复杂的Agent反而拖累整条链路但任何一次触达的可观测性一定要做足因为你不可能靠猜去运维一个几十个Agent的网络。还有一个很实际的小技巧Agent-Reach这类组件不要在项目后期再强行引入。如果Agent网络只有两三个节点时你确实可以用野蛮直连把业务跑通但一旦规模到了十个以上再把触达层嵌入进来搬迁和改造的成本会成倍上升。最好从设计阶段就给Agent网络留一个路由层的位置前期哪怕只用最简单的配置实现也比没有好。后面你会感谢当初多留了这个口子。
