Agent-Reach：多智能体协作的通信协议与运行时框架

我先跟你交代一个背景：去年我在搭建一套由十几个大模型驱动的工作流集群时，被一个问题卡了整整两周——模型能力没问题、prompt 也调得不错，但各个节点之间就是"找不到对方"。有的智能体在服务注册表里能看到，但消息发过去石沉大海；有的明明部署在同一台机器上，却因为端口写错互相视而不见。这套系统就像一屋子人各说各话，谁也联系不上谁。当时我意识到，多智能体协作最缺的不是更强的模型，而是一套让 Agent 互相"认路、敲门、对话"的通信底座。后来我把这套思路落了地，起了个名字叫Agent-Reach。这篇文章想跟你聊聊它的设计逻辑、核心机制，以及我在实际部署中踩过的坑。

Agent-Reach 本质上是一套面向 AI 智能体之间互联的轻量级通信协议与运行时框架。它解决的是智能体在分布式环境下的服务发现、寻址建连、会话保持和可靠消息投递问题。适合正在做多智能体系统、Agent 工作流编排、人机协同中台，或者干脆被"Agent 之间怎么互相调用"折磨过的开发者参考。下面我按自己真实开发的顺序，把整个项目从动机到落地拆开讲。

1. 为什么需要 Agent-Reach：多智能体协作的通信断层

先回顾一个行业背景。2023 年到 2024 年，智能体（Agent）这个词从一个学术概念变成了工程事实。LangChain、AutoGPT、MetaGPT 这些项目把"大模型 + 工具 + 记忆 + 规划"的组合打成了标配。但大家慢慢发现一个尴尬的问题：单 Agent 很聪明，多 Agent 很混乱。如果你只有一个 Agent，它自己调用工具、自己写文件、自己回复用户，事情很简单。可一旦把系统拆成"规划 Agent、执行 Agent、审查 Agent、记忆 Agent"这样的协作网络，通信问题就变成了头号敌人。

举个例子。我最初的架构很简单：一个 Planner 负责拆解任务，把子任务派给两个 Worker，等 Worker 返回结果后再汇总。当时我用的是最原始的办法——把任务写进共享的 Redis 队列，Worker 轮询队列拿任务，再把结果放到另一个队列。这个方案在小规模时能跑，但当 Worker 数量到了五个以上、任务之间开始出现依赖关系时，轮询队列的方式就彻底失控了。

这里有几个典型痛点：

• Agent 之间的寻址没有标准。每个 Agent 怎么描述自己是谁、能干什么、如何被调用？没有统一办法，大家各自为政。
• 发现机制缺失。新上线一个 Agent，老 Agent 怎么知道它存在？靠配置文件写死 IP 和端口的做法，在动态伸缩场景下完全不可用。
• 协议割裂。有的 Agent 走 HTTP，有的走 WebSocket，有的走 gRPC，还有的干脆只认 MCP。要让它们互相通信，得写一堆适配层。
• 消息不保障。任务发出去了，对方到底收到没有？收到后处理成功了吗？失败了怎么重试？这些问题在模型驱动的异步场景里被无限放大，因为 Agent 处理一个任务可能耗时几十秒甚至几分钟，超时、重试、乱序的几率远超普通微服务。

Agent-Reach 就是在这样的背景下产生的。它的目标不是重新发明一套 RPC，而是站在智能体的角度，把"我要找谁干活、怎么找到它、怎么保持对话不断线、怎么确认活干完了"这几个问题一次性解决。

2. Agent-Reach 的整体架构与分层设计思路

先说明一点：Agent-Reach 不是一个大而全的平台，而是一套可嵌入的通信内核。你的 Agent 代码只要引入 Agent-Reach 的客户端 SDK，就能自动获得"注册、发现、收发消息、心跳维持"这些能力。我在最初设计时定了几条硬性原则，导致最终架构非常清爽，也方便别人二次开发。

第一条原则：控制面与数据面分离。控制面负责"谁在哪、谁还活着、谁能干什么"，数据面负责"消息怎么传、传完怎么确认"。控制面我采用了一个轻量的中心协调节点，叫 Reach Hub；数据面不经过 Hub，Agent 之间直连。这么做的好处是 Hub 不会成为流量瓶颈，哪怕一个 Hub 挂了，已经建立的会话和正在传输的消息不受影响。

