大概从去年开始，我陆续接手了几个 Agent 相关项目，做着做着发现最麻烦的已经不是单个 Agent 的提示词调优，而是怎么让它们开口说话。每家的 Agent 都有自己的上下文格式、工具调用规范和状态管理方式，项目一多，就变成了一堆烟囱式系统，A 的结论没法直接喂给 B，B 要调 C 的能力得专门写适配层。Agent-Reach 这个项目，就是为了解决这个“多智能体互不连通”的痛点而做的。
这篇文章我会从设计思路、架构拆解、技术选型到实际部署，完整讲一遍我自己做 Agent-Reach 的过程。适用于正在做多 Agent 编排、智能体平台接入、或者想把已有 LLM 应用改造成可协作形态的开发者。这里不会只贴代码，更多是讲清楚每一步选择背后的原因和一些我踩过的坑。
1. 项目背景：Agent 各自为政，协作要靠人肉接线
1.1 多智能体场景真正难在哪
单个 Agent 做对话、做 RAG、做工具调用，现在其实都有比较成熟的方案了。可是生产环境里，一个复杂任务往往需要多个 Agent 配合，比如：
- 客服场景需要意图识别 Agent、工单查询 Agent、SOP 建议 Agent 协作；
- 数据分析场景需要取数 Agent 先拿到数据，清洗 Agent 再处理，报表 Agent 最后生成可视化结论；
- 自动化运维场景需要告警分析 Agent 定位问题，变更 Agent 给出方案，执行 Agent 去操作。
把这些串起来，常见的做法有三种：一是写业务编排层，用代码一个个调用；二是在一个 Agent 内部塞很多工具让它自己去调；三是用 LangChain、CrewAI 这类框架搞定流程编排。但它们都有一个共同的问题：Agent 之间没有标准化的通信方式，一旦 Agent 数量多起来，彼此之间是“接口耦合”而不是“消息耦合”，每次新增一个角色都要改代码。
我当时做 Agent-Reach 的出发点，就是想把“两个 Agent 之间的协作”抽象成一种标准化的消息传递，而不是堆 API 调用。这套东西本质上是一个轻量级的多智能体通信与编排层，它不关心你的 Agent 是用什么框架写的、跑在哪台机器上、内部是什么技术栈，只要遵循一套协议就能接入网络，被其他 Agent 发现和调用。
1.2 Agent-Reach 能解决什么问题
用一句话概括：Agent-Reach 是“多智能体之间的 TCP/IP”。它提供了一套去中心化的 Agent 注册、发现、消息路由和任务分发机制，让不同来源的 Agent 可以互相发现、交换消息、协同完成复杂任务。
这套方案比较适合以下几类人：
- 手头有多个独立 Agent 服务，希望在不重写它们的情况下实现协作；
- 准备做企业内部智能体平台，需要一个通用的接入标准；
- 研究多智能体协作机制，想找一个轻量、可控、能跑通全链路的参考实现；
- 做 LLM 应用基础设施，希望把 Agent 的互联方式做得像微服务一样标准化。
我不会把它说得天花乱坠。Agent-Reach 解决的只是“连接”问题，它不会替你写好业务 Agent 的逻辑。但一旦连接层打通了，后面做编排、做任务分解、做并行协作，就都变成顺理成章的事。
2. 整体架构设计：一条消息如何找到另一个 Agent
2.1 核心设计理念：Agent 之间只认“消息”，不认“接口”
做架构设计的时候，我给自己定了一条铁律：Agent 之间不能硬调接口，只能发消息。
为什么？因为如果 A 要调 B 的 HTTP 接口，那么 A 就必须知道 B 的请求格式、鉴权方式、错误处理逻辑，这跟微服务之间的接口耦合没有本质区别。而如果 A 只是往“某个负责天气查询的 Agent”投递一条消息，它对 B 的内部实现一无所知，两者之间唯一的共识就是消息格式，解耦程度就完全不一样。
所以 Agent-Reach 的核心抽象是Message Envelope（消息信封）。所有 Agent 之间的通信，不管底层走的是 WebSocket、HTTP 还是内部进程调用，对外只表现为一次消息的发送与接收。信封里带着发送者标识、接收目标、消息类型、上下文引用、任务票据等元信息，而消息体本身则是一个与具体业务无关的载荷——可以是一段文本、一个 JSON 结构、一个文件引用，甚至是一段可执行脚本的 URL。接收方只需要处理消息内容，不需要关心消息从哪来，更不需要关心路由和重试，这些全部由框架接管。
2.2 三个核心模块拆分
Agent-Reach 的架构，说开了就三个模块：ReachHub（接入节点）、Agent Registry（注册中心）、Task Router（任务路由器）。
ReachHub 是每个 Agent 运行时上挂的一个接入点，它负责维持与对端的网络连接、处理消息的收发、校验签名和权限。每个 Agent 进程内部集成一个 AgentReach Client SDK，SDK 负责把 Agent 的能力声明注册到 ReachHub 上，并监听来自其他 Agent 的请求。这里的关键设计是：Agent 客户端是主动连出，不监听端口。这样 Agent 无论部署在哪个网络环境，只要能访问 ReachHub 就能参与协作，而不用给每个 Agent 都开公网入口，生产环境的安全策略上会好做很多。
Agent Registry 负责服务发现和元数据管理。她保存的不是 IP 地址这种物理信息，而是 Agent 的“数字孪生”：能力描述、输入输出 Schema、当前状态、负载情况。我用了 etcd 来存这部分数据，利用它的 watch 机制实现近乎实时的上下线感知。
Task Router 是消息层面的决策节点。当一条消息要找“N 个能处理文本分类的 Agent”时，Task Router 会结合注册中心里的能力标签做匹配，并按照负载和可用性打分，把消息推给合适的 Agent。这个路由规则不是写死的，而是走一段可配置的策略脚本，所以业务方可以很方便地定制自己的调度策略。
2.3 一次跨 Agent 请求的完整链路
我用一个具体的例子来串一遍整个链路：A 是意图识别 Agent，B 是订单查询 Agent。
- A 需要查订单状态，但它不认识 B，它只知道平台上有“订单域”的能力；
- A 用 SDK 构造一条 SendMessage 请求，目标字段填的是
capability:order.query，而不是agent:B； - SDK 先把消息投递给 A 所在机器上的 ReachHub，ReachHub 查询本地的路由缓存；
- 路由缓存没命中或者本地负载过高，ReachHub 把请求转发给全局的 Task Router；
- Task Router 在 Agent Registry 里找到所有声明了
order.query能力的 Agent，根据负载、响应速度、匹配度打分，选中 B； - 消息被投递到 B 的 ReachHub，B 的 SDK 回调业务代码，业务代码处理完成后把结果原路返回；
- A 收到的是一次完整的异步响应，整个过程对业务层透明。
这个链路看起来步骤多，但实际延迟瓶颈只在 Task Router 匹配和消息序列化那一段，我在后续的性能部分会给出实测数据。整体设计借鉴了微服务里服务网格的思路，只不过把服务换成了 Agent，把 RPC 调用换成了消息投递。
3. 技术选型：为什么选这套组合而不选别的
3.1 通信层：WebSocket + MessagePack，而不是 HTTP + JSON
Agent 和 ReachHub 之间的通信，我最终选了 WebSocket 作为长连接通道，序列化用 MessagePack。
最初我也纠结过要不要直接用 HTTP。HTTP 的优势是简单，生态丰富，调试工具一堆。但它有个致命短板：如果有任务需要长时间执行，比如一个数据分析 Agent 要跑几分钟，HTTP 请求要么一直占着连接，要么得设计轮询或回调，都会让链路变得非常绕。Agent 协作场景天然是双向异步的，A 发完消息不一定要立刻拿到结果，B 可能在排队处理，处理完了主动推给 A 更自然。WebSocket 长连接正好契合这个模式，一条连接上可以同时跑几百个未完成请求，互不阻塞。
序列化选 MessagePack 是为了省带宽和降低延迟。我实测过，同样一段 Agent 上下文消息，JSON 序列化后大约 11KB，MessagePack 只要 7KB 左右；序列化耗时更是肉眼可见的差距，JSON 大约 1.6ms，MessagePack 大约是 0.2ms。在高频消息场景里，这个差距会直接影响整体吞吐。
3.2 注册中心：etcd，看中 watch 机制和租约
注册中心我没有用 Redis，也没有用 ZooKeeper，最后定了 etcd。
原因有三：第一，etcd 的 watch 机制可以让我在 ReachHub 本地维护一份接近实时的 Agent 路由表，而不是每次消息都穿透到注册中心查一次；第二，etcd 的租约机制天然适合做 Agent 存活性判断，Agent 每 5 秒续租一次，租约超时自动清除，上下线的感知是全自动的；第三，etcd 支持事务，我可以确保 Agent 注册过程的原子性，避免两个同质 Agent 重复抢占同一个能力标识时产生脏数据。
数据库存储则用了 PostgreSQL，存的是任务票据、消息轨迹和审计日志。为什么不用 MongoDB？因为这里的数据结构偏关系型，而且需要复杂查询——比如按 Agent ID 聚合统计消息量、按时间段切片查成功率，这类需求用 SQL 表达比文档数据库要自然得多。
3.3 SDK 语言支持策略
Agent-Reach 的 SDK 目前提供了 Python 和 Go 两个版本。选择这两个语言的原因很朴素：Python 是当前 LLM 应用和 Agent 框架的主流语言，覆盖了绝大多数 AI 开发者；Go 则适合写连接层和高性能服务，比如想直接把 Agent 做成高并发网关的场景。
SDK 的设计目标是让接入成本尽可能低。Python SDK 里，接入一个 Agent 大概只需要：
from agentreach import AgentRuntime, capability @capability("order.query", version="1.0") async def query_order(payload: dict) -> dict: order_id = payload["order_id"] ... return {"status": "shipped", "tracking_no": "SF123456"} runtime = AgentRuntime(agent_id="agent-order-01") runtime.register_handler(query_order) runtime.connect("reachhub://localhost:7800", token="...") runtime.start()这样一段代码，你的业务函数就变成了一个可以被网络上其他 Agent 调用的能力。SDK 内部处理了注册、心跳、消息接收、超时重试，对业务代码的侵入极小。
4. 部署与接入实操：把三个 Agent 串起来
4.1 启动 ReachHub 节点
我们假设一个最简单的生产部署形态：ReachHub 以多副本方式部署在机器上，前面挂一个负载均衡器，Agent 通过域名接入。
ReachHub 的配置我写成了一份 YAML 文件：
server: listen: 0.0.0.0:7800 mode: relay max_msg_size_mb: 16 registry: endpoints: ["etcd://10.0.0.11:2379", "etcd://10.0.0.12:2379"] lease_ttl_seconds: 15 sync_interval_seconds: 3 transport: websocket: ping_interval_seconds: 20 ping_timeout_seconds: 10 auth: jwt_secret_env: AGENTREACH_JWT_SECRET require_tls: false启动命令：
./reachhub --config config.yaml启动之后，ReachHub 会先连接 etcd，把自己的节点信息注册进去，然后开始监听 WebSocket 接入。注意这里的max_msg_size_mb，因为我曾经遇到过消息体过大把内存打满的问题，默认 16MB 是一个比较平衡的值，既满足大多数 Agent 的场景，又不至于让资源开销失控。
4.2 注册第一个 Agent 并验证上下线
我写了一个很简单的示例 Agent，功能是“环境配置助手”，它会接收用户传入的需求描述，返回一组推荐的环境参数。注册指令长这样：
agentreach register \ --name env-config-agent \ --endpoint localhost:7800 \ --token "$AGENT_TOKEN" \ --capability "env.detect"注册完以，可以用自带的 CLI 查看状态：
agentreach list-agents --hub localhost:7800正常情况下，Registry 里会看到env-config-agent，状态显示online，并带有一个能力标签env.detect。这时候我从另一个 Agent 发一条探测消息：
agentreach probe --capability env.detect --payload '{"os": "linux", "cpu": 8}'如果链路正常，几秒内会收到返回，内容就是这个 Agent 给出的环境配置建议。此时再手动杀掉 Agent 进程，等一个心跳周期，重新执行list-agents，会发现状态已经变成offline，这个上下线的自动感知就是靠 etcd 租约实现的。
4.3 把一个真实 Agent 的流程跑通
上面只是简单的探测，真正跑通跨 Agent 协作，需要多节点配合。我搭了一个三 Agent 环境做测试：
| Agent ID | 能力 | 职责 |
|---|---|---|
agent-analyzer | text.sentiment | 做情感分类，返回正/中/负 |
agent-intent | intent.detect | 识别用户意图 |
agent-responder | reply.generate | 根据分类和意图生成回复文本 |
测试请求是一条用户消息“我要投诉物流太慢了，顺便帮我取消订单”。流程如下：
agent-intent收到原始消息，识别出意图是complaint+cancel_order两个意图；- intent Agent 生成一个任务票据，把后续处理请求路由给
agent-analyzer和agent-responder； agent-analyzer先做情感分类，判定为负面情绪，输出结果；agent-responder拿到 intent 和 sentiment 的结果，生成回复模板“抱歉给您带来不便，已记录投诉并同步订单取消流程”；- 最终回复写回起点 Agent，整个链路结束。
这个流程里，所有 Agent 之间没有一次直接 HTTP 调用，全部走消息。我在日志里看到的调用链是这样的：
msg-1001 env.detect -> agent-intent msg-1002 agent-intent -> agent-analyzer [ref: msg-1001] msg-1003 agent-intent -> agent-responder [ref: msg-1001, msg-1002] msg-1004 agent-responder -> agent-intent [ref: msg-1001..1003]每条消息都带着ref字段，把因果链完整串联起来。出问题的时候排查会非常方便，直接按消息链重放整条链路即可。
4.4 实际生产环境部署要点
如果要把这套东西放到生产，有几个我自己踩过的坑必须列出来：
要保证至少两个 ReachHub 节点。如果只部署一个，Agent 客户端连入数量超过几百个以后，WebSocket 单节点连接数会开始逼近瓶颈，而且重启节点期间全员掉线。部署两个节点并做好负载均衡之后，Agent 通过域名解析到任意一个，节点故障时另一台的注册表会接管路由。协议这边是有节点间同步机制的，具体做法是一个节点收到 Agent 注册消息后，会同步给 etdc 集群里的其他节点。
ReachHub 节点之间不建议跨公网直连，如果两个机房各部署一组，最好走内部专线。因为消息的路由信息里带的是内网地址，跨公网会丢包导致心跳误判。
Agent 的 JWT token 要定期轮换。我用AGENTREACH_JWT_SECRET环境变量注入，每季度生成一批 token 并预下发到各个 Agent 配置中心，新 token 生效前旧的仍然保留一星期，避免全部 Agent 同时离线。
5. 稳定性设计与性能调优
5.1 消息不丢的保底手段：任务票据与重放
做分布式系统都知道一个定律：网络不可靠，超时会重试。Agent 协作同样是这样。Agent 之间的一条消息可能因为网络波动、节点重启、进程 OOM 而丢失，如果业务上不能接受丢失，就必须有可靠的保底机制。
Agent-Reach 的做法是给每一条需要可靠投递的消息生成一个Task Ticket（任务票据）。票据里包含一个全局唯一的 message_id，以及消息的完整载荷、超时时间、重试次数上限。Task Ticket 会先写入 PostgreSQL，状态是pending；消息成功投递到目标 Agent 且收到 ACK 之后，状态更新为delivered；业务处理完成，状态更新为completed。
如果投递超时，或者 Agent 返回错误，重试调度器会从数据库里把这个 Ticket 捞出来重新推送。重试策略我用了指数退避 + 少量抖动：
第 1 次重试：1 秒 第 2 次重试：2 秒 第 3 次重试：4 秒 第 4 次重试：8 秒 最多重试 5 次这个节奏是我根据自己的生产场景定的，如果目标是局域网内高频消息，可以把间隔缩短；如果是跨机房异步日志，间隔可以拉长。关键是重试要带 jitter，即每次重试的实际间隔加一个 0～200ms 的随机抖动，避免多个 Agent 同时重试导致消息风暴。
5.2 幂等处理：每个 Agent 都要做到的底线
既然有重试，就会有重复消息。如果订单查询接口被重复调用，可能没太大问题；但如果是一条“取消订单”的指令被重复执行两次，就会出现用户订单被取消两次的尴尬场景。因此在 SDK 里我默认开启幂等机制：
对每条收到的消息，SDK 会根据 message_id 做去重。去重表就是 Agent 进程内的一个 LRU 缓存，默认容量 1024 条。如果消息 ID 已经在缓存里，SDK 会直接返回第一次处理时的缓存结果，不再触发业务代码。同时，如果重试消息在进程重启后到来，缓存已经丢失，但持久层有处理记录，所以业务方最好在重要操作里再做一层业务幂等，比如用订单号加状态机判断。框架的幂等是辅助，业务的幂等才是底线。
5.3 实测性能数据
我搭了一个 3 台 8C16G 节点的测试环境：一台跑 ReachHub，一台跑 50 个模拟 Agent 客户端，一台跑压测程序。压测的场景是：随机一个 Agent 向另一个 Agent 发一条 1KB 大小的消息并等待回复。结果如下：
| 指标 | 数值 |
|---|---|
| 平均单条消息端到端时延 | 38ms |
| P99 时延 | 74ms |
| 稳态吞吐 | 1200 msg/s |
| 峰值吞吐 | 2100 msg/s |
| 消息丢失率（默认重试机制下） | 0% |
这个数据对于 Agent 协作场景来说是完全够用的，毕竟 Agent 单次处理的耗时通常是几百毫秒甚至几秒，消息传输的 38ms 可以忽略不计。如果以后吞吐要求更高，可以考虑在 SDK 里开启消息压缩，或者把消息分片，但现阶段没必要提前优化。
6. 常见问题与排查技巧实录
写这一节是因为在开发和内部试用过程中，我自己确实踩了不少坑，有些问题在文档里根本翻不到，只能通过日志和抓包一点点定位。整理成表，方便后来者速查：
| 现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
| Agent 注册后状态一直是 offline | 心跳超时或 token 失效 | 看 ReachHub 日志，找heartbeat timeout | 检查 token 有效期，重启 Agent；检查本地时钟是否偏差过大 |
| 消息投递超时但目标 Agent 还在线 | 路由表缓存过期，目标真实地址变化 | 查看注册表的 watch 日志，看是否收到更新事件 | 调大 ReachHub 的同步间隔；确认 etcd watch 连接没有断开 |
| 高并发下时延毛刺明显 | WebSocket 消息未分片，大消息阻塞小消息 | 抓 pcap 看是否有大帧阻塞 | 开启分片发送，限制单条消息最大体积不超过 1MB |
| 两个 Agent 重复处理同一条消息 | 重试造成重复投递，幂等缓存未命中 | 用 message_id 在日志里检索处理次数 | 开启 SDK 幂等；业务层做幂等键检查 |
| 任务票据数据库增长过快 | 过期票据没有清理 | 查ticket_cleanup定时任务 | 配置清理策略，每 24 小时删除 7 天前completed票据 |
| 某 Agent 经常失联但进程还在 | 长连接被防火墙掐断，未开启 WebSocket ping | 看网络层连接状态，检查 idle timeout | 开启 WebSocket 心跳，ReachHub 侧设置 ping_interval 为 20 秒 |
| SDK 接入后注册很慢 | 注册逻辑里做了同步网络调用 | 看代码里是否有同步阻塞 | 把注册逻辑放到后台任务，避免阻塞主流程 |
| 跨网段部署时消息丢失 | 防火墙/安全组拦截了高端口回包 | 用tcpping测试目标端口 | 调整安全组放行 WebSocket 回包端口 |
再分享一个我印象很深刻的坑。第一次做消息链跟踪时，我把所有日志都打印到了一个文件，结果排查问题时发现不同 Agent 的日志时间戳对不上。查了一圈才发现是各节点服务器的时钟没同步，偏差已经到了秒级。后来在部署脚本里加了一段强制chrony同步逻辑，并在 Agent-Reach 的日志里把所有事件时间统一成 UTC 存，展示时才转换成本地时间。从此再排查消息链问题，只要看同一 message_id 的时间序列就够了，不用再跟时钟偏差打架。
还有权限校验的设计也是改过一版的。最初版本只校验了 Agent 的 token，结果内部试用时发现，某个 Agent 可以任意调用其他 Agent 的能力，如果其中一个 Agent 被攻破，整个协作网络就裸奔了。后来我改成了细粒度授权：token 里带上 Agent 的角色标签，ReachHub 在路由时校验调用方是否具备目标能力的使用权限。比如agent-intent只有intent.detect的调用权限，它就不能去调payment.execute。这个改造虽然增加了一些配置成本，但安全上确实踏实很多。如果之后要做跨团队接入，我建议这一步不要省。
7. 个人经验与后续打算
做 Agent-Reach 这段时间，我最大的体会是：多智能体系统的瓶颈往往不是模型能力，而是组织方式。模型再强，如果 Agent 之间像孤岛一样各说各话，组合起来的价值就远远小于单体 Agent 的能力总和。反过来，只要你把通信和协作这一层做好了，哪怕底下是能力很一般的模型，大家各司其职，整体的表现都会超出预期，就像一支配合默契的团队，每个人不一定要是顶尖高手，但协作效率能打出意外效果。
后续我计划在这个基础上做两件事。一件是给 Agent-Reach 增加一个可视化编排界面，让非技术背景的业务同学也能用拖拽的方式定义多 Agent 流程，而不只是靠写代码。另一件是做一个更智能的路由策略，不只是基于能力标签和负载做匹配，而是根据历史调用成功率、响应速度、语义匹配度综合打分，让 Task Router 真正学会“把活派给最合适的人”。目前这个项目还在持续迭代中，如果有同学也在做多智能体通信，非常欢迎一起交流。
