做分布式Agent调度做了两年多，我最怕的两件事，一是Agent悄悄死掉但调度方还蒙在鼓里，二是消息明明发出去了，却没有任何一条日志能证明它真的到了目标节点。后来我把这套能力沉淀成一个独立组件，起名Agent-Reach。它不做业务消息转发，只专注一件事：让调度方以可验证、可观测、可恢复的方式确认目标Agent确实收到了调用，并且知道它当前是存活、可疑还是已离线。实际跑下来，线上"任务神秘消失"的工单量直接降了一个数量级。这篇文章打算把Agent-Reach的设计思路、关键路径、踩坑过程和上线后该盯的数字一次讲清楚，希望能给同样在做Agent编排的朋友一个可直接参考的样板。
1. Agent-Reach到底解决了什么问题
1.1 分布式Agent最容易被忽视的"送达假设"
先講一个我们线上发生过的典型故障。调度服务往任务队列里塞了一条消息，状态置为"已提交"，业务方也确认"发出来了"，但下游Agent因为网络分区根本没收到。从调度方视角看，这条任务没有失败、没有超时、没有任何异常，它就像凭空消失了一样。最后靠人肉对日志才发现，消息在队列里积压了四十分钟，Agent重连成功后才被消费掉，而调度方的超时时间只有三十秒。
这种问题在单个服务、单机进程里几乎不存在，一旦拆成多个Agent、多个进程，事情的复杂度就上来了。Agent的存活不是一成不变的，它可能正在发版重启、可能被OOM杀掉了、可能是网络抖动导致端口不可达、也可能是它自己陷入了死循环但进程还活着。调度方如果默认"只要写入队列就算送达到"，那后续所有的失败补偿、任务幂等、状态恢复都建立在一个不牢靠的假设上。
Agent-Reach的出发点很简单：把"送达"从一个隐含假设变成显式状态。它不会替你做业务决策，但会告诉你某个Agent在某个时刻是否真的可用，以及你对它发起的调用到底有没有被确认收到。有了这层信息，调度方才敢去重试、补投或者切换策略。
1.2 Agent-Reach的定位：在业务通信之下补一层"可达性底座"
先说清楚边界，Agent-Reach不是消息队列，也不是RPC框架。消息队列解决的是"如何把消息暂存并投递"，RPC解决的是"如何把请求发到远端并返回结果"，Agent-Reach解决的是"目标Agent当前是否可达，调用是否被确认"。它更像一个保险层，架在调度方和业务Agent之间，专门管理注册、心跳、探活、回执和补偿。
设计Agent-Reach时我给自己定了几条约束：
- 不侵入业务协议。Agent内部仍然用自己习惯的HTTP、gRPC或者内部RPC处理业务，Agent-Reach只做旁路探测和回执确认。
- 状态中心要足够轻。集中式状态节点只维护Agent元信息和可达状态，不碰业务数据，避免成为性能瓶颈。
- 所有判定必须可配置。心跳间隔、超时次数、重试窗口、熔断阈值都要能以配置项调，不能写死。
加入Agent-Reach之后，一次普通调用的请求链变成这样：调度方先问Agent-Reach"目标在不在线、地址是什么"，拿到可用端点后再发起业务调用；业务调用完成后，Agent进程把回执发给Agent-Reach；Agent-Reach更新调用状态，调度方通过回调或轮询确认最终结果。如果目标不可达，Agent-Reach会在重试窗口内试探，直到恢复或者彻底判定失败。这个模型不强求每个环节都同步，但每个环节的状态都能被查询和审计。
2. 核心设计：四条链路怎么把"送达"做成可验证的
Agent-Reach的功能拆开看其实只有四件事：注册与心跳、探测与回执、降级轮询与重试抑制、不可达状态机。四者加起来，才构成完整的"可达性保障"。
2.1 注册与心跳：让"你知道它在哪"变成可靠数据
每个Agent启动后做的第一件事，是向Agent-Reach的状态中心注册。注册信息包括agent_id、对外暴露的endpoint、当前承载的能力列表以及注册有效期TTL。TTL是必须有的，因为Agent可能优雅退出也可能直接宕机，状态中心不能一直保留死节点的信息。
Agent在线期间会持续发送心跳。默认心跳间隔是30秒，连续3个心跳周期没有续期，Agent被标记为suspect（可疑）；再过一个周期仍未恢复，标记为offline（离线）。这里刻意做了两个状态而不是一刀切，原因很实际：瞬时网络抖动非常常见，如果第一次心跳超时就立即把Agent从可用列表里踢掉，调度方会无谓地把大量请求切到别处，反而造成负载倾斜。
为什么不直接用注册中心的下线通知来做？因为我们没法保证"下线通知"一定能送出去。进程可能被kill -9杀掉，宿主机可能宕机，Agent自身的回调可能异常。只有主动心跳配合超时判定，才能在极端情况下给出可靠结论。这一点跟很多高可用设计思路一致：不要依赖对方的自觉退出，要让中心节点自己判断时间戳。
2.2 探测指令与回执：从单程发送到全链路确认
Agent-Reach发送探测时，会给每一次调用生成全局唯一的request_id。这个request_id贯穿三个环节：调度方发起、目标Agent收到、目标Agent回执完成。三个环节都会记录时间戳，方便后期统计延迟和定位卡点。
这里要区分两个回执概念：一个是"收到"，一个是"完成"。目标Agent收到请求后，可以先返回一个received确认，表明消息到达进程内部；业务逻辑执行完毕后，再发送一个completed确认，表明结果已产出。对应到Agent-Reach里就是ack_mode参数，支持只确认到达，也支持确认全链路完成。调度方可以按业务场景选择，比如下发配置只需要到达，数据加工任务则必须等到完成。
两个回执都要求幂等。Agent-Reach靠request_id去重，重复收到同一请求的回执不会产生新状态，只会刷新最后更新时间。这个设计在后面对抗网络重复投递时非常有用，否则一次网络重试可能造成两份回执，业务方又要多写一堆判重逻辑。
2.3 降级轮询与重试风暴抑制
调用发出去了，回执迟迟不来，最常见的第一反应是"再发一次"。但如果目标Agent只是处理慢或者正在GC，重发只会加剧对方的压力，形成雪崩。Agent-Reach把重试做成了有节奏的降级轮询，而不是无脑重发。
具体策略是：第一次投递后等待回执，超时后进入重试窗口。重试间隔按指数退避加抖动走，初始1秒，之后2秒、4秒、8秒，最大不超过120秒。同时每个request_id最多重试一定次数，超过上限就标记为failed，把失败信息交给调度方，由上层决定是跳过还是人工介入。
更关键的是熔断。如果状态中心发现某个Agent的不可达率持续超过阈值，会临时将它标记为熔断，短时间内不再对同一个Agent发起新的探测。熔断不是永久隔离，只持续一个配置窗口，窗口过后恢复探测。这个机制有效避免了集群里出现一个慢节点时，所有任务都挤向它、又全部超时的情况。
2.4 不可达状态机与补偿队列
Agent-Reach为每个Agent维护一个状态机，节点在reachable、suspect、unreachable、recovering四个状态之间迁移。从unreachable恢复到reachable必须先经过recovering，recovering期间Agent-Reach会主动发送一次探活请求，而不是等心跳周期自然到期，这样恢复检测的响应速度更快。
补偿队列放在状态中心侧，专门用于暂存"目标不可达但还需要投递"的请求。队列有大小上限，默认2000条，超过上限的新请求直接返回失败并给出明确错误码，而不是无限堆积。每条补偿消息保留原始request_id、payload指针和过期时间，Agent恢复后按优先级补投。
这样设计的直接好处是：调度方不必自己维护一张复杂的待重试表。如果Agent宕机五分钟，补偿队列负责在这五分钟内兜住需要投递的消息；Agent恢复后，补投逻辑自动触发。整个过程在Agent-Reach内部闭环，调度方只需要关注最终的成功或失败事件。
3. 从零跑通的关键路径：配置、接口与一个最小示例
先给一个结论：Agent-Reach的上手门槛不高，但有几个配置项一开始必须理解，否则后面会遇到"为什么我运行半天还是没效果"的困惑。
3.1 环境准备与依赖选择
Agent-Reach的SDK我选型时坚持用了Python + asyncio。原因很直接：Agent进程通常是IO密集型的，异步模型可以让心跳、回执、业务调用并发跑，不会因为一次网络等待阻塞整个事件循环。依赖越少越好，核心只要httpx、pydantic和一个pickle或JSON序列化器，避免引入重框架。
状态中心我拆成两个部署形态：本地开发用SQLite加文件存储，零配置直接起；生产环境用PostgreSQL存储注册信息和状态变更流水。Redis可以用作可选的缓存层，但我不建议把状态中心的持久化完全押在Redis上，因为Agent注册信息是基础元数据，丢了会造成全量重新上线风暴。
Agent侧接入只需要做三件事：第一，启动时调用sdk.register();第二，启动后台心跳任务；第三，在业务处理完成后调用sdk.ack()。业务代码本身不需要大改，这算是我当时定下的硬性要求。
3.2 最小示例：一个能跑起来的Agent对
我写一个极简示例方便说明。假设有一个worker Agent，它暴露出一个处理文本的任务接口。Agent-Reach SDK在它启动时完成注册，业务处理完成后发送completed回执。
# agent_worker.py import asyncio from fastapi import FastAPI from agent_reach import AgentReachAgent app = FastAPI() # 初始化Agent-Reach SDK，连接状态中心 reach = AgentReachAgent( state_center_url="http://localhost:8100", agent_id="agent-worker-3", endpoint="http://localhost:9001", capabilities=["text.process"], heartbeat_interval=30, ) @app.post("/tasks/text_process") async def handle_task(request_id: str, payload: dict): # 业务处理 result = do_some_work(payload) # 业务完成后发送completed回执 await reach.ack(request_id=request_id, status="completed", result=result) return {"ok": True}调度方这边通过Agent-Reach的Client发起调用：
# dispatcher.py from agent_reach import AgentReachClient client = AgentReachClient(state_center_url="http://localhost:8100") request_id = await client.probe( target="agent-worker-3", capability="text.process", payload={"text": "hello"}, ack_mode="completed", timeout=30, ) # 轮询状态，或者注册回调 result = await client.wait(request_id, timeout=60)这里最容易被忽略的一个点：probe接口返回的request_id是整个链路的核心凭证。后续查询状态、取消补偿、审计延迟，全都要带上它。我见过有人直接在日志里只打印目标Agent的ID，出问题时空有agent_id没有request_id，根本查不到那次调用的记录。所以工程上要求所有业务日志必须在上下文里透传request_id，不只是Agent-Reach的日志要带，业务日志也要带。
3.3 验证四步自检
跑通最小示例后，建议按下面四步做一次自检，确保不是"看起来通了"。
- 注册检查：启动Agent后，在状态中心查询agent-worker-3的状态，确认endpoint和capabilities都正确入库。
- 进程存活检查：对Agent进程执行kill -9，等待心跳超时窗口，再查询状态，确认它从reachable变成suspect，再变成offline。
- 断网重试检查：把Agent的监听端口临时停掉，用调度方发起probe，确认Agent-Reach进入指数退避重试流程，并且没有疯狂重发。
- 恢复补投检查：重新启动Agent，确认状态进入recovering后自动恢复reachable，补投队列里的任务被重新执行，并且回执状态正确。
这四步做完，Agent-Reach在你这套环境里的基础能力才算验证过。很多问题会在第一步和第二步中间暴露出来，比如防火墙挡了心跳端口、Agent ID重复注册导致状态被互相覆盖，这类问题越早发现越省心。
4. 落地时踩过很真实的坑：回执丢失让任务被重复执行
结构设计好了，真正上线时还是出事。这个坑我认为很有代表性，值得完整复盘。
4.1 症状：半夜任务"消失"，第二天业务方要求解释
现象是：一部分任务没有执行结果，但调度方显示任务已经超时失败，并且触发了自动重试到另一个Agent。问题在于原Agent其实已经处理完了任务，只是结果没有回报给调度方，导致同一条业务被处理了两遍。第一遍的结果被当作垃圾回滚，第二遍又跑了一次，数据出现不一致。
如果只是超时，问题还好定位。这次诡异在：原Agent的业务日志明确打印了"任务处理完成"，但Agent-Reach状态中心里，这条request_id的状态却一直是pending。回执丢失了。
4.2 完整排查链路
我按时间线把排查过程列出来，方便复现。
第一步，先看状态中心的回执日志。结果发现没有收到任何来自目标Agent的回执请求。问题不在网络传输层面，因为其他Agent的回执都正常送达。
第二步，登录目标Agent机器，查Agent-Reach SDK进程是否存活。进程活着，心跳也正常。但确认到一条关键日志：SDK尝试发送回执时抛出了连接池队列满的异常。异常被业务代码吞掉了，所以业务侧看起来一切正常。
第三步，定位连接池队列为什么满。Agent内部业务回调使用的是一个独立的HTTP客户端，这个客户端在业务高峰期被大量调用。问题出在代码里很多地方用了未设置超时的同步调用，请求发出去后一直阻塞占着连接，把连接池的队列占满了。到了晚上峰值，回执发送这种非业务关键操作就被排在业务调用后面，迟迟拿不到连接。
第四步，计算时间线：调度方probe设置的超时是30秒，目标Agent实际在第10秒就处理完了业务，但回执一直排队，直到50秒后才发出来。调度方在30秒时已经判定失败并触发了重试，所以即使回执迟到，它也只能当作无效数据。
这个坑的本质是：Agent-Reach把回执当成了业务关键路径上不可分割的一部分，但回执通道本身没有独立的资源保障。当业务流量暴涨时，回执和业务调用争抢同一个HTTP连接池，业务优先、回执饿死。
4.3 修复与设计变更
修复分为三部分。
第一，把回执发送从业务线程池里彻底拆出来，使用独立的连接池和独立的发送队列。回执发送不占用业务线程，业务再忙也不能阻塞它。
第二，给所有回执发送请求设置短超时，默认3秒，失败后不立即重试，而是写入本地的回执待发送文件，由后台任务每5秒扫描一次补偿发送。这相当于给回执也加了一层持久化保护。
第三，调整Agent-Reach的语义：当SDK收到业务完成信号后，必须同步落一条ack记录到本地存储，再异步发送给状态中心。状态中心以收到的ack为准，但本地存储作为审计底账，避免进程崩溃后完全丢失现场。
修复后我特意做了两次压测：把Agent的并发业务请求抬到平时峰值的三倍，同时关闭回执连接池的一部分连接，确认回执通过独立通道仍然在数秒内送达。这个场景成为Agent-Reach的回归测试用例，后续每次发版都会跑一遍。
5. 生产环境容量与配置经验
Agent-Reach上生产后，印象最深的是"看起来不起眼的心跳，也会成为流量"。容量规划不能只盯着业务调用看。
5.1 心跳、探测、回执的QPS怎么算
假设集群里有1000个Agent，心跳间隔30秒，那么状态中心每秒收到的心跳请求大约是1000除以30，约33个请求每秒。这个数字不大，但要注意心跳请求是很规律的，不像业务流量有波峰波谷，它会稳定地占着连接数。
业务侧假设每天500万次调用，一天按八万秒估算，平均每秒大约60个探测请求。加上回执，每秒大约120个左右。两项加起来，Agent-Reach状态中心在1000个Agent规模下需要支撑的QPS大约是150到200。一个单实例的Python异步服务用两核CPU完全扛得住，瓶颈通常不在CPU而在数据库连接数和日志IO。
真正需要留意的不是平均QPS，而是瞬时峰值。发版时刻所有Agent同时重启，会触发一波注册风暴。1000个Agent同时注册，每秒可能有几千个请求涌向状态中心。我建议状态中心按峰值十倍容量设计连接池，数据库连接数不要设太低，否则发版时会成为新的瓶颈。
5.2 一套可落地的参数配置
我按自己的生产环境给出一组参考参数，具体值还是要根据业务调整。
| 配置项 | 默认值 | 说明 |
|---|---|---|
| heartbeat_interval | 30秒 | 心跳间隔，Agent数量多时可适当调大 |
| suspect_after | 3个周期 | 连续N个周期未续期进入可疑状态 |
| offline_after | 4个周期 | 再一个周期未恢复进入离线状态 |
| probe_timeout | 10秒 | 单次探测的业务超时时间 |
| retry_initial_interval | 1秒 | 指数退避初始间隔 |
| retry_max_interval | 120秒 | 退避最大间隔 |
| retry_max_times | 3次 | 单次请求最大重试次数 |
| circuit_breaker_threshold | 80% | 目标Agent不可达率超过此值触发熔断 |
| circuit_breaker_window | 60秒 | 熔断窗口 |
| compensation_queue_limit | 2000条 | 补偿队列上限 |
这里我要特别强调probe_timeout和retry_max_times的关系。很多调度方会把超时设成60秒、重试设成10次，表面看更保险，实际会把问题放大。如果目标Agent真的处理不过来，60秒超时加10次重试会让同一份请求在坏节点上反复被打，坏节点更不可能恢复。短超时加有限重试，配合熔断，是更可持续的组合。
5.3 监控与告警阈值
Agent-Reach上线后我加了一套监控，指标不多，但每个都有明确含义。
- 可达率：当前所有Agent中处于reachable状态的比例。正常应该长期在99.9%以上，低于99%就需要看是否发生了大面积重启或网络故障。
- 回执率：状态流转到完成状态的请求占比。回执率持续走低，往往反映目标Agent业务处理异常或回执通道阻塞。
- ACK延迟P99：从发出的probe到收到completed回执之间的时间差。这个指标比平均延迟重要得多，P99一旦飙升，用户会开始感知到任务变慢。
- 补偿队列长度：补偿队列积压数量。平时应该趋近于0，持续上涨说明有Agent长时间离线，需要人工确认。
告警阈值可以这么设：可达率低于99%触发warning，低于95%触发critical；ACK延迟P99超过超时阈值的80%触发warning；补偿队列长度超过1000触发warning。不要用固定的"超过100就报警"这种死值，需要基于你自己的基线去定。
6. 什么时候不要用Agent-Reach，以及下一步扩展方向
介绍完Agent-Reach的能力和指标，我也得泼泼冷水。它不是万能组件，在某些场景下上了反而多余。
只有两个Agent、用同一个消息中间件、链路偶尔失败也能接受的时候，完全没必要引入Agent-Reach。它会成为系统里额外的一个状态中心，多一个需要运维的组件，并且增加首调延迟。小规模系统把RPC超时重试做好就够了，没必要为"可达性"专门建一层底座。
另外，如果你们的消息中间件本身提供了强一致的回执能力，比如某些事务消息方案，再叠一层Agent-Reach会显得重复。Agent-Reach的定位是补足那些缺保障的系统，而不是在所有地方都强行加一道。
再聊一些我自己觉得有价值的扩展方向。第一个是多协议支持，现状是SDK内部对HTTP做探活，但很多Agent的对外接口是gRPC或者自定义长连接。把探测能力抽象成协议插件，是下一步最自然会做的事。第二个是面向路由的可达性预测，等运行数据积累得足够多，Agent-Reach可以根据历史心跳频率、资源指标、故障模式预测某个Agent在未来几分钟可能的不可达概率，再把这部分信息反馈给调度方做路由决策。第三个是主动混沌注入，比如在测试环境随机断开Agent网卡、随机阻塞心跳，验证补偿队列和熔断逻辑是否真的能兜住，这比任何静态测试都有说服力。
最后说一点个人体会。最早我以为Agent-Reach要解决的是"消息不丢"，做完之后才明白，真正要解决的是"系统不能被隐式假设欺骗"。任务发出去了不代表送达了，连接建立过不代表现在还通着，进程活着不代表它能响应业务。把每个环节都变成显式可查的状态，遇到问题才有快速定位的可能。如果你也在做类似的分布式Agent体系，我建议先别急着加消息队列、加注册中心，先把你最核心的那条调用链路上的"Reach"搞清楚，很多线上事故的根因都会提前暴露出来。