第二条原则：注册信息必须包含能力描述，而不只是地址。普通微服务注册中心里通常只存 host:port 和健康检查状态，但 Agent 的注册信息里如果不带上"这个 Agent 能做什么"（比如文本摘要、代码执行、图像分析），上游根本没法做智能路由。Agent-Reach 里我用 JSON 描述一套能力标签，注册时跟着地址一起上报，查询方可以按能力筛选候选对象。

第三条原则：消息协议必须支持模型友好的载荷。Agent 之间传的不只是普通 JSON，还可能有中间推理结果、工具调用参数、长文本上下文。所以 Agent-Reach 的消息包做了一个 Payload 抽象，可以是 JSON、纯文本或二进制引用，消息头统一记录 traceId、taskId、seq 和 ack 状态，方便链路追踪。

整体分层上，我分成了四层：

• 传输层：默认走 WebSocket，支持 TLS，局域网内也可切换为 TCP 直连。
• 协议层：定义消息帧格式、心跳、握手、认证，以及消息确认（ACK）和消息拒绝（NACK）语义。
• 服务层：提供注册、发现、订阅、路由、会话管理等 API，SDK 封装成几个简单方法。
• 应用层：跟业务相关，比如"请 Worker-A 帮我执行一段代码并返回结果"，这一层其实已经超出 Agent-Reach 本身，但它给你预留了任务编排的接口。

下面这个表可以快速看明白 Agent-Reach 跟传统 RPC 框架的定位差异：

3. 服务发现与寻址：Agent 如何知道自己该找谁

服务发现是整个项目里最体现"Agent 思维"的部分，因为它跟人的社交很像。你想找一位律师朋友推荐，不会把所有联系人问一遍，而是先想"谁是做法律的"，再进一步看"谁离我近、谁最近有空"——Agent-Reach 的发现机制也是这么设计的。

3.1 注册与心跳

每个 Agent 启动后，第一步是向 Reach Hub 注册。注册报文大概长这样：

{ "action": "register", "agent_id": "worker-code-executor-01", "endpoint": { "host": "192.168.31.56", "port": 9002, "transport": "ws", "public_url": "ws://192.168.31.56:9002/agent" }, "capabilities": [ { "type": "code_execution", "language": ["python", "javascript"], "timeout_ms": 60000 }, { "type": "text_processing", "skills": ["summarize", "extract_keywords"] } ], "runtime": { "model": "qwen2.5-72b", "max_concurrency": 4, "current_load": 0.2 }, "ttl": 30 }

我把ttl设为 30 秒，意味着每个 Agent 必须每 30 秒发一次心跳，否则 Hub 就认为它下线了。这个设计是从分布式系统的心跳机制学来的，但有一个 Agent 场景独有的点：心跳里必须带上 current_load。原因很简单，Agent 的"负载"变化极快，一个 Worker 可能前一秒闲着，下一秒被一个大任务占满十分钟。上游在选路时如果只看地址，很容易把任务派给正在忙的 Agent。current_load 由 SDK 自动统计，默认是"正在执行的任务数 / max_concurrency"，你也可以在业务层自定义回调覆盖这个值的算法。

3.2 按能力标签做路由

当 Planner 要找一个"能执行 Python 代码"的 Worker 时，它不关心具体是哪个 Worker，只关心有没有谁具备这个能力。Agent-Reach 提供了两种查询方式：

• syncDiscover(capability_filter)：阻塞拿到当前所有满足条件的在线 Agent 列表。
• watchDiscover(capability_filter)：建立订阅，后续有 Agent 上线/下线/负载变化时持续收到更新。

路由逻辑是核心亮点。传统负载均衡无非轮询、随机、最少连接，但 Agent 场景里我会多考虑几个因子。比如，两个 Worker 都能执行代码，但 Worker-A 的模型是 GPT-4o，Worker-B 是本地部署的 Qwen，如果你在做成本敏感的业务，可能希望优先把简单任务派给便宜模型，复杂任务派给强模型。Agent-Reach 允许在查询条件里附加 affinity 权重，SDK 内部会计算一个综合得分：

score = 1.0 / (1 + current_load) * weight_capability + affinity_match * weight_affinity + rtt_factor * weight_rtt

权重可以配置，默认是能力匹配优先、负载其次、RTT 最后。实际用下来，这个简单的打分公式比随机轮询的效果好很多，特别是在混合部署了云端 API 模型和本地模型的场景里。

3.3 我对"健康检查"的重新定义

这是我在设计中发现的一个重要问题。在微服务里，健康检查通常是一个/healthz接口，返回 200 就行。但 Agent 的"健康"不是一个二元状态。一个 Agent 可能进程活着、网络通着，但它的模型推理线程池堵死了、或者上下文窗口几乎用完，这时它实际上是"不健康"的。Agent-Reach 里我定义了三层健康：

