★ FEATURED ARTICLE 第一次听到 Agent-Reach 这个名字时我下意识把重心放在 Agent 上以为又是什么花哨的 Agent 编排框架。后来在一个多 Agent 项目里三个独立部署的智能体怎么都互相调不通我才真正意识到问题不在智能而在触达。Agent-Reach 要解决的不是让 Agent 更聪明而是让 Agent 之间能够稳定、安全、可追踪地互相找到对方、发起请求、拿到回执。这篇文章就把我的理解、实际接入过程、以及踩过的几个坑完整写出来希望给正在做多 Agent 协作的团队一个可参考的落地思路。1. 先把名字拆清楚Agent-Reach 解决的是触达而不是智能很多刚接触多 Agent 系统的朋友会问Agent 之间通信不就互相发个 HTTP 请求吗顶多加个消息队列。这话听着对但只适用于两个写死的 Agent这种玩具场景。一旦 Agent 数量超过三个、部署在不同环境、能力和职责会动态变化最痛苦的根本不是大模型怎么调用而是我到底该找谁、怎么找到它、怎么把话传到它手里。1.1 单 Agent 的程序员思维我们写传统程序时调用关系是编译期或者部署时就定好的A 服务知道 B 服务的地址B 服务暴露接口A 用 SDK 或者 HTTP 调用。这套模式在单体服务和微服务时代都够用因为服务边界是静态的接口签名是明确的调用链路由注册中心和负载均衡帮我们维护。但在 Agent 场景下这个假设崩了。我做的第一个多 Agent 实验是这样的一个调度 Agent 根据用户意图决定让客服 Agent还是售后 Agent去处理。当时我直接把两个子 Agent 的 HTTP 地址写死在调度器配置里用requests.post调用。一开始很顺利后来加了第三个物流查询 Agent地址变了能力也变了调度器里的 if-else 开始失控。我意识到我写的是预定路径的调用而 Agent 协作需要的是按能力动态寻找路径。1.2 多 Agent 环境下的三个真实困境真正让我下决心自己去写一层触达框架的是下面三个困境第一是动态发现困难。Agent 是独立进程尤其在我把它拆成 Docker 容器之后IP 地址和端口每次重启都可能变。现有 RPC 框架能解决服务发现但发现的是服务名不是能力。我要找的是能查订单状态的 Agent而不是名为order-service的固定服务。第二是意图对齐成本高。不同的 Agent 可能由不同人开发接口参数命名、语义、返回格式完全不一样。调度 Agent 要用自然语言向目标 Agent 表达需求传统 RPC 的强类型接口根本不允许这种模糊匹配。第三是会话上下文断裂。一次用户对话可能跨多个 Agent先由对话 Agent 理解意图转给业务 Agent 查询再让内容 Agent 生成回复。中间的上下文如果靠每个 Agent 自己拼参数很容易丢字段、丢状态最后用户收到的回复像是失忆了一样。1.3 触达层与智能层的边界Agent-Reach 这个名字里的 Reach我理解就是触达把一次请求-处理-回执的完整链路抽象出来让它不再依赖具体传输协议、不再依赖目标 Agent 的硬编码地址、也不再要求调用方提前知道被调方的内部实现。注意Agent-Reach 不碰智能决策。它不替你做 Agent 该调用谁那是上层编排或者模型推理的事它只保证一旦你决定要触达某个能力这个消息能可靠地到达正确的 Agent并且得到可验证的回执。打个比方它更像物流网络而不是派单大脑。你不需要知道快递员长什么样、走哪条路你只需要贴着快递单包裹就能到该去的地方。Agent-Reach 就是那个贴快递单、分拣、送件的物流层。2. 为什么现成的 RPC 和消息队列在 Agent 场景下不够用有人会问Kafka、gRPC、NATS 这些不都是干通信的吗为什么还需要一个 Agent-Reach说实话都能用但都很别扭。这里把几个关键差异讲透。2.1 服务寻址 vs 能力寻址传统 RPC 的注册中心里存的是服务名 - 实例列表。调用方知道服务名从注册中心拿实例地址然后负载均衡发起调用。Agent-Reach 的能力注册表不一样。它存的是一条条能力声明一个 Agent 能做什么、输入大概是什么、输出大概是什么、可靠性如何、是否有权限约束。比如同一个查询订单能力可能有三个 Agent 都能做但它们的准确率、成本、响应时间不一样。调度方需要的是在能力层面做挑选而不是指定一个固定服务。我实际测试过如果只用 gRPC 做多 Agent 通信日程安排 Agent 要调用查天气 Agent时就得先找到服务名weather-agent然后找 proto 文件知道GetWeather方法的参数类型。这个流程在 Agent 数量少时能忍数量一多、能力一变维护成本就是灾难。Agent-Reach 的能力寻址天然允许我不知道具体是谁能处理但我描述清楚需求网络帮我找到最合适的对象。2.2 意图路由从调用接口到表达需求传统接口讲究精确。getWeather(city: string, date: string) - WeatherInfo参数类型错了就编不过。但 Agent 之间尤其是与 LLM 结合的 Agent更像人在协作你说帮我看看明天上海会不会下雨对方能理解不需要你把参数拆开。所以 Agent-Reach 的触达消息里除了结构化的头部消息 ID、目标能力、发送方、时间戳正文部分允许携带自然语言描述或者半结构化的需求。路由层会将这个需求与能力声明的描述做匹配。这相当于把 REST 的Content-Type从application/json扩展成application/nljson让模型来补足意图字段。我在实际项目里让一个 Agent 发送{intent: 查一下订单OW20250112的物流轨迹}没有指定具体 AgentAgent-Reach 根据物流轨迹这个能力描述把消息路由到了物流 Agent。整个过程没有写一行 if-else。2.3 会话与上下文一次触达不是一次请求传统 RPC 的请求是一次性的客户端发请求服务端返回响应结束。即便有 trace ID也只是链路追踪不会主动把之前的对话上下文带给下游。Agent 触达不一样。同一个用户问题可能是多次触达的组合。例如用户问我买的 iPhone 什么时候到对话 Agent 需要先做一次触达去查订单拿到订单号后再做一次触达去查物流。这两次触达必须共享同一个会话上下文而且下游 Agent 最好能感知用户正在气头上这类情绪信号否则回复可能很生硬。Agent-Reach 会在触达消息头里携带session_id和context_ref。context_ref指向上下文存储中的某个快照下游 Agent 如果需要可以主动拉取而不是每次把全量上下文都塞在消息体里。这个设计的收益在长对话场景尤其明显能大幅减少 token 消耗也避免无关上下文干扰判断。2.4 安全边界的动态性另一个传统框架容易忽略的是权限。微服务时代权限通常在网关层做服务间内部调用默认信任。但 Agent 世界里有些 Agent 属于不同团队、不同信任域甚至可能跑在不同公司的边界内。你不能默认只要网络通就能随便调别人的 Agent。Agent-Reach 把权限和身份下沉到触达层每个 Agent 有独立的身份令牌能力声明里写明谁能调用我。调度方触达一个敏感能力时可能需要额外的授权票据比如用户在会话里的授权记录。这样一个不懂事的调度 Agent 乱调用其他 Agent 时至少会被权限层挡下来而不是直接打到目标 Agent 上。3. Agent-Reach 的核心机制拆解注册、路由、触达、回执前面讲了很多理念现在落到机制层面。我把自己设计的 Agent-Reach 协议栈拆成四个核心组件能力注册表、路由引擎、触达通道、回执处理。每个组件都有明确的职责和边界。3.1 能力注册表与心跳保活能力注册表的数据结构不复杂核心是{ agent_id: agent-logistics-01, capabilities: [ { name: query_logistics, description: 查询订单物流轨迹支持快递单号和订单号, input_schema: { order_id: string, carrier: string(optional) }, output_schema: { status: string, estimated_delivery: string }, reliability: 0.98, cost_per_call: 0.02, auth_required: true } ], endpoint_hint: reach://agent-logistics-01.channel-a.internal, heartbeat_ttl: 60 }每个 Agent 注册后要周期性发心跳。如果超过 TTL 没有心跳路由引擎就不会再把新触达消息发给它。这个设计很关键因为 Agent 进程可能崩溃、被 OOM 杀掉、或者网络分区。如果靠调用方自己感知失败那么调用方就得实现重试、熔断最后通信逻辑和业务逻辑全咬死在一起。我在项目里的经验是心跳 TTL 不要设太短否则 Agent 做一次长任务比如 LLM 生成还没来得及发心跳就被标记离线。我的建议是 TTL 设为任务最大耗时的两倍最小不少于 30 秒。3.2 消息路由协议的三个原语Agent-Reach 的通信模型可以简化为三个原语我直接列给你原语方向典型场景reach.request调用方 - 目标能力需要同步等待结果如查订单、算价格reach.dispatch调用方 - 目标能力异步派发任务不立即要结果如生成周报reach.subscribe调用方 - 能力事件流订阅状态变化如物流状态更新、库存告警reach.request对应传统 RPC 的请求/响应适合响应时间短、结果必须回来的场景。reach.dispatch则用于触达但不等的场景我先告诉你一个任务你处理完给我发一个reach.callback回执。reach.subscribe把单个请求变成了长连接式的事件流适合持续监控型 Agent。这三个原语的实现不需要自己造轮子。我基于 NATS JetStream 做底层消息通道用 Redis 做能力注册表的缓存上层再套一层 JSON 协议。为什么不用 Kafka因为 Agent 触达的消息量通常不大但延迟要求高、路由要灵活NATS 的轻量发布订阅正好合适。3.3 幂等任务与幂等回执的设计Agent 项目里最容易出的问题就是重复执行。比如调度 Agent 发出一个reach.dispatch因为网络抖动没收到回执于是重试了一次。如果目标 Agent 不处理幂等同一个通知可能被发送两遍用户会收到重复短信。Agent-Reach 的解决方案是每条触达消息都带一个全局唯一的message_id目标 Agent 在执行业务逻辑前先检查这个message_id是否处理过。做法是在 Agent 内部维护一张已处理消息表或者让 Agent 框架自动把message_id作为分布式锁的 key。我建议用 Redis 的SET NX EX做幂等锁# Python 伪代码 import redis r redis.Redis(hostredis.internal) def is_duplicate(message_id: str, ttl: int 300): # 如果设置成功说明是第一次处理 return r.set(fdedup:{message_id}, 1, nxTrue, exttl) is False这个方案简单可靠。需要注意的是 TTL 不要短于业务最大处理时间否则一个慢任务刚处理完重试消息又进来了还是会被当成新任务。回执同样有幂等需求。目标 Agent 处理完任务后向调用方发送reach.callback里面必须带上原始的message_id和状态。调用方收到回执后更新自己维护的任务状态表。如果回执丢了调用方会超时重发reach.request但目标 Agent 通过message_id识别出这是同一个任务直接返回缓存的结果而不是再次执行。3.4 断线、迟到、重放怎么处理分布式系统里消息不可能永远即时Agent 场景尤其明显。最典型的情况是目标 Agent 正在执行一个耗时 5 分钟的 LLM 任务调用方等了 3 分钟就超时了但任务其实还在跑。如果调用方直接放弃底层任务就变成了孤儿任务。Agent-Reach 的处理策略是把超时和取消分开。超时只是调用方不再同步等待但触达消息仍在目标 Agent 上正常执行。执行完成后回执依然会被投递给调用方。调用方哪怕已经不对当前响应抱期望也可以把结果缓存起来等用户后续追问时直接使用。如果调用方明确想取消需要发reach.cancel消息目标 Agent 收到后检查任务状态如果能中断就中断不能中断则返回一个cancel_acknowledged的回执。迟到消息方面调用方应该校验message_id与session_id避免把旧任务的回执应用到新任务上。我在日志里加过一条规则回执的时间戳如果早于任务发起时间直接忽略并告警。这能有效防止消息重放到错误状态。4. 看懂配置与接入流程从零把一个 Agent 挂到 Reach 网络上前面原理讲得再多落地才是关键。这一节我用自己的一个实际案例演示接入流程。假设我有一个日程助手 Agent需要让它触达天气 Agent来决定会议是否需要改期。4.1 快速启动一个 Reach LinkAgent-Reach 的运行时组件叫 Reach Link它本质上是每个 Agent 旁边的通信代理负责心跳、注册、接收消息、调用本地 Agent。启动方式很简单用 Dockerdocker run -d \ --name reach-link-weather \ -e REACH_NODE_NAMEweather-agent \ -e REACH_NODE_ROLEprovider \ -e REACH_REGISTRY_URLnats://registry.internal:4222 \ -e REACH_REDIS_URLredis://redis.internal:6379 \ -p 8123:8123 \ agent-reach/link:0.4.2启动后Link 会自动向注册中心注册并开始发送心跳。如果你在本地做测试也可以用reachlink命令行直接跑reachlink start --name weather-agent --registry nats://127.0.0.1:4222启动成功日志里会有一行registered with heartbeat ttl60s看到这个就说明注册成功了。4.2 声明你的 Agent 能力天气 Agent 需要在自己的配置目录放一份capabilities.yamlagent: name: weather-agent version: 1.2.0 capabilities: - name: query_weather description: 查询指定城市和日期的天气情况包括温度、降水概率 input_schema: city: string date: string output_schema: temperature: number condition: string precipitation_probability: number auth_required: false这里最重要的字段是description。路由引擎匹配能力时一般会计算触达消息里的需求文本与description的语义相似度。所以描述别写太抽象比如查询天气就太宽泛建议写成查询指定城市和日期的天气情况这样调度 Agent 能更准确地找到你。写完配置后执行reachlink apply --config capabilities.yamlLink 会读取配置并更新注册表。每次更新版本号都要递增否则路由引擎可能认为历史版本仍然有效。4.3 从调用方发起一次触达现在调度 Agent 要调用天气能力。我在调度代码里这样写from agent_reach import ReachClient client ReachClient() # 异步派发触达天气 Agent请求查询上海2025-06-01天气 resp client.dispatch( capabilityquery_weather, payload{city: 上海, date: 2025-06-01}, session_idsession-1234, timeout30s ) # 如果只是想发起不管结果的触达可以不用等 resp这里没有指定具体 Agent而是指定了能力名。路由引擎会根据能力名、当前在线 Agent 列表、以及面负载情况自动选择最合适的实例。我测试过同一个能力注册了三个 Agent路由引擎默认按响应速度加权轮询也可以配置按成本优先。4.4 验证触达链路是否健康接入完之后第一件事不是急着看业务结果而是看监控。Agent-Reach 自带一个轻量级的 Prometheus 指标暴露端点我通常关注四个指标指标含义理想区间reach_messages_total总触达消息数持续增长reach_route_failures_total路由失败次数为 0reach_roundtrip_seconds端到端往返耗时 P95视场景而定reach_callback_timeout_total回执超时次数越低越好有一次我发现reach_route_failures_total一直有增长查日志看到no agent matched capability: query_weather。原因是天气 Agent 的capabilities.yaml里把能力名写成了query_weather_info而调用方发的是query_weather。能力名精确匹配没成功。后来我在能力路由里开了语义匹配兜底——如果精确匹配不到就改用description做向量相似度匹配。但在生产环境还是建议统一维护能力名的命名规范不要依赖兜底。5. 我在项目里踩过的四个坑排查链路完整版)这一节我按真实排查顺序写不直接给结论。希望对你有启发。5.1 坑一Agent 注册了但调不通问题出在超时配置现象是某个 Agent 明明在线心跳也正常但调用方发reach.request总是抛timeout。我的第一反应是网络问题ping了目标容器通了。然后看注册表状态也是online。后来把链路日志打开发现触达消息确实到达了目标 Link但 Link 投递给本地 Agent 用了超过 60 秒。原因是我调用的模型响应时间太长了而调用方的默认超时是 30 秒。Link 本身没有超时限制但调用方先放弃了导致整个链路看起来像不通。排查结论Agent 场景的处理耗时比传统 API 高一个数量级LLM 生成可能要几十秒。超时配置不能照搬微服务习惯reach.request的超时要设置成目标 Agent 的预估响应时间加上可靠缓冲。我后来把调用方超时设置成 120 秒并且增加了reach.request的先返回确认、后返回结果模式调用方至少能快速收到已受理不用干等。5.2 坑二异步任务被重复执行原因是回执丢了调度 Agent 发了一个reach.dispatch让通知 Agent 给用户发短信。目标 Agent 执行完发送reach.callback但那个瞬间 NATS 连接闪断回执没发出去。调度 Agent 等不到回执按策略重发了reach.dispatch。由于我没有做幂等处理用户收到了两条一模一样的短信。排查链路是这样的先从数据库里查任务状态两条任务记录都在completed状态但message_id不一样。再查回执日志果然第二个任务的回执是重发之后才收到的第一个任务的回执因为断线丢了。解决方案我前面说过message_id幂等。其实重发逻辑本身也是必要的但不能因为重发导致重复执行。目标 Agent 框架应该自动基于message_id去重而不是依赖业务代码自己记。这应该内建在 Agent-Reach 的运行库里而不是每个业务 Agent 自己写。我后来把幂等检查挪到了 Link 层任何触达消息进入本地 Agent 之前先查dedup表这样业务代码完全无感知。5.3 坑三自然语言意图被错误路由到能力相似的 Agent有一次用户说帮我看看这单东西到哪了调度 Agent 把消息转了出来。结果路由到了商品推荐 Agent因为它的能力描述里有根据订单偏好推荐商品。两个 Agent 的能力描述都和订单相关但实际语义完全不同。这个问题比精确匹配麻烦很多。我当时的解法是在能力描述里加入排除词和典型问题示例。比如物流 Agent 的description写成查询订单物流轨迹不支持商品推荐并在example_queries里加几条典型问题我的快递到哪了物流状态是什么。路由匹配时example_queries的语义相似度权重高于description这样准确率大幅提升。后来我还加了一道校验层当多个 Agent 的匹配分数差距小于 0.05 时路由引擎不自动选择而是把候选列表返回给调度 Agent由 LLM 做一次轻量决策。虽然多了一步但在关键业务上值得。5.4 坑四上下文丢失导致下游 Agent 回答失忆调度 Agent 先调用了订单查询 Agent拿到了订单信息然后把这段信息直接拼到下一个触达请求里。结果因为请求体太大中间一层做了截断物流 Agent 收到的上下文里只有订单号没有商品描述回复里就少了很多细节用户觉得回答很敷衍。这个问题的根源在于上下文透传依赖人工拼装而不是框架层保障。我在 Agent-Reach 里做了一个context_ref优化触达消息只带context_ref下游 Agent 通过这个引用从上下文服务拉取完整的、分层的上下文。上下文服务支持按需裁剪比如物流 Agent 只需要订单号和地址就只给它两个字段。从这以后再也没有因为消息体被截断导致失忆。如果你现在还在用 JSON 大字段传上下文强烈建议改成引用式传递这能省掉大量调优时间。6. 从 Agent-Reach 看下一阶段的 Agent 协作形态最后聊聊扩展。我始终觉得 Agent-Reach 这类触达层会慢慢成为 Agent 基础设施的一部分这里有几个我认为必然会出现的演进方向。6.1 联邦触达多个 Reach 网络互联单个团队内部用一套 Reach 网络很简单但跨团队、跨公司就麻烦了。A 公司的 Agent 想调用 B 公司的机票预订 Agent不可能把 A 的注册表开放给 B。联邦触达的思路是每个 Reach 网络有一个对外网关只暴露经过脱敏的能力目录不暴露内部拓扑。触达消息通过网关时会经过双方的访问控制策略还可以加上计费、审计。这有点像电子邮件的 MX 记录你可以给任意地址发邮件但对方接不接受、收不收费由对方决定。我自己的一个粗浅实践是在两个隔离的 Reach 网络之间建立了代理 AgentA 网络里有一个external:booking能力真实指向 B 网络的某个 Agent。A 的调度方完全感知不到跨网络所有跨域策略都代理在网关层处理。6.2 触达成本与限流Agent 调用不是免费的尤其是涉及 LLM 的 Agent每次触达都有 token 成本。如果调度 Agent 发起了 100 次无效触达账单会很可观。所以 Agent-Reach 这类框架应该内置额度管理。能力声明里可以带上cost_per_call路由引擎在多个候选 Agent 之间做选择时会考虑成本因素。另外调用方可以设置预算上限超过后路由引擎直接拒绝并回一个budget_exceeded错误。我自己在项目里给每个调度 Agent 配置了每月 1000 次触达额度超过后自动降级到离线规则引擎虽然没那么智能但成本可控。6.3 离线和边缘场景的触达缓存不是所有场景都在云服务器上。有些 Agent 跑在用户本地电脑、边缘网关里可能断网。传统同步 RPC 根本没法用。Agent-Reach 的异步dispatch天然适合这类场景调用方把触达消息暂存在本地队列网络恢复后再重放。目标 Agent 上线后可以从注册表同步缺失的触达消息。这个机制和邮箱的离线发送一模一样。我测试过把触达消息缓存到 SQLite断网两小时再恢复消息一条不少地送达。边缘场景里的reach.subscribe也很有用比如边缘 Agent 一直订阅中心下发的模型更新事件一旦中心发布新版本边缘 Agent 自动拉取并加载。如果推送改成轮询成本高且时延大。最后说点个人体会Agent-Reach 这个名字现在在我理解里不再是一个框架名而是一种思维方式先解决触达再谈智能。我见过很多团队一上来就让 Agent 们自由对话结果消息乱飞、上下文丢失、互相阻塞最后项目一地鸡毛。其实只要先把触达层做扎实——能力注册清晰、路由可靠、回执可追溯、幂等不出错上层哪怕只是简单的 if-else 也能跑出稳定的多 Agent 系统。如果你正准备设计自己的多 Agent 架构我的建议是别急着写大模型调度代码。先画一张图你的每个 Agent 有哪些能力谁可以调用谁触达超时多少重复消息怎么去重以及跨 Agent 的上下文怎么传递。把这张图画明白再选择 Agent-Reach 或者类似的触达层方案都不迟。顺序对了后面能少加一个月的班。
阅读完成 · 觉得有帮助？
