★ FEATURED ARTICLE 如果你的多 Agent 系统只在一台机器上跑你可能还意识不到 Agent-Reach 的价值。等 Agent 被拆到不同容器、不同机器、不同网络区域后你就会遇到一类特别诡异的现象Agent 的进程明明活着日志还在打印但调度 Agent 就是连不上它。我在负责一个多 Agent 质检系统时被这个问题连续折磨了两周。后来折腾出了一个轻量工具就是 Agent-Reach。它解决的问题非常具体多 Agent 协作里的触达管理——Agent 如何注册、如何被感知、任务消息如何可靠投递。这篇文章会从一次真实事故讲起掰开揉碎介绍 Agent-Reach 的架构、核心算法、接入步骤和排查经验。无论你是在用 LangGraph、CrewAI 这类编排框架还是准备自己手写多 Agent 服务只要你的 Agent 需要跨进程、跨机器协作这篇文章里的思路都可以直接参考。1. 先从一次线上事故说起Agent 为什么叫不应1.1 一次真实的多 Agent 超时事故当时我们有一个质检系统跑着 12 个 Agent分别部署在两个机房和一组容器节点上。为了把这些 Agent 串起来我们用了主流的微服务注册中心做服务发现每个 Agent 启动后上报自己的 IP 和端口主调度 Agent 通过注册中心拿地址然后直接发起 HTTP 调用。起初一切正常直到某次发布后集中式调度器开始大量出现connect timeout很多子 Agent 的任务队列里堆了上千条消息。我们第一反应是网络问题于是登录到调度机器上手动 curl 那些 Agent 的地址。结果非常诡异几乎每个地址都能通端口响应也正常Agent 的健康检查接口返回 200。但一旦让调度器去调用真实的业务接口就有一半概率卡住最终超时。后来我们查了很久才发现问题出在受检 Agent 内部其中一个核心组件出现了死循环导致处理线程几乎被占满但负责健康检查的线程还能响应简单请求。这个事故让我彻底意识到传统微服务的注册中心模式放在 Agent 协作场景里是不够的。Agent 的可达不能只看进程是否活着更要看它有没有能力接收并处理当前的任务消息。为了应对这一类问题我需要一个专门为 Agent 设计的东西它得懂 Agent 的注册、心跳、网络探测和消息投递而不是让我把微服务全家桶搬过来再魔改一遍。后来Agent-Reach 就这么诞生了。1.2 Agent-Reach 是什么适合谁Agent-Reach 本质上是一个面向多 Agent 协作的轻量触达层。它不是一个完整的 Agent 框架不提供大模型推理能力也不替代 LangGraph 这类编排工具。它专注解决三个问题Agent 如何注册和发现、Agent 当前是否真正可达、任务消息如何可靠地投递到正确的 Agent 实例上。你可以把它理解成 Agent 世界的电话交换机 健康档案。Agent-Reach 用 Go 实现核心是一个中心服务各 Agent 通过多语言 SDK 接入。目前我主要维护 Python 和 Node 两种 SDK基本覆盖了实验性项目的常用语言。如果你正在做跨进程、跨机器部署的 Agent 协作尤其是遇到服务注册了但调用不到进程活着但任务不消费这类问题很适合尝试这套思路。如果你只是在本机用两个 Agent 做演示那暂时不必引入它Agent-Reach 的价值在于分布式环境下的确定性。2. 整体架构设计Agent-Reach 如何做到统一触达2.1 注册、探测、路由三层结构Agent-Reach 的架构不复杂核心是三个组件注册中心Registry、可达性探针Reach Probe和触达路由器Router。这三个组件互相配合形成一条完整的链路。注册中心负责维护每个 Agent 的元数据包括 Agent ID、能力标签、地址列表、版本号、启停时间等。它默认使用 SQLite 存储单机几百个 Agent 没问题如果要部署多副本可以把存储后端切换到 etcd。可达性探针会不断从注册中心拉取 Agent 地址并主动发起 TCP 探测测量往返时延、丢包率和连通性然后生成一个综合的可达性评分。触达路由器则是消息的发货员当调用方通过 Agent ID 请求某个 Agent 时路由器根据注册信息和评分结果选择一个最优实例把消息投递过去失败时自动进入重试流程。三者之间的数据流大致是这样的Agent 启动时SDK 先调用agentreach.Register()把自己注册进去然后后台线程每隔固定时间上报一次心跳服务端的探针从注册中心拿到地址列表主动测一遍并把结果写回注册中心当业务代码调用agentreach.Send()时Router 会结合注册列表、心跳状态、探测结果来决定投递路径。整个过程中调用方永远只关心 Agent ID不需要维护任何 IP 或端口表。这个设计带来的直接好处是你调整 Agent 副本、迁移服务器、更换容器网络都不需要改动调用方代码。2.2 为什么不用纯注册中心方案可能有人会问直接用 Nacos、Consul 这类注册中心不行吗我之前也这么想过但实践下来有几个坑。第一传统注册中心的健康检查通常看 HTTP/health接口返回 200 就认为是健康的。但 Agent 场景的问题在于健康接口可以很轻而实际业务处理线程可能已经被拖垮。也就是说传统健康检查给不出是否有能力消费消息的判断。第二Agent 的实例地址经常动态变化尤其是容器环境一个 Agent ID 可能对应多个实例传统注册中心虽然支持服务列表但按能力标签路由需要大量二次开发。第三注册中心本身不负责消息投递它只解决谁能被找到不解决消息怎么送进去。Agent 协作最关键的恰恰是后者任务消息要可靠地进入目标 Agent 的处理队列并且在失败时能够重试、转移。Agent-Reach 没有把自己定位成又一个注册中心而是把注册、探测和投递三个动作整合到同一个上下文里。调度决策可以同时参考元数据和实时探测结果尽量避免查到的节点活着结果一调用就超时的尴尬。这套逻辑用熟了以后你再回去看传统注册中心会觉得它只解决了一半问题。2.3 心跳与探测双通道的取舍Agent-Reach 使用了双通道来做可达性判断应用层心跳和服务端主动探测。这两条通道各有侧重缺一不可。应用层心跳由 Agent SDK 主动发起默认每 10 秒上报一次除了我还活着之外还会携带当前负载、正在处理的任务数、最近一次任务完成时间等业务状态。服务端主动探测则从 Agent-Reach 服务端的视角出发向 Agent 注册地址发送 TCP 探测包测量 RTT、丢包率等网络指标。双通道的价值在于互相校验心跳是 Agent 自己说的可能因为代码 bug 而失真探测来自服务端更接近真实调用的网络视角但它看不到业务内部状态。只有两者交叉才能同时发现进程假活和网络不通这两种问题。举一个实际例子某个 Agent 因为资源泄漏进入半死状态心跳线程还能跑但业务线程已经全部阻塞。此时链路探测可能完全正常不过 Agent 上报的正在处理任务数会持续上涨。Agent-Reach 就会结合这个业务指标把该 Agent 标记为业务性不可达而不是继续把新任务硬塞进去。反之如果心跳线程挂掉了但探测正常说明 Agent 进程还在但状态上报出了问题这种情况会触发告警但不会立刻判定为离线。两条通道互相印证信息更可靠。3. 核心细节可达性评分与可靠性投递3.1 AgentReachScore 评分公式Agent-Reach 最核心的指标是AgentReachScore范围 0~100。它不是简单的通或不通而是通过加权计算给上层调度提供一个精细的优先选择依据。默认公式是ReachScore 50 * heartbeatScore 30 * rttScore 20 * lossScore三个子分数的计算方式分别如下。心跳分数heartbeatScore取决于最近一次心跳的新鲜度设置的心跳间隔是 10 秒如果心跳 age 小于 10 秒取 1.0超过 30 秒后线性衰减到 0。RTT 分数rttScore根据服务端到 Agent 的探测往返时延计算小于 20ms 为 1.0大于 500ms 为 0中间线性映射。丢包分数lossScore基于最近 10 次探测的丢包率0% 为 1.0超过 30% 为 0。这三个权重不是拍脑袋定的。我们在压测中发现Agent 失去响应比单纯网络慢对协作体验的破坏要大得多所以心跳新鲜度权重最高RTT 主要影响单次调用的等待时长影响次之短期丢包可以通过重试来缓解所以权重最低。你可以根据自己网络的实际情况调整权重。比如在内网低延迟环境RTT 通常是稳定的个位数毫秒就可以降低 RTT 权重避免因为偶尔一次探测抖动导致误判。举个具体的计算例子。假设一个 Agent 最近心跳 age 为 12 秒探测 RTT 为 150ms最近 10 次探测丢包率 5%。那么heartbeatScore 1 - (12-10)/(30-10) 0.9rttScore 1 - (150-20)/(500-20) 0.73lossScore 1 - 5/30 0.83。最终ReachScore 45 21.9 16.6 83.5分属于可用但状态一般。这个评分会直接参与路由选择分数高的实例优先被投递。3.2 自适应探测频率与连接池隔离探测本身不能太频繁否则会无谓地消耗 Agent 资源和网络带宽但也不能太稀疏否则故障感知会变慢。Agent-Reach 默认的策略是Agent 状态健康时每 5 秒探测一次当某个 Agent 的 ReachScore 降到 60 以下时探测频率自动提高到 1 秒如果连续 3 次探测全部失败就会把该 Agent 标记为UNREACHABLE同时把重试探测的频率降为每 30 秒一次。这样既能在故障发生时快速发现又不会对着一个已经宕机的地址持续高频打探。这里有一个必须强调的细节探测用的连接池和业务消息投递连接池是要分开的。最初我的实现里探针复用了业务连接池结果在一次高负载测试中探针连接把连接池占满真实的任务消息反而排不进去了。后来我单独为探测维护了一个连接池默认最大 8 个连接超过就跳过本次探测。这个改动虽然不大但对稳定性提升非常明显属于那种不踩坑不会注意到的设计。另外探测结果还需要做平滑处理不能因为一次 RTT 抖动就疯狂改变路由。Agent-Reach 内部保存了最近 10 次探测结果的滑动窗口路由时取的是窗口内的加权平均值。这样做的好处是偶尔一次网络毛刺不会被当成 Agent 故障处理。3.3 重试、指数退避与死信处理Router 在投递消息时不会直接同步阻塞等待目标 Agent 返回。它先把消息写入一个本地持久化队列默认使用 BoltDB然后异步投递。这个设计其实是借鉴了消息队列的至少一次语义但用更轻量的方式实现。为什么不直接上 Kafka因为引入 Kafka 会增加部署复杂度对中小规模的 Agent 协作系统来说性价比不高。投递失败时Router 会按照失败原因做分流处理。目标 Agent 短暂不可达时进入重试队列按指数退避重试最多 5 次。第一次重试延迟 1 秒第二次 2 秒第三次 4 秒依次翻倍上限 30 秒。目标 Agent 返回业务错误比如当前负载已满或任务类型不受支持这时不盲目重试而是立即回调给调用方让上层 Agent 决定是否更换目标。重试次数耗尽后消息进入死信队列同时触发告警方便人工介入。因为投递是异步的调用方拿到的是一个任务提交结果而不是最终执行结果。如果你需要知道 Agent 是否真正处理成功就得依赖任务 ID 做结果回传。Agent-Reach 内置了结果回调接口Agent 处理完消息后可以调用agentreach.reportResult()把执行结果上报调用方通过agentreach.waitForResult()异步等待结果。这套机制对耗时任务非常友好不会让调用方一直占用一个同步连接。3.4 多副本与按标签路由Agent 生产环境中经常一个 Agent ID 下挂多个实例例如三个相同的文档解析 Agent 同时运行。Router 在选择目标实例时会先根据能力标签过滤然后在可用实例里按照ReachScore和当前负载综合排序选最优实例投递。默认策略是最高分优先但如果最高分和次高分之间差距小于 5 分会采用随机选择避免同一个实例被反复选中造成热点。标签路由是我在实际使用中认为最有价值的功能之一。你可以给每个 Agent 打上doc、image、gpu、cpu_only这类标签然后调用时指定标签要求。例如result agentreach.send( methodtask.process, tags[doc, gpu], payload{doc_id: abc123} )Router 会自动在带有这两个标签的 Agent 中筛选实例而调用方完全不需要关心具体是哪个 Agent 处理。这就让 Agent 的扩容和缩容变得非常灵活新加一个 Agent 实例只要打上相同标签立刻就能接到任务下线一个实例也只需要从注册中心摘除。4. 实操记录从零接入 20 个异构 Agent4.1 部署 Server 端与配置文件我推荐用 Docker 镜像方式部署 Server这样依赖干净、升级方便。需要在目标机器上准备好一个数据目录用来存放注册数据和持久化队列。启动命令如下docker run -d --name agent-reach \ -p 8800:8800 \ -p 8900:8900 \ -v /opt/agent-reach/data:/data \ agentreach/server:0.4.2这里 8800 是 HTTP 管理端口供查询和配置使用8900 是 Agent SDK 通信端口。如果不方便用 Docker也可以下载编译好的二进制文件直接运行./agent-reach-server --config config.yaml对应的config.yaml里我习惯重点配置这几项server: port: 8900 admin_port: 8800 storage: type: sqlite # 可选 etcd path: /data/agent-reach.db probe: interval: 5s fail_threshold: 3 retry_interval: 30s router: max_retry: 5 dead_letter: trueprobe.interval默认 5 秒是一个比较平衡的配置。调成 1 秒虽然故障发现更快但会让 Agent 的日志刷新得很快也会增加连接占用调成 10 秒以上则会让故障发现变得迟钝。除非你的监控系统有更高频的需求否则先用默认值。4.2 Python Agent 接入与消息收发以 Python 为例Agent 端接入分为三步注册、上报心跳、启动消息回调。第一步在 Agent 进程启动时初始化import agentreach agent agentreach.Agent( agent_iddoc-analyzer-01, tags[doc, gpu], addr172.18.0.5:7001, heartbeat_interval10 ) agent.register() agent.start_heartbeat()注意addr必须是其他 Agent 也能访问到的地址不能写127.0.0.1否则 Agent-Reach 服务端从别的机器探测时永远连不通。这也是新手最容易踩的坑之一。第二步把 Agent 的业务处理函数暴露成回调接口。Agent-Reach 提供了一套简单的装饰器from agentreach.web import route route(task.process) def handle_task(task_id: str, payload: dict): result process_document(payload[doc_id]) return {code: 0, data: result}装饰器会在 Agent 本地启动一个 HTTP 服务把task.process映射到对应路径。Router 投递消息时会携带task_id、method、payload三个字段自动 POST 到这个路径。第三步调用方发消息result agentreach.send( agent_iddoc-analyzer-01, methodtask.process, payload{doc_id: abc123}, task_idtask-20240915-001 )task_id我强烈建议由业务自己生成。如果不传SDK 会生成一个 UUID但你没有办法在业务上关联原始请求。有了自己的task_id后续幂等和排查都会方便很多。4.3 用管理接口验证触达状态部署完成后可以通过管理端口快速检查集群里的所有 Agent 状态curl http://localhost:8800/api/v1/agents返回的 JSON 数组里每个 Agent 会包含reach_score、probe_status、last_heartbeat、last_probe_error等字段。我当时的 20 个 Agent 里19 个reach_score稳定在 95 分以上只有一个跨专线部署的 Agent 因为 RTT 一直在 300ms 左右分数只有 70 多但仍然属于可用状态。我还会用另一个命令观察消息投递指标curl http://localhost:8800/metrics重点关注agentreach_router_delivery_total、agentreach_router_retry_total和agentreach_router_dead_letter_total三个指标。如果重试次数持续上升说明网络不稳定或者目标 Agent 应用层处理能力不足需要进一步排查。4.4 长任务与异步回调的处理Agent 处理任务不总是瞬间完成的。有些任务比如批量文档分析可能需要几十秒甚至几分钟。如果调用方一直同步等结果会把连接资源和调用线程都占住。Agent-Reach 对此有两种处理方式。第一种Agent 收到消息后立刻返回一个已接收状态然后在后台任务完成后通过agentreach.reportResult()回调结果。第二种调用方在发送消息时传入timeout参数并配合waitForResult()做异步等待。我在接入那个质检系统时把所有耗时超过 5 秒的任务都改成了异步回调模式系统吞吐量立刻上了一个台阶。这里要给 Agent 开发者一个建议回调接口一定要做并发控制。我最初把 Agent 回调用的是单线程 HTTP 处理结果连续投递几十个长任务后回调端口自己先堵了大量消息堆在 TCP backlog 里看起来服务端一直在重试实际 Agent 根本来不及消费。后来给回调接口增加了线程池并用max_concurrency元数据告诉 Agent-Reach 当前实例的并发上限路由时自动跳过已经达到上限的实例问题迎刃而解。5. 常见问题与排查技巧实录5.1 显示不可达但手动连接正常这是 Agent-Reach 落地时最常被问到的现象管理接口显示某个 AgentUNREACHABLE但手动curl或nc连接又通。一般情况下问题出在判断维度不同。Agent-Reach 判定不可达是综合了心跳新鲜度和服务端探测结果而手动 curl 通常只验证了端口通。常见原因有三个。第一Agent 的心跳线程被业务代码阻塞了。比如 Agent 里有一段同步调用迟迟不返回把心跳 goroutine 也拖住了心跳续不上评分自然归零。第二Agent 注册的地址用了127.0.0.1或内网映射地址Agent-Reach 服务端从外部探测不到。第三云端环境对 ICMP 或 TCP SYN 限速导致探测包大量丢失但业务流量因为走了别的高速通道反而正常。排查时不要只看最终状态要先查last_heartbeat和last_probe_error。如果last_probe_error有内容你需要在 Agent-Reach 所在机器上手动执行nc -vz agent_ip port确认网络链路是否真的通。如果探测正常但心跳断了那问题基本在 Agent 进程内部需要去看 Agent 的日志和线程状态。5.2 消息重复执行与幂等处理Agent-Reach 默认是至少一次投递语义所以重试不可避免地会带来重复消息。如果你收到的任务里有少量重复这其实是正常现象真正要做的是保证消费端的幂等。我常用的方案是在数据库里维护一张任务执行记录表利用唯一索引来过滤重复任务INSERT INTO task_execute_log(task_id, agent_id, status) VALUES (?, ?, processing) ON CONFLICT(task_id) DO NOTHING;如果插入影响行数为 0说明这个任务之前已经处理过直接返回成功不再执行业务逻辑。这个方案比先查再插入要稳妥能避免并发重复投递时两个人同时查到不存在然后一起执行。注意唯一索引要建立在业务幂等键上而不是 Agent 生成的随机 UUID。5.3 多副本下的路由超时调优如果你一个 Agent ID 挂了多个副本但还是频繁出现路由超时核心原因是 Router 选中的实例恰好没有消费能力。比如两个文档分析实例一个空闲一个已经积压了大量任务但因为它们的 ReachScore 差距不大Router 随机选中了积压实例消息就卡住了。解决办法有两个方向。第一Agent 上报心跳时务必把current_load这个字段填对。Router 在选择实例时不仅看 ReachScore还会参考current_load和max_concurrency负载高的实例天然会被降权。第二在 Agent 回调接口处设置合理的并发上限。如果并发数只设 1那么来两个任务就会有一个端口响应变慢导致 Router 误判为网络问题而触发重试。我在容器环境里通常把并发数设为 CPU 核数的两倍效果不错。5.4 排查速查表症状可能原因检查方法显示 UNREACHABLE注册 IP 外部不可达、心跳线程阻塞在 Server 端执行nc -vz agent_ip portReachScore 持续偏低网络 RTT 高、丢包严重查看/metrics中probe_rtt_ms和probe_loss_rate任务积压但 Agent 不消费业务线程池占满、并发上限过低查看 Agent 上报的current_load和max_concurrency重试次数飙升目标 Agent 应用层处理能力不足查看agentreach_router_retry_total指标变化趋势数据目录增长过快死信队列积压过多调整死信队列保留策略只保存必要字段这张表是我在实际项目中的速查清单覆盖了我遇到过的大部分问题。当然场景不同细节会有点差异但排查方向基本一致。6. 同场景下的三个扩展方向6.1 从单组网走向多组网Agent-Reach 目前的多 Agent 协作还没有支持多租户联邦。如果你有多个互不相通的网络区域每个区域内部部署独立的 Agent-Reach区域之间默认是隔离的。我最近在尝试让不同的 Agent-Reach 服务之间建立联邦关系通过一个轻量的目录同步机制让跨区域调用可以像本地调用一样按 Agent ID 路由。这个做法的难点在于区域间网络往往不稳定需要把探测和路由的粒度都加一层。如果只是想做简单的多区域分发可以先不用等待这个功能。你可以在上层编排 Agent 里做区域策略通过 Agent-Reach 的标签能力把不同区域标记成不同标签调用时指定标签路由器自然只会选符合条件的实例。6.2 从通用探测到任务级探测当前 Agent-Reach 的可达性评分是通用的只衡量网络和应用基础状态。但在真实业务里同一个 Agent 可能对不同类型的任务响应差异很大。例如一个 Agent 既支持文本处理也支持图片处理GPU 实例的图片任务表现很好文本任务却因为资源竞争响应很慢。我下一步打算在注册数据里加入能力资源维度让每个 Agent 能够声明某个方法预期的 RTT 和并发能力Router 在投递不同任务时参考不同的评分权重。这样可以让调度更精准但也会让配置和维护更复杂。对于现阶段大多数实验项目来说通用评分已经足够用了。6.3 一个可以马上动手的小优化如果你想在现有 Agent-Reach 版本上立刻优化效果我建议从心跳载荷入手。SDK 默认上报的心跳消息里除了 Agent ID 和负载还可以加两个自定义字段last_task_duration和consecutive_failure_count。前者可以让 Router 感知到实例近期处理任务的平均耗时后者可以用于在服务端做降级预判。一旦某个实例连续上报了 3 次失败计数就可以提前把它从路由池中暂时移除而不是等任务消息真正发过去之后再等超时。这个小改动不需要改服务端逻辑只改 SDK 的心跳字段和服务端的权重规则收益却很直接。最后再分享一点个人体会。我在多 Agent 系统上折腾了这几年最大的感觉是大家很容易把注意力放在Agent 聪明不聪明上却忽略了底层的协作工程问题。Agent-Reach 解决的不是智能问题而是稳定性问题。它让我在写业务逻辑的时候再也不用担心这个 Agent 到底叫不应怎么办因为这些都交给触达层去管了。如果你正在做类似架构希望这篇文章里的思路能帮你少踩几个坑。
阅读完成 · 觉得有帮助？