• L0 进程健康：能响应心跳。
• L1 链路健康：能正常建立 WebSocket 连接并完成一次应用层握手。
• L2 业务健康：能实际完成一次最小粒度的推理或工具调用。

默认只检查 L0 和 L1。L2 检查很贵，不建议频繁做，但可以在某个 Agent 连续 NACK 或者超时后，由控制面对它发起一次"探活任务"，确认是不是该把它临时摘除。这个设计帮我在后期排障时省了很多力气——某个 Worker 其实已经隐性假死，但心跳一直正常，正是 L2 探活把它揪出来的。

4. 会话管理与可靠消息投递：对话不能断，消息不能丢

解决了"找到谁"之后，下一个核心问题是"怎么对话"。Agent 之间的交互不像 HTTP 请求那样一问一答就结束，更多时候是一场持续几分钟甚至几小时的多轮协作。比如一个研究任务的流程是：Planner 把任务拆成十个子问题，逐个派给 Research Agent，Research Agent 再回传中间结果，Planner 可能要中途打断、追加信息、要求聚焦某一个方向。这就需要一个健壮的会话层。

4.1 会话的建立与上下文保持

我用一个简单的会话对象来抽象交互。发起方调用createSession()，拿到一个 sessionId 和相关密钥信息；接收方收到session_init帧后，如果不是已知能力，可以返回拒绝；如果接受，双方就进入 established 状态。后续所有消息都带 sessionId，中间任意一端重启后，可以凭 sessionId 重建会话上下文，继续未完成的任务。

这里有个很容易踩的坑：Agent 的会话跟人的聊天会话不一样，它的上下文是动态的。同样是"帮我分析这份财报"，第一轮和第二轮的语义权重完全不同。如果网络层只是简单地透传消息，不做任何状态管理，业务方就不得不自己维护上下文。Agent-Reach 的做法是把上下文句柄也放进协议头部——每次消息可以带一个context_ref，这个引用指向一段存储在 Agent 本地的记忆块。对方收到消息后，如果需要完整上下文，可以按需拉取，而不是把整段历史都塞进每个消息帧里。这个设计让长对话的开销从 O(n²) 降到接近 O(n)。

4.2 可靠投递：ACK 不是终点，业务确认才是

普通消息队列有 at-least-once、at-most-once 这些语义，但 Agent 场景下有个特殊性：消息的"处理成功"是由模型推理后的业务结果决定的。Agent-Reach 把确认分成两个阶段：

1. 传输层确认（ACK/NACK）：接收方收到了消息帧，但还没开始处理。这个确认只保证"信送到了"。
2. 业务层确认（BizACK/BizNACK）：接收方完成了一次完整的业务处理后，主动回传结果时携带的结果确认。

举个例子。Planner 给 Worker 发了一条"执行这段 Python 代码，返回运行结果"。Worker 的网络层收到消息后，立刻回一个 ACK，Planner 就知道"消息没丢"。Worker 开始执行代码，也许跑了 40 秒，期间 Planner 如果有耐心等，就收到 BizACK（附带代码执行结果）；如果代码报错，Worker 会回 BizNACK（附带错误堆栈）。Planner 拿到 BizNACK 后可以走重试、换人、或者降级策略。

超时重试策略是我反复调优的地方。Agent 的耗时波动非常大：一个简单 SQL 查询可能 2 秒返回，一个需要调用外部 API 并等待对方响应的任务可能 5 分钟都没结果。如果超时设短了，经常误判"对方没响应"而重复派单；设长了，又会让故障感知变迟钝。最终我采用自适应超时方案：SDK 记录每个 Agent 最近 N 次任务的历史耗时分布，计算 p50 和 p95，把默认超时设为 p95 的 1.5 倍。这样跑得快的 Agent 故障能被快速发现，而跑得慢的 Agent 也不容易被冤枉。

4.3 消失的 Agent 与任务迁移

分布式系统里节点随时可能崩。Agent 如果处理到一半崩溃了，任务怎么办？Agent-Reach 的做法是把"任务状态"和"Agent 实例"解耦——任务本身有独立的任务描述和任务级状态，会话只是任务执行的一个载体。

