先交代一个背景。我手上有几个业务系统，去年开始做多Agent协作实验，最早是拿LLM API硬拼，几个Agent各写各的prompt，各调各的接口，跑通demo很容易，但一上量就崩。后来咬着牙把通信层抽出来重做，这个项目就是Agent-Reach——一套面向多Agent场景的轻量级触达与路由组件。简单说，它解决的是Agent之间怎么互相发现、怎么把任务可靠送出去、怎么触达外部工具和数据源这三件事。如果你正在搭多Agent系统、写Agent工作流，或者只是想把一堆自动化脚本变成能互相调度的"Agent集群"，这篇复盘应该对你有用。
我不会按时间线流水账讲，而是把Agent-Reach从设计思路到核心实现、再到上线后踩的坑，拆成几个相对独立的部分。那些代码细节、协议字段、压测数据，都是我在真实环境里跑过、改过的版本，你可以直接参考，不用再绕我走过的弯路。
1. 做Agent-Reach之前，我到底被什么问题逼疯了
1.1 三个Agent各说各话的现场
先说一个具体场景，你就能理解Agent-Reach解决的是什么。当时我手上有三个Agent：一个负责读订单邮件并提取结构化数据，一个负责查库存和生成补货建议，一个负责把建议发送到企业微信通知群。单看每个Agent，能力都不复杂，麻烦在于它们之间要协作。订单Agent处理完邮件之后，需要通知库存Agent"这批SKU缺货了，你去查一下有几个渠道在售"，库存Agent查完之后又要告诉通知Agent"这是今天的补货清单，请你推送给仓库负责人"。
一开始我把这种协作写成了硬编码：订单Agent的代码里直接调库存Agent的HTTP接口，库存Agent的代码里直接调通知Agent的Webhook。三个Agent还能转起来，问题是每次加一个新Agent，或者某个Agent改了接口参数，另外几个Agent的代码就要跟着改。到了第八个Agent的时候，整个调用链已经变成一团乱麻，一个小改动要牵连四五个文件。我意识到，这不是Agent能力的问题，是缺一个能让它们"互相找到对方、用统一方式说话"的中间层。
1.2 现成方案的别扭之处
当时我评估过几条现成路线，都有点别扭。
一条路线是直接用事件总线，比如Redis Pub/Sub或者Kafka。这个方案的问题在于事件总线本质上是"广播"，每个Agent都要订阅一堆主题，消息一旦多了，消费者那边要自己做大量过滤和路由判断，本质上又把路由逻辑塞回到了各个Agent身上。
另一条路线是用工作流编排框架。但工作流框架适合"流程确定"的场景，比如先做A再做B再做C，而Agent协作往往是动态的，订单Agent并不知道应该找哪个Agent处理库存，它只知道"我需要一个能查库存的能力"。这是能力路由，不是流程编排。
还有人建议把所有人的上下文都塞到同一个大prompt里，让大模型自己决定谁干什么。这个在小规模时很爽，Agent数量一多，上下文窗口根本扛不住，而且大模型偶尔会跳过某个Agent，直接凭记忆瞎编结果。这种"灵性"在闲聊时是好玩的，在订单处理这种场景里就是事故。
1.3 Agent-Reach的边界：只做"触达"
所以我在设计Agent-Reach时给自己画了一条很清楚的边界：它不做模型调度，不做Agent的思考逻辑，只做触达。英文里Reach这个词有"伸手够到"的意思，我要的就是这个感觉——让一个Agent能可靠地够到另一个Agent，够到自己需要的工具，够到外部数据源。
具体来说，Agent-Reach承担三件职责：
- 注册与发现：每个Agent上线时向注册中心登记自己的能力和调用地址，其他Agent不需要预先知道对方的存在。
- 路由与派发：根据任务描述里的能力标签，把消息派发给匹配的Agent，支持点对点和一对多扇出。
- 触达适配：把外部HTTP API、数据库、文件系统等资源封装成Agent能调用的统一工具形态。
至于Agent内部怎么推理、怎么用prompt组织回复，Agent-Reach完全不关心。这个边界很重要，它保证了Agent-Reach本身可以保持很轻，接入新Agent的成本也低——你不需要改通信层，只需要让Agent实现一套统一的对外接口就行。
2. Agent-Reach核心架构：一次调用是怎么走完全程的
2.1 三个核心组件：注册中心、路由网关、触达适配器
Agent-Reach由三个核心组件组成，我会分开描述它们的职责。
注册中心（registry）负责维护Agent的元信息。每个Agent启动时，会向注册中心发送一条注册消息，内容包括Agent名字、能力标签、调用地址、版本号、权重信息。注册中心会定期检查Agent的心跳，超过阈值没心跳的Agent会被标记为离线。什么叫能力标签？简单来说就是一个Agent能处理什么类型任务的描述，比如"inventory.query""order.extract""notify.push"，路由的时候就是靠这些标签找到目标的。
路由网关（router）是真正处理消息转发的部分。它接收上游Agent发来的任务消息，解析消息里声明的目标能力或目标Agent，去注册中心查匹配的实例，然后按负载均衡策略派发，同时记录一条完整的路由日志。如果目标Agent不可达，网关会尝试重试，重试仍失败就把消息丢进死信队列。
触达适配器（adapter）是Agent-Reach的独特之处。Agent本身不直接面对各种外部系统的SDK，而是把外部资源声明成工具，由适配器统一执行调用、统一返回格式。这样Agent的代码里就不用写curl，不用考虑各种接口的鉴权差异，只要说"调用工具inventory_api查一下SKU-1024的库存"，适配器会处理剩下的事情。
2.2 消息体：从TaskDispatch到TaskAck
Agent-Reach的通信协议是JSON，消息类型分四类：Register（注册）、Dispatch（任务派发）、Ack（确认回执）、Result（结果回传）。其中Dispatch是最核心的消息。下面是我实际在用的一个简化版本：
{ "schema_version": "1.2", "message_id": "d2js9fk2-8d21-4f0a-b7a2-35bc9d1a0f17", "type": "task.dispatch", "timestamp": 1730347605231, "source_agent": "order_agent", "target_capability": "inventory.query", "target_agent": null, "payload": { "task_id": "task_20241101_003", "input_data": { "skus": ["SKU-1024", "SKU-2024"], "channels": ["self_operated", "third_party"] }, "callback": { "mode": "return", "return_to": "order_agent" } }, "routing": { "max_hops": 3, "timeout_ms": 10000 } }几个字段的作用我解释一下。message_id是全局唯一的消息编号，用来做幂等和追踪；target_capability是这次任务想要的能力，比如"inventory.query"；target_agent如果填了就是指定Agent，不填则由路由网关根据能力匹配；routing.max_hops限制了消息最多经过几个Agent，这是后面防止Agent互相死循环的关键参数；callback.return_to标明结果要送回给谁。
Ack消息则比较简单，接收方Agent收到Dispatch后立即回一条Ack，表示"任务我收下了"，这样发送方就不用傻傻等一个没有回音的请求。真正的结果数据通过Result消息异步返回。
2.3 一次完整的消息旅程
把上面这些拼起来，一次调用的完整链路是这样的：订单Agent构造Dispatch消息，指定target_capability为"inventory.query"，发到路由网关。网关去注册中心查找所有声明了"inventory.query"能力的Agent，可能查到三个实例，按权重和当前负载选一个，转发过去。库存Agent收到消息，先回Ack给网关，网关把Ack转回给订单Agent，订单Agent就知道"消息对方收到了"。库存Agent处理完之后，构造Result消息，通过网关回传给订单Agent。整条链路里，消息每经过一跳，网关都会追加一段路由日志，包含时间戳、节点名、耗时，方便之后排查问题。
2.4 为什么用JSON而不是更"高效"的二进制协议
这是开发时一个朋友问我的问题，他建议用Protobuf或者MessagePack，说性能更好。我当时是这么考虑的：Agent-Reach面对的Agent生态里，有大模型API、有Python脚本、有Node服务，甚至还有同事用Excel里的VBA在调接口，JSON是包容性最强的格式，任何语言都能零成本解析。至于性能，在一次任务派发里，真正耗时的是大模型推理和外部API调用，消息序列化的开销连5%都不到，为了这点性能牺牲跨语言兼容性，不值。如果你确实遇到极端高通量场景，再在内部节点之间做二进制压缩层也不迟，但入口出口保持JSON，对生态最友好。
3. 关键实现细节：协议、状态机与工具触达
3.1 让每个Agent学会"自我介绍"
Agent-Reach接Agent的第一步，是让Agent实现一个描述接口。无论你用什么语言写的Agent，只要能在启动时吐出一份AgentInfo，就能被Agent-Reach纳管。我的AgentInfo长这样：
{ "agent_id": "inventory_agent", "display_name": "库存查询Agent", "version": "0.3.1", "capabilities": [ { "name": "inventory.query", "description": "查询商品SKU在多个渠道的库存状态", "input_schema": { "type": "object", "properties": { "skus": {"type": "array", "items": {"type": "string"}}, "channels": {"type": "array", "items": {"type": "string"}} }, "required": ["skus"] } } ], "endpoint": "http://inventory-svc:8000/agent/invoke", "auth_token_ref": "token:inventory", "load_weight": 3, "heartbeat_interval_s": 30 }capabilities里每一项的input_schema其实就是JSON Schema格式，路由网关不会解析你的业务语义，但会根据这个schema对入站消息做基础校验，避免一个不完整的payload被丢到一个Agent上才报错。auth_token_ref指向密钥存储里的某个key，Agent和Agent之间调用时，网关会自动附加鉴权信息，这个机制省去了在每个Agent里硬编码token的麻烦。
3.2 任务状态机：别让消息悬在半空
消息派发出去之后，如果接收方Agent直接崩溃了，或者网络闪断，这条任务该怎么办？Agent-Reach为任务定义了一个简单但严格的状态机。整个生命周期是：PENDING -> ROUTED -> ACCEPTED -> RUNNING -> COMPLETED / FAILED，另有一条特殊路径：PENDING -> ROUTED -> RETRY -> DEAD_LETTER。
PENDING状态表示消息刚被提交；网关路由成功进入ROUTED；接收方回Ack进入ACCEPTED；开始处理是RUNNING；处理完回传Result是COMPLETED。如果说好超时时间内一直没收到Ack，网关会把消息标记为RETRY并重新选择目标Agent，最多重试3次。3次都不行，消息进入DEAD_LETTER队列，等人工介入。
这个状态机看起来简单，但它帮我拦住了一个大坑：以前没有状态机时，消息发出去了就没人管，失败了也不知道，经常出现"订单Agent以为自己查过库存了，其实库存Agent根本没收到"的情况。有了明确状态和解耦的Ack机制，每个任务在任意时刻处于什么状态，都能拿出来给业务方面对。
3.3 触达适配层：把外部API变成Agent手里的工具
Agent要调用外部系统，最原始的做法是Agent的代码里直接请求外部API。但这样有一个问题：外部API的参数格式五花八门，响应格式也是各家的习惯，Agent的代码里会堆满各种字段映射和容错逻辑。
Agent-Reach的触达适配器把这种情况收敛成统一的工具调用模式。我在代码里定义一个工具元数据，比如：
tools = [ { "name": "inventory_api", "type": "http", "url_template": "https://{host}/api/v2/inventory/batch", "method": "POST", "auth": "header:Authorization", "request_mapping": { "skus": "product_codes", "channels": "warehouse_ids" }, "response_mapping": { "items": "$.data.list", "total_stock": "$.data.total" }, "timeout_ms": 5000, "retry": "on_5xx" }, { "name": "notification_webhook", "type": "webhook", "url": "https://notify.internal/webhook/agent", "method": "POST", "request_mapping": {}, "response_mapping": {}, "timeout_ms": 3000, "retry": "on_network_error" } ]执行时，Agent会发起一个工具调用请求："inventory_api(skus=['SKU-1024'], channels=['self_operated'])"，适配器负责把参数映射成外部API需要的product_codes和warehouse_ids，发起HTTP请求，再把响应里的深层字段映射回统一的结果格式。适配器还负责超时控制、重试策略、以及调用失败时的标准化错误信息。这样Agent的业务逻辑里不会出现任何外部系统特有的字段，切换外部服务商时只需要改适配器配置，Agent代码一行都不用动。
这里要特别强调一点：任何"Agent能触达外部URL"的设计，都必须把安全边界做严。我的适配器里维护了一份内网域名白名单，Agent只能调用白名单里的服务，外部公网URL默认禁止。否则一旦Agent被prompt注入，攻击者就可能借Agent之手探测内网。这个意识一定要有。
3.4 路由网关的实现骨架
路由网关是Agent-Reach里我最常改动的地方，核心逻辑其实不复杂，我用FastAPI实现了约两百行核心代码。核心路由函数大约是这样的逻辑：接收Dispatch消息，检查版本号，查注册缓存，选择目标，转发，记录日志，返回Ack。
async def dispatch_task(message: DispatchMessage): if message.schema_version < MIN_SCHEMA_VERSION: raise SchemaTooOld(f"need schema >= {MIN_SCHEMA_VERSION}") candidates = registry.lookup( capability=message.target_capability, agent_id=message.target_agent ) if not candidates: dead_letter.put(message) return DispatchResult(status="NO_AGENT", message_id=message.message_id) target = select_target(candidates, strategy="weighted_least_conn") ack = await send_to_agent(target, message, timeout=message.routing.timeout_ms) if ack is None: retry_queue.put((target, message, 3)) return DispatchResult(status="RETRY_SCHEDULED", message_id=message.message_id) trace_log.record(message.message_id, target.agent_id, latency_ms=ack.latency_ms) return DispatchResult(status="ACCEPTED", message_id=message.message_id)实际生产里我还加了内存缓存，避免每次路由都去注册中心查一次，注册信息变更通过订阅推送实时更新。路由日志是全链路追踪的基础，每条消息经过网关都会记录一条结构化日志，包含消息ID、源Agent、目标Agent、耗时、状态码。排障的时候，按message_id一查，整条调用链一目了然。
4. 部署方式与一个小规模压测实验
4.1 手动部署一套最小的Agent-Reach
Agent-Reach我打成了三个Docker镜像：registry、router、adapter。本地调试可以用Docker Compose一键拉起一个最小环境。下面是一个裁剪过的编排配置：
services: registry: image: agentreach/registry:1.2.0 ports: - "8500:8500" environment: REGISTRY_HEARTBEAT_TIMEOUT_S: 90 REGISTRY_STORAGE_DRIVER: "memory" router: image: agentreach/router:1.2.0 ports: - "8600:8600" environment: ROUTER_REGISTRY_ADDR: "registry:8500" ROUTER_DEAD_LETTER_DRIVER: "file" ROUTER_DEAD_LETTER_DIR: "/var/lib/agentreach/dlq" adapter: image: agentreach/adapter:1.2.0 ports: - "8700:8700" volumes: - "./tools.yml:/etc/agentreach/tools.yml:ro"启动之后，你只需要让自己的Agent程序向registry:8500的注册接口发一个Register消息，然后通过router:8600派发任务就行了。整体来说，Agent-Reach不强制依赖数据库，默认状态下注册信息存内存、死信落本地文件，适合中小规模Agent集群。如果你要支撑几十个Agent以上的规模，再把它底层的存储换成Redis或Postgres，接口不需要变。
4.2 压测中的数据表现
我在测试环境跑了一轮压力测试：8个模拟Agent，分别注册了不同的能力标签，每个Agent的响应时间设定在50毫秒左右，消息生成速率从100条/秒逐步提高到2000条/秒，连续压测10分钟。结果如下：
- 平均路由耗时约3毫秒，P95约8毫秒，P99约25毫秒（这个耗时是纯网关转发，不含Agent处理）。
- 到2000条/秒时，消息积压开始出现，网关进程CPU约45%，内存稳定在180MB左右。
- 模拟了1%的Agent随机崩溃，消息落死信队列的比例约0.8%，重试成功挽回约0.6%，最终真正丢失的只有剩余0.2%左右，且全部有日志可查。
这个表现对我来说足够了。原因也很简单：Agent场景的瓶颈本来就不在消息路由本身，而在Agent内部的大模型推理和外部API响应。路由器保持极致的轻量，反而不会成为瓶颈。
4.3 我建议的最小部署范式
如果你的Agent集群还不到十个，其实不需要把三个组件拆开部署，一个单进程版Agent-Reach就够了。只有当Agent实例变多、需要独立扩展网关吞吐时，再拆成独立服务。拆的时候要记住一个原则：路由网关必须是无状态的，所有状态放注册中心或缓存里，这样才能随便水平扩容。
5. 实战中踩出来的坑，比代码更难啃
5.1 坑一：Agent之间真的会"说个没完"
我最早在Agent-Reach里没有设置跳数限制时，出现过一次事故。一个审计Agent要找财务Agent拉数据，财务Agent发现数据格式不对，把请求转给归一化Agent，归一化Agent发现自己没权限，又把请求转回审计Agent，审计Agent觉得"这不是我该干的"，又转给财务Agent……三个Agent互相踢皮球，消息在系统里转了几十圈，把消息队列堵了。
后来我做了两道保险。第一道是routing.max_hops字段，消息每经过一个Agent，网关就把跳数减一，减到零直接进死信队列并告警。第二道是循环指纹检测：网关会计算消息关键载荷的哈希并记录在缓存里，如果同一哈希的消息在短时间内再次经过同一Agent，直接判定为循环，终止流转。这道保险在后面Agent还没有那么智能时特别管用，网上很多人叫它"防死循环探测"，本质上就是个有状态缓存。
5.2 坑二：超时重试和消息乱序，差点弄丢任务
早期版本里，Agent-Reach的重试逻辑是这样的：发送给Agent A，超时了，重试发送给Agent B。有一次Agent A其实已经收到任务了，只是处理慢，Ack回传的时候超时了，网关这边立即重发给了Agent B。结果就是同一个task_id被两个Agent同时处理。
解决办法是引入两级幂等：网关在生成的message_id上做去重，Agent在payload.task_id上做业务幂等。也就是说，Agent收到一个task_id时，先去自己的处理表里查一下有没有处理过，处理过就直接回Result，不再重复执行。自那以后，同一任务的重复执行率从接近于零的控制住了，极端情况下会出现重复投递，但不会出现重复扣库存这类业务事故。做异步系统的人常说"at least once"是无法避免的，业务上能接受重复投递，但Agent侧必须有幂等处理。
5.3 坑三：配置分发不齐，Agent用不同版本的协议聊天
这个问题是在一次版本升级后暴露的。当时我把AgentInfo里的capabilities字段从数组改成了对象结构，结果没有同时升级所有Agent实例，老Agent还在用旧协议，新网关按新协议解析，直接解析失败，注册和路由都异常，整个集群服务了大约四十分钟不可用。
后来我建立了两个机制。一是schema version握手：注册时和派发时都带上schema_version，网关发现版本高于自己支持的版本，立即拒绝并提示"请升级网关"，而不是强行解析。二是灰度升级策略：升级Agent协议时，先升级网关，再分批升级Agent，观察一段时间注册和路由成功率没有异常后，再全量切流。这套协议版本管理机制我现在已经沉淀成Agent-Reach的默认配置，再没出过同类事故。
5.4 踩坑方法论：线上问题排查思路
几次事故之后，我总结出一条经验：多Agent系统排障，第一件事永远不是去翻Agent的代码，而是先把消息链路的日志拉出来。看看message_id经过哪些节点、每个节点的耗时、在哪一跳状态变成异常，基本就能把问题范围缩小到一个具体Agent上。所以我强烈建议你在Agent和Agent之间传递消息时，务必保留下游返回的原始错误信息，而不是只返回一个"ERROR"状态码。否则一个Agent报错，上游Agent只能对着"ERROR"干瞪眼，排查链路会非常痛苦。
6. Agent-Reach还能怎么走远
Agent-Reach做到现在，核心功能已经稳定，我最近在思考几个扩展方向。一个是事件溯源，记录每个任务的完整时间线，方便事后回放和复盘，这对业务审计场景很关键。另一个是跨网段路由，目前它只能在同一网络内工作，后续打算加一层网关对网关的联邦协议，把多个网络里的Agent集群连接起来，类似物联网里的网关级联。还有一个是配额与优先级，现在所有Agent的任务都是平等对待的，但实际业务里核心链路的任务应该比边缘任务有更高的优先级，不能让一个批量通知任务占用了订单处理的路由带宽。
最后说一句自己的体会。Agent-Reach不是一个"智能"的系统，它做的事很笨——登记、转发、确认、记录，但正是这些笨而稳定的机制，撑起了上层Agent之间聪明的协作。我见过太多做Agent的朋友把精力全花在"让单个Agent更聪明"上，忽略了Agent和Agent之间的连接质量，结果单个Agent再聪明，协作时也是鸡同鸭讲。基础设施本来就应该是钝的、稳的、无趣的，这是它最该有的样子。如果你也在搭多Agent系统，我建议你先花点时间思考"Agent怎么可靠地触达彼此"这个问题，再决定要不要用Agent-Reach或者自己写一套，这笔投入值得的。
