Agent-Reach：构建高可靠的Agent调度与任务触达系统

1. Agent-Reach要解决的现实问题：Agent不是造出来就完了

今年团队把Agent从"能跑通Demo"推进到"能抗住业务流量"的阶段时，最大的感受是：单机跑一个Agent很容易，但把几十上百个Agent按需调度、让任务精准触达合适的执行体、再把结果可靠回收，这件事的复杂度完全被低估了。我们内部做的这套编排与触达系统，就是Agent-Reach。

Agent-Reach的定位很朴素：它不是一个Agent框架，不负责Agent内部怎么思考、怎么调工具，它管的是Agent外面的那层"血管网络"——谁在提供服务、任务应该发给谁、发出去之后怎么知道有没有执行完、执行失败了怎么补救。用一句话概括：让任务可靠地触达正确的Agent，并拿到可验证的结果。

这个项目适合谁参考？如果你手头有多个Agent服务，靠硬编码调接口、靠人肉轮询结果、或者任务一多就出现"某个Agent被打爆、其他Agent闲着"的情况，那Agent-Reach的架构思路和踩坑记录应该能帮你少走不少弯路。文章里涉及调度策略、健康检查、失败补偿、分布式锁这几个核心模块，后面我按实际开发顺序来讲，每一步都附上了当时的取舍理由和实测数据。

先聊一个反直觉的结论：Agent越多，系统越不稳定。这不是说Agent本身质量差，而是Agent之间的负载均衡、超时控制、错误隔离如果没做好，数量上去之后故障会是雪崩式的。Agent-Reach最先解决的问题，就是给这一堆各自为政的Agent建立一套统一的上岗、排班、故障退役机制。

1.1 为什么"能跑"的Agent一堆，"能找到、能触达正确资源"的Agent很少

我们团队早期接Agent的方式非常原始：哪个Agent能干活，就在业务代码里写死一个HTTP调用地址；哪个Agent换了IP，改配置；哪个Agent挂了，等监控告警。这种模式下，一个Agent的不可用会直接导致一条业务链路失败，因为根本没有"换一个Agent继续"的选项。

更麻烦的是"能力匹配"问题。团队维护了十几个Agent，有的擅长做文本摘要，有的擅长结构化信息抽取，有的专门处理长文档翻译。业务方提需求时说的是"帮我处理这批文档"，但是处理这个词太模糊了，系统必须自己决定这批文档该走摘要链路还是抽取链路，或者按文档类型拆开分给不同Agent。没有一套能力描述和路由机制的时候，这个决策就是人肉做的，每次都要找算法同学问"这个该发给谁"。

Agent-Reach的设计目标就是把"人肉找Agent"变成"任务自己找Agent"。它在每个Agent启动时强制要求注册能力标签和吞吐参数，比如capability: summarization, language: zh, max_concurrency: 8, timeout_ms: 30000。注册之后，所有Agent对调度器来说就是一个可查询、可打分、可下线的资源节点，业务方只要关心任务怎么描述，不用关心背后的执行者是谁。

1.2 需求拆解：从任务下发到结果回收，中间隔了整个调度层

我们第一版思考Agent-Reach的时候犯过一个错：把重点放在"把任务发出去"上，写了一个分发器就以为完事了。结果上线第一天就暴露了问题——任务发出去了，但没人确认Agent到底收到没有；Agent执行到一半崩溃了，任务就永远停留在"已下发"状态；两个Agent同时抢到了同一个任务，数据被改了两次。

所以Agent-Reach的需求清单不是"能发消息就行"，而是四个连环能力：

• 注册与发现：Agent上下线能被系统感知，新扩容的Agent能自动进入调度池，不用改配置。
• 路由与匹配：根据任务类型、数据特征、Agent健康状态，决定任务分配给哪个或哪几个Agent。
• 执行与确认：不只是发出请求，还要拿到"接收确认、开始执行、执行结束"三阶段状态，状态可查询、可回溯。
• 补偿与降级：执行失败能自动重试或转交别的Agent，Agent集体不可用时有明确的降级策略，而不是原地报错。

这套清单定下来之后，Agent-Reach的架构就清晰了：它不是一条消息管道，而是一个围绕任务生命周期的状态机系统。后面的所有模块，都是在为这四个能力服务。

2. 整体架构：三层模型和一条消息闭环

Agent-Reach的代码结构按"接入、路由、执行"三层划分，每层职责单一，互不掺和。先说结论：这个三层模型不是一开始就设计出来的，是踩了"中间层想管太多"的坑之后重构出来的。