当 Planner 发现某个 Worker 失联时，它可以向 Hub 发起一个转移请求，Hub 会查找另一个具备相同能力标签的 Agent，把任务上下文同步过去。同步的内容包括：任务原始定义、已经完成的部分结果、未完成清单、还有记忆引用。这个功能对长时间运行的工作流极其重要。我的实际经验是：与其在任务执行中途做状态热迁移，不如从一开始就把任务拆成足够小的检查点。Agent-Reach 暴露了一个checkpoint()接口，Worker 每完成一个里程碑就把进度写回 Hub，这样即使中道崩殂，新接手的 Agent 也能从最近的检查点继续，而不是从头开始。

5. 实际部署中的稳定性和坑：从一次事故说起

这部分是我最想分享的。Agent-Reach 的思路虽然清晰，但真正跑起来之后，问题一个接一个。我挑几个最有代表性的。

5.1 客户端线程池耗尽事故

第一次压力测试时，我用 200 个 Worker 同时跑一个多 Agent 工作流，跑了不到 5 分钟，整个系统像被掐住脖子一样，所有消息都排队，响应时间飙升到分钟级。排查半天，发现根因在 SDK 底层的线程池配置。每个 Agent 既有"发送队列线程"，又有"接收处理线程"，还有"心跳线程"，默认配置在低负载时完全够用，但在高并发下，发送队列里的任务堵住了，导致心跳也发不出去，Hub 以为 Agent 全下线了，于是开始大量触发重连，网络风暴进一步恶化。

修复方案有两层。第一层是把心跳线程从公共线程池里剥离出来，独享一个最小线程池；第二层是给发送队列加了一个有界缓冲和主动降载策略——队列积压超过阈值时，SDK 不再无脑入队，而是直接向上层抛出一个BackpressureException，业务代码可以选择丢掉这条消息、改走离线存储，或者重试其它 Agent。这种"宁可失败也不要堆死"的思路，在 Agent 场景里比"死磕投递成功"更现实。

5.2 模型推理超时后的重试风暴

在一次运行中，某个 Agent 因为调用的外部模型 API 突然变慢（从平均 3 秒变成 30 秒），导致任务普遍超时。Planner 的策略是超时后重试，结果就是——同样一批任务，被三个不同 Worker 重复执行了三次，不仅浪费了大量 token，还产生了三个不同的结果。更糟糕的是，这些结果被后续的汇总 Agent 当作三个独立结果合并了，逻辑直接乱了。

这个事故教育我两件事。第一，重试必须幂等。Agent 任务不是天然幂等的，比如"生成一张图片"重复执行会得到不同的图；"执行一段写入型代码"更是绝不能重复跑。Agent-Reach 在协议层加入了dedup_key，每次重试都带上同一个 dedup 键，接收方在短时间内对相同 dedup 键的消息直接返回上次的 BizACK 结果，杜绝重复执行。第二，重试的退避策略要区分原因。超时重试和错误重试策略完全不同：超时可能是暂时的，用指数退避；而 NACK 往往是确定性的错误，重试没有意义，应该直接换 Agent 或降级。

5.3 NAT 和内网穿透问题：Agent 不能只有服务器能连

很多开发者用 Agent 框架时默认只在服务器上跑。但真实场景里，很多 Agent 跑在开发者的笔记本、家里的 NAS、或者办公网里的虚拟机上，这些设备通常不在公网上。如果两个 Agent 一个在公网服务器、一个在内网电脑，怎么实现点对点通信？

Agent-Reach 针对这个问题做了两层设计。第一层是"Hub 中转模式"：如果两个节点无法直连，消息会通过 Hub 中转，但数据的编解码仍是端到端的，确保也只是传输路径变长，不影响协议语义。第二层是支持 WebSocket 的被动模式：内网 Agent 主动向外连出一个 WebSocket，Hub 记录这条连接的方向，之后公网 Agent 可以通过 Hub 把消息沿这条连接推过去，绕开了 NAT 端口映射的问题。我在家里的一台 Mac mini 上跑了一个文档检索 Agent，公司服务器上的工作流就是通过这种方式调它，全程不需要在路由器上做任何端口转发。

5.4 部署过程中最常犯的五个错误

顺手列一下给别人排障时反复看到的问题，如果你准备自己部署 Agent-Reach，建议先对照检查：

• 只配置了 Hub 的 IP，没配置 Agent 对外广播的 public_url，导致跨网段的节点互相找不到对方。
• TLS 证书用了自签名，但客户端没有配置信任链，握手阶段反复失败。
• 心跳 TTL 设置过长（比如 120 秒），Agent 已经挂了但上游还在持续派单，直到网络层报错才发现。
• 忽略了 capability 标签的规范化。有人把能力写成 "Python3"，有人写成 "python-3.11"，字符串精确匹配直接让路由失效。
• 把 Agent-Reach 当消息队列用，发消息不建立会话。虽然透传消息也能工作，但会失去所有会话级能力（上下文、派生状态、重放保护），相当于把宝马当代步车开。

6. 实测数据与调优建议：这套方案到底能扛住什么

为了不让这篇文章停留在概念层面，我把自己测试环境的数据整理了一份。我的基准测试环境是：3 台 8 核 32G 的云主机，每台跑一个 Hub（一主两从）+ 若干 Worker 节点，共计 60 个 Agent 实例，全部通过 WebSocket 连接。

在纯 echo 压力测试下（Agent 收到消息后原样回传），Agent-Reach 的单 Hub 吞吐能达到每秒 3800 条消息，p99 延迟 14ms。这个数据其实不算特别亮眼，因为瓶颈主要在 WebSocket 帧的编解码上，但作为 Agent 通信底座来说是够用的——真实的 Agent 任务耗时基本都在秒级以上，通信开销在整体链路里占比很小。

更有参考价值的是带业务逻辑的测试：我模拟了一个 10 个 Worker 并行完成 100 个子任务的工作流，总耗时约 6 分 40 秒。其中通信层总用时只有 18 秒（含发现、建连、传输、确认），其余全部是模型推理和工具调用时间。这说明通信层的开销足够低，不构成 Agent 系统的瓶颈。

调优建议方面，我给出几个经过验证的参数建议：

• Hub 端连接超时设为 10 秒，写入超时设为 15 秒，读超时保持 120 秒（因为 Agent 消息间隔可能很长）。
• Agent 的心跳间隔默认 15~30 秒比较合适，太频繁会浪费资源，太慢会延迟故障感知。
• 消息大小：超过 512KB 的载荷强烈建议改为"存储 + 引用"模式，也就是把大数据块先写到共享存储（本地磁盘或者 S3），消息里只传 URL 或者对象键。WebSocket 传大消息容易导致队头阻塞。
• 启用消息压缩。默认关闭，但如果你传的是大段 JSON 日志或中间推理结果，开启后压缩率通常能到 70% 以上。

下面这张表格用来快速做容量规划参考：

7. 从 Agent-Reach 到更广的生态：构建你自己的 Agent 互联底座

Agent-Reach 现在是完全开源的，代码量不大，整个核心仓库大概 8000 多行，SDK 支持 Python、JavaScript/TypeScript 和 Go。我的建议是，如果你对它的设计思路满意，不要直接拿来就跑，先看两个文件：protocol/README.md和examples/目录下的三个示例。协议文档基本能让你在两小时内搞懂消息帧格式，三个示例对应三种最典型的用法：单工通知式、双工会话式、以及带任务编排的完整工作流。

补充一个延伸思路：Agent-Reach 的"能力标签 + 动态路由 + 会话管理"这套设计，也可以迁移到非 AI 的场景。比如 IoT 设备组网，或者边缘计算节点之间的任务调度，其实面临的都是同样的"动态发现 + 能力匹配 + 可靠通信"问题。我在内部做过一次验证：把 Agent-Reach 的 SDK 换成一个小型 C 语言实现的客户端，成功让几个单片机节点跟 PC 上的服务互相通信。原封不动的协议，基本不改。

如果你想基于它做二次开发，我推荐从这三种扩展方向入手：一是给 Hub 增加持久化存储，把注册信息和离线消息落盘，支持 Agent 重启后的快速恢复；二是引入更复杂的能力匹配，比如用向量化的能力描述做语义路由，而不只是字符串标签；三是做联邦部署——多个 Hub 之间同步注册信息，让不同组织内部署的 Agent 集群实现跨域互联。最后一个方向做起来最有趣，也最能体现 Agent 互联的真正价值。

回过头来看，Agent-Reach 解决的不只是一个技术问题，更像是给"Agent 之间应该怎么相处"定了一套社交礼仪。每个智能体进来先自报家门（注册能力），打招呼（握手），聊事情（建会话），确认收到（ACK），告别（关闭会话）。这套礼仪简单、稳定、不挑模型，也跟具体的业务解耦。

最后分享一个我自己一直保留下来的小习惯：每接入一个新的 Agent 类型，不要急着写业务逻辑，先用 Agent-Reach 的 CLI 工具跑一次 discovery 和 echo 测试。确认它能被发现、能被连接、能收发消息，再做业务上层。磨刀不误砍柴工，通信底座稳了，后面怎么折腾都不慌。