最早我们让路由层顺便干执行层的事——发消息、等结果、做重试全在路由模块里。结果路由模块越来越胖，每次改重试逻辑都要动路由代码，改出bug之后整个系统瘫痪。重构之后，路由层只回答一个问题："这个任务给谁"，至于给了之后怎么跟踪、怎么兑现，那是执行层的事。层与层之间通过任务对象（我们内部叫TaskEnvelope）传递信息，任务状态变更通过事件总线广播，各层订阅自己关心的事件。

2.1 接入层如何统一Agent注册与描述

Agent启动时调用Agent-Reach的注册接口，上报的信息不是简单的一个名字加地址，而是一份结构化的Agent描述。字段包括：

{ "agent_id": "sum-01", "name": "summarizer", "version": "2.3.0", "capabilities": [ {"type": "summarization", "languages": ["zh", "en"], "max_input_chars": 50000}, {"type": "key_extraction", "languages": ["zh"], "max_input_chars": 20000} ], "runtime": { "max_concurrency": 8, "timeout_ms": 30000, "preferred_queue": "cpu-bound" }, "health_check": { "path": "/healthz", "interval_sec": 15 } }

这里有个容易忽略的点：Agent必须主动上报自己的瓶颈维度。有的Agent是CPU密集型，有的其实是IO密集型（比如大量调用外部接口），如果统一按一个并发数来调度，CPU密集的Agent会被IO慢请求拖死，IO密集的Agent又吃不饱。Agent-Reach在注册描述里允许声明preferred_queue，调度器据此把Agent放进不同的资源池，避免互相干扰。

接入层还有一个容易被忽略的细节：版本兼容。Agent升级后接口协议可能有变化，注册描述里的version字段不是摆设。Agent-Reach在路由打分时会优先选择与任务要求版本匹配的Agent，避免老版本Agent处理新格式数据导致解析错误。这种情况在我们实际运行中遇到过几次，后面排查问题时发现都是注册信息没更新，Agent已经升到2.4了，注册表里还写着2.3。

2.2 路由层的匹配逻辑：标签、权重、健康度的三维打分

任务进来后，路由层把它拆成需求特征，再拿特征去Agent注册表里匹配。匹配不是"有或没有"的二值判断，而是一个三维打分模型：

• 能力匹配度：任务要求的技能类型，Agent是否具备；语言是否支持；输入规模是否在Agent能力上限内。
• 权重偏好：业务方可以为任务指定倾向，比如"尽量用便宜的Agent""必须在本机房执行"。
• 健康度：Agent当前的健康分数，由最近成功率、响应延迟、并发饱和度三个指标实时计算。

最终得分 = 能力匹配度 × 0.6 + 权重偏好 × 0.25 + 健康度 × 0.15。分数最高的Agent获得任务。

这个打分公式看着简单，但是健康度怎么算才靠谱，我们磨合了很久。有个教训是：不能只按最近一分钟的成功率算，因为Agent故障往往是瞬时的，一分钟的窗口太宽，等分数反映出来，任务已经积压了。后来改成三档滑动窗口——最近1分钟占60%，最近5分钟占30%，最近30分钟占10%，瞬时段权重放大，这样Agent一出现异常，路由能很快把流量转移走。

健康度里还要防一个"假死"问题：Agent线程池满了，来不及处理心跳检测，但进程还活着。这种情况健康检查接口会超时，健康度直接掉到很低，任务被路由走。等到线程池缓过来之后，Agent又恢复健康，这就形成了一种"震荡"。后面我们在执行层加了冷启动保护，刚恢复健康的Agent前两分钟只接收低优先级任务，先慢慢热身，避免一恢复就被灌爆。

2.3 执行层的触达协议与结果回收

执行层负责真正把任务交给Agent，并跟踪任务直到终结。Agent-Reach不要求在Agent端安装任何SDK，统一走HTTP回调协议，协议就三条：

1. 调度器发任务请求，Agent接收后立即返回accepted: true，只代表"收到"，不代表"做完"。
2. Agent执行完任务后，往回调地址POST结果，结果为标准JSON，包含task_id、status、output、metrics。
3. 如果Agent超过预定的超时时间没有回调，执行层主动轮询Agent的状态接口，确认任务到底还在不在执行。

为什么设计成"先ack后回调"而不是同步返回？因为Agent处理的往往是大任务，一个摘要任务可能要跑几十秒甚至几分钟，HTTP连接根本扛不住这么长时间的同步等待。异步化之后，调度器和Agent的耦合就弱了，Agent可以慢慢干活，干完再说。

结果回收是执行层容易被忽视的复杂点。回调可能乱序、可能重复、可能缺失，执行层要做三件事：幂等接收、状态合并、超时补查。幂等接收的意思是，同一个task_id的回调来了两遍，系统只认第一遍，第二遍直接丢弃。状态合并是因为Agent可能分阶段上报——"开始执行""中间进度""最终结果"，执行层要把这些碎片状态拼成一条完整的时间线，方便业务方追踪。

3. 核心实现：调度算法、并发控制与失败补偿

架构定了之后，真正的硬骨头在实现细节。Agent-Reach调度器一开始用的是最简单的轮询，后来改成带权重的最大堆，再后来发现问题不在选谁，而在怎么控速、怎么兜底。

3.1 动态优先级的调度循环

Agent-Reach的调度器核心是一个优先级队列，任务按优先级排序，调度循环每次从队头取任务，根据Agent的健康度和当前负载选出一个接收方。优先级不是任务进来时定死不变的，而是动态调整的——任务在队列里等待超过一定时间，优先级会逐步提升，避免长尾任务被新来的高优任务无限插队。

这个"等待越久优先级越高"的机制，实现上是一句话：effective_priority = base_priority + wait_time / 30，单位是秒。等待超过30秒，优先级自动涨一级。这样做的好处是，没人需要专门设计一个"饿死保护"模块，优先级自然会把长时间等待的任务推上去。

调度循环还必须响应Agent的负载变化。每个Agent暴露一个current_load字段，表示当前正在执行的任务数除以最大并发数。负载超过0.8的Agent，路由打分时会乘以一个衰减系数，负载超过1.0的Agent直接不参与本轮分配。这些数据通过Agent处理完任务后回调时携带，调度器在本地缓存一份，不需要额外的心跳通道。

3.2 并发阈值与队列背压

并发控制是Agent-Reach上线后第一个让我们意识到"不简单"的模块。最初版本没有并发限制，任务一多，所有任务同时涌向Agent，Agent直接OOM。后来给每个Agent设置了max_concurrency，调度器维护一个信号量，超过阈值就排队等待。这个排队等待是有讲究的，不是无限等，而是引入一条"队列长度红线"。

假设某个Agent最大并发是8，当前排队任务已经积压了50个，说明Agent已经处理不过来了。这时候再发任务进去毫无意义，只会让Agent的积压越来越严重。Agent-Reach的做法是：队列长度超过max_concurrency × 5时，触发背压机制，调度器不再向这个Agent发新任务，而是直接把任务重新路由到别的能力匹配的Agent。

背压机制上线之后，系统整体吞吐反而提升了20%。原因是Agent不再被无限塞任务，单位任务的处理时间变短了，健康度稳住了，调度器对它的打分也稳定了，整个系统的节奏就对了。

3.3 三种失败场景的补偿策略

失败处理是Agent-Reach里踩坑最多的地方。任务失败这事本身不可怕，可怕的是失败发生后，系统不知道任务去哪儿了。我们归纳了三种典型失败场景，分别给了不同的补偿策略：

• 发送失败：调度器连不上Agent，任务根本发不出去。这时先把任务放回队列，标记尝试次数，退回一秒后重试。超过三次还发不出去，就换Agent。
• 接收后无响应：Agent接收了任务但一直不回调结果，直到超时。这时调度器先主动查状态接口，确认Agent是否还活着、任务是否还在执行。如果Agent活着但任务卡住，把任务标记为"疑似卡死"，转交另一个Agent重新执行。
• 执行失败：Agent回调了status: failed，携带失败原因。这要看失败类型：如果是模型超时、外部API限流这类可重试错误，自动重试；如果是输入数据格式不对这种不可重试错误，直接回调给业务方，绝不重试。

补偿策略设计的几条硬性规定：一是所有重试必须幂等，任务重复执行不能造成重复扣费或重复写数据；二是补偿动作必须有审计日志，每次重试、转交都要记录原因和时间点；三是失败任务最多重试三次，超过三次进入死信队列，人工介入处理。这三条确保系统在任何情况下都不会无限自激循环。

4. 实测出来的三个坑：排查链路完整复盘

Agent-Reach在测试环境跑得顺风顺水，上了生产之后才陆续暴露出问题。这三个坑花费了我们最长的时间排查，每个都有代表性，值得单独复盘。

4.1 慢Agent拖垮整条队列：响应超时没有按Agent隔离

第一次生产事故是这样的：某个文本摘要Agent因为模型推理特别慢，平均处理时间从10秒涨到了60秒，但它的健康度还没掉到阈值以下，调度器仍然在持续给它派任务。结果这个Agent的积压队列越来越长，连带整个优先级队列的头部被拖住，后面所有任务都在等这个慢Agent释放并发额度。

排查链路是这样的：先看调度器日志，发现任务大量超时；再看Agent指标，发现某个Agent的P99延迟飙升；然后看调度器的队列深度，发现一个可疑现象——队列尾部积压的任务全是别的Agent能处理的任务，但因为调度循环每次都卡在向慢Agent发任务时的同步等待上，导致整个循环被拖慢。

修复方案有两个层次。第一层紧急修复：给Agent的请求发送改成异步非阻塞，发请求绝不等待响应，Agent的ack回来之后再走下一步。第二层根治优化：在路由打分时加入延迟感知——Agent的平均响应时间超过自身基线的3倍，健康度直接扣掉30分，让调度器快速绕开它。这次事故给我们的教训是，Agent的慢和挂是两种不同性质的故障，慢比挂更容易造成整体雪崩，因为挂掉是显性的，调度器很快会摘除它；慢是隐性的，不监控延迟就发现不了。

4.2 健康检查把刚启动的Agent误判为死亡

第二个坑是Agent扩容后出现的诡异现象：新启动的Agent在注册后始终接不到任务，但注册表里显示它在线。查了很久才发现，健康检查模块有一个"启动判定"逻辑——新Agent必须在60秒内连续返回三次健康，才会被标记为可调度；但是新Agent启动时由于要加载模型，冷启动需要90秒以上。结果就是Agent在60秒内只通过了两次健康检查，第三次健康检查时还在加载模型，接口超时，系统判定它健康不达标，把它放进"观察名单"，之后就不再接收新任务了。

这个Bug的隐蔽之处在于：健康检查的日志显示的是"健康检查通过次数不达标"，没有明确的告警，所以Agent一直处于"注册了但没被调度"的灰色状态。盯着注册表看是正常的，盯着任务分配看才发现异常。

修复方式是给注册接口增加一个warmup_seconds参数，Agent声明自己需要的冷启动时间。健康检查模块在这个时间内只记录结果，不做调度判定；时间到了之后，连续三次健康检查通过就转为正式可调度状态。同时监控面板新增一条"已注册但未就绪"的Agent列表，避免再有灰色状态淹没在正常列表里。

4.3 分布式锁过期导致同一任务被两个Agent执行

最严重的一个坑涉及任务去重。Agent-Reach为了确保同一个任务不会被重复处理，引入了Redis分布式锁——任务被某个Agent接收后，就给任务的task_id加一把锁，其他Agent看到锁存在就跳过。这个设计本身没问题，问题出在锁的过期时间上。

当时锁的过期时间设置的是30秒，而某些Agent执行一个任务要超过30秒。锁到期自动释放后，另一个Agent又抢到了同一个task_id，任务被重复执行。最直接的后果是：调用方收到两条一模一样的结果回调；更严重的业务后果是，如果任务本身是"给用户发消息"或"更新余额"，重复执行等于重复扣款。

排查这个问题的过程很曲折。最开始看到重复结果，以为是回调接口有bug，查了回调代码没有问题；又怀疑是Agent重复提交，看Agent日志只有一次提交；最后翻了分布式锁的key，发现锁还在，但TTL已经重置过了。这才意识到是锁过期导致第二个Agent进入。

修复方案不是简单把过期时间调长，而是引入续期机制——执行层启动一个守护协程，任务还在执行中，就定期给锁续期，直到任务终结才释放锁。这个方案的优点是不需要在设计上预估"最长执行时间"，不管任务跑10分钟还是半小时，锁都不会提前失效。同时增加了一层防重：Agent回调结果时带上一个全局唯一的执行实例ID，执行层如果发现同一个task_id已收到过结果，后到的直接忽略。

5. 优化后的效果与落地建议：先小规模再铺开

Agent-Reach上线三个月后，整体数据比第一版有了明显改善。核心指标对比如下：

这几个数字不是靠某一项优化达成的，是注册描述、路由打分、并发背压、失败补偿几个模块配合起来的结果。尤其是超时率下降，主要还是因为慢Agent会被健康度机制快速绕开，而不是硬等它超时。

最后说一点落地建议：如果你也想在团队内搭一套类似的Agent调度系统，不要急着把所有Agent接进来。先把两个业务形态差异最大的Agent接入，跑通注册、路由、补偿三个核心链路，观察一周的调度日志和失败数据，再逐步扩大范围。Agent调度系统最忌讳的就是一次性全量接入——出了问题连责任边界都分不清，到底是Agent本身的bug还是调度层的问题，排查成本会非常高。

Agent-Reach现在的版本还在持续迭代，下一步的计划是给路由打分模型引入更多维度的特征，比如数据分布相似度、历史协同成功率，目标是让"哪个Agent最适合这个任务"的判断更细腻。这个方向走通之后，Agent集群的效率和稳定性应该还能再上一个台阶。