Agent-Reach：多智能体协作的触达层架构设计与实践

上周我把 Agent-Reach 的触达层代码重构到 2.0 版本，总算把两个核心 Agent 之间的调用链路压到了 300 毫秒以内。这个项目名听起来像个抽象概念，实际上是我在多智能体协作项目里沉淀出来的一套触达中间层设计思路。如果你也在搞多智能体系统，大概率遇到过这种情况：模型能力选得挺好，提示词也调得不错，可两个 Agent 一对接就卡壳，要么接口协议对不上，要么根本找不到对方，要么调用超时后雪崩。这就是我口中常说的"触达问题"。

这篇文章不打算讲 Agent 怎么写提示词，也不聊模型微调，只聚焦一件事：Agent 怎么找到目标、怎么沟通、怎么把一次跨系统调用稳定地跑完。我会把 Agent-Reach 的架构拆解开，讲清楚注册中心、消息信封、路由策略和治理逻辑，再给出一套可以直接落地的实操记录，包括配置示例和三个真实踩过的坑。无论你是后端开发者、AI 应用工程师，还是刚接触多智能体协作的小白，这套思路都能直接用上。

1. Agent-Reach 到底要解决什么问题

1.1 一次让人抓狂的联调经历

先说个真实场景。我接手过一个订单自动化项目，里面有两个 Agent：一个负责解析用户订单意图，另一个负责查库存。前者的接口是 gRPC，返回 protobuf；后者是 HTTP REST，返回 JSON。订单 Agent 调用库存 Agent 时，协议对不上，字段名对不上，鉴权方式也不同，一个要求 OAuth2，一个要求 API Key。光是让这两个 Agent 正常说上话，我们就花了一周。

后来我意识到，这类问题的根源不在于模型笨，而在于 Agent 之间的"触达"没有任何统一治理。每个 Agent 都知道自己"能做什么"，但不知道"怎么被别人找到"、"用什么样的协议说话"、"失败了该由谁来兜底"。这是典型的集成问题，却被很多人误当成 AI 问题去解决。

Agent-Reach 这个名字，就是我在痛定思痛之后给这套方案起的代号。它要回答的只有三个问题：第一，调用方如何发现并路由到正确的目标 Agent；第二，异构协议之间如何统一转换；第三，跨 Agent 调用如何做到可观测、可重试、可熔断。

1.2 我把触达拆成了三个维度

在设计 Agent-Reach 时，我把"触达"拆成了三个维度，分别对应不同的技术挑战。

第一个维度是寻址。也就是调用方怎么知道"该找谁"。"找谁"包括两层意思：找哪个 Agent，以及找这个 Agent 的哪个能力。我见过太多项目把 Agent 的地址硬编码在代码里，Agent 一扩容就抓瞎。正确做法应该是引入注册中心，让 Agent 启动时上报自己的地址、能力列表、协议类型和健康状态，调用方只按"能力名"寻址，不关心具体节点。

第二个维度是沟通。两个 Agent 即使找到了彼此，如果协议不一样、数据格式不一样，也没法对话。最简单的做法是规定一种统一的消息格式，让所有 Agent 对外暴露时都包一层"信封"，把业务数据和通信元数据分开。业务数据爱用什么格式就用什么格式，信封负责统一。

第三个维度是保障。分布式系统里的调用不可能永远成功，超时、重试、熔断、幂等这些老生常谈的东西，在 Agent 场景里会被放大。因为 Agent 通常是有状态的，同一个请求重发两次，可能产生重复订单、重复退款这类严重后果。触达层必须内置治理能力，而不是让每个 Agent 自己实现一套。

这三个维度，对应到架构上就是注册中心、消息信封和治理策略。后面几个章节我会逐个展开。

2. 为什么"触达"才是多智能体协作的隐形瓶颈

2.1 模型负责想，触达负责做

很多人评估一个多智能体系统好不好，第一反应是看模型强不强、提示词精不精。这当然重要，但业务跑不通的时候，问题往往不出在"想"上，而出在"做"上。

我打个比方。你把一个公司里所有员工都换成了顶尖顾问，每个人都聪明绝顶，但公司没有内线电话、没有邮件系统、没有会议室预订机制，顾问之间想协调一件事只能靠喊。这个公司能高效运转吗？肯定不能。模型就是顾问的脑子，Agent-Reach 就是那套内线电话和会议室系统。

实际项目里，Agent 要触达的对象不只是其他 Agent，还有数据库、工单系统、企业微信、短信网关、第三方 SaaS。这些系统的协议五花八门，有 HTTP、gRPC、WebSocket，有 XML、JSON、二进制流。如果每次新增一个下游系统都要改一遍 Agent 的代码，这个系统根本维护不下去。触达层的价值就在于把这些差异收敛到一个统一入口，Agent 只跟触达层说话，剩下的由触达层去适配。

所以我常说一句话：模型能力决定这个系统可能有多聪明，触达能力决定这个系统实际有多可靠。后者才是最容易拖垮项目的隐形瓶颈。

2.2 三类典型触达场景的差异

我按触达对象不同，把场景分成三类，设计策略时需要区别对待。

第一类是 Agent 到 Agent，也就是 A2A。这是最常见的场景，一个 Agent 的输出作为另一个 Agent 的输入。这类触达的核心痛点是寻址和协议统一。A2A 的调用通常是高频的、结构化的，适合走内网 RPC，对时延和稳定性要求最高。

第二类是 Agent 到系统，也就是 A2S。比如 Agent 要查询数据库、调用支付接口、写入 CRM。这类触达的核心痛点是适配和鉴权。下游系统千差万别，有的连批量接口都没有，有的限流很狠，触达层需要做协议适配、流量整形和错误码归一。

第三类是 Agent 到人，也就是 A2H。比如 Agent 判断订单异常，需要人工审核确认后再执行。这类触达的核心痛点是渠道管理和反馈闭环。你要保证消息确实送达了某个人，还要等人确认之后再把结果回传给 Agent。很多团队把 A2H 做成了发一条通知就完事，结果 Agent 那边傻等，人工这边根本没看见。正确的做法是给每条 A2H 消息分配一个确认令牌，人工处理完通过回执接口通知 Agent，Agent 收到回执才继续执行。

这三类场景的差异决定了触达层不能只做一种通用接口。我在 Agent-Reach 里给这三种触达分别定义了不同的 channel 类型，后面实操部分会展示配置写法。

2.3 硬编码触达的四个致命伤

不引入触达层，直接让 Agent 自己调别人，会怎么样？根据我的经验，前期 Demo 跑得飞快，后期维护痛不欲生。硬编码触达的四个致命伤，我一个一个说。

第一是点对点耦合。Agent A 的代码里写死了 Agent B 的地址和接口，哪天 B 换了地址或者拆成两个服务，A 必须发版。在 Agent 数量少的时候还能忍，Agent 一多就是蜘蛛网，改一个动全身。

第二是错误处理各自为政。A 调 B 超时了怎么办、B 返回了一个不认识的错误码怎么办、要不要重试、重试会不会造成重复数据，每个 Agent 都自己写一遍。最后你会发现，十个 Agent 有十套错误处理逻辑，线上出问题时根本没法统一排查。

第三是链路断裂。没有统一的 traceId，一个请求从 Agent A 到 Agent B 再到下游系统，日志分散在好几个服务里。出了问题要跨日志系统去拼一个完整链路，手工查好几个小时很正常。

第四是能力无法复用。某个 Agent 本来已经接好了短信网关，另一个 Agent 也想发短信，但因为前者的接口是私有的、耦合的，第二个 Agent 只能重新接一遍。重复建设这个事，在缺少触达层的系统里是日常。

这四个致命伤，发生一个就够折腾了，四个叠在一起，这个多智能体系统基本就是个运行期的定时炸弹。

3. Agent-Reach 的架构设计与核心实现

3.1 总体分层：触达层保持无业务状态

Agent-Reach 的整体架构分为四层：接入层、路由层、协议转换层和治理层。接入层负责接收 Agent 的注册信息和触达请求；路由层根据能力标签和服务状态决定把请求发给谁；协议转换层处理各种数据格式和协议的互相翻译；治理层做超时、重试、熔断、限流和审计。

这四层里面，最核心的一条设计原则是：触达层不保存业务状态。什么意思？比如支付 Agent 处理一半，触达层不会帮它记住订单数据；库存 Agent 查完了，触达层也不缓存库存结果。业务数据只在信封的 payload 里流过，触达层只关心信封上的元数据。这么做有实实在在的好处：触达层随时可以无损重启、扩容、发布，不会因为持有状态而成为新的单点；业务 Agent 可以保持无状态，方便横向扩展。

有人会问，那 Agent 之间的会话状态怎么办？我在 Agent-Reach 里的做法是把会话状态放在"会话 Agent"里，专门有个 Agent 负责管理上下文，触达层只负责把这个 Agent 的请求路由过去。这样职责清楚，各管一段，不会出"触达层偷偷存了业务数据"这种脏东西。

3.2 注册中心：让 Agent 能被找得到

注册中心在 Agent-Reach 里扮演的角色，相当于公司里的通讯录。每个 Agent 启动时，向注册中心上报一系列元信息，包括服务名、实例地址、能力列表、协议类型、权重和健康检查接口。

我用的注册模型是"服务名 + 能力标签"双维度。服务名解决"找哪个 Agent"的问题，比如 order-service；能力标签解决"找这个 Agent 的哪个能力"的问题，比如 parse-intent、check-inventory。一个 Agent 可以上报多个能力标签，一个能力也可以由多个实例承载。

这里有个容易踩坑的地方：能力标签的命名必须全局统一。我见过有人把"查库存"写成 check-stock，另一个人写成 inventory-query，结果路由表里两个标签指向同一个 Agent，调用方用错标签就查不到数据。我的建议是维护一份能力字典，每个能力有唯一的 ID 和描述，Agent 上报时引用字典里的 ID，而不是自由发挥。

注册中心推荐用 etcd 或者 Consul 这类天生支持服务注册和健康检查的组件。我自己用的是 etcd，原因很简单：watch 机制成熟，路由表变更可以实时推送给调用方；租约机制能自动清理不健康的 Agent 节点。注册信息里一定要带一个 schema_version 字段，防止新旧 Agent 上报的元信息格式不一致导致解析失败。

3.3 消息信封与协议转换

触达层统一的消息格式，我称之为 Envelope，也就是信封。信封分三个部分：Header、Payload 和 Meta。Header 放路由信息，包括消息 ID、来源 Agent、目标 Agent、目标能力、消息类型、优先级。Payload 放业务数据，可以是 JSON、XML、protobuf 字节流，甚至是一段文本。Meta 放链路上下文，包括 traceId、调用链路径、幂等键、鉴权凭证、超时策略引用。

举个例子，订单 Agent 调用库存 Agent，信封大概是这样的：

{ "header": { "msg_id": "msg_8f3a2c9e1b4d", "source_agent": "order-service", "target_agent": "inventory-service", "target_capability": "check-inventory", "priority": "high" }, "meta": { "trace_id": "trace_7e1a5c9d0f22", "idempotency_key": "idem_20240511_order_99813", "auth_token_ref": "token_ref_prod_001", "timeout_policy": "fast" }, "payload": { "sku": "SKU-10086", "warehouse": "WH-NORTH" } }

业务 Agent 之间只感知 Payload，Header 和 Meta 由触达层统一管理并填充。这样即使两个 Agent 的业务数据结构完全不同，触达层也能通过转换器把一边的 Payload 翻译成另一边的结构。

协议转换层我建议用插件化设计。每一种"传输协议 + 数据格式"组合对应一个 adapter，比如 http-json-adapter、grpc-protobuf-adapter、mq-xml-adapter。新接入一种下游系统时，只需新增一个 adapter，不用改动路由层和治理层。有一个细节值得注意：adapter 里不要写业务逻辑，只做数据搬移和格式翻译。一旦 adapter 里混入了业务判断，后面排查问题时会非常痛苦。

3.4 路由与治理策略

路由层拿到信封后，按 target_capability 查注册表，得到候选实例列表，再通过策略选出一个实例。我常用的路由策略有三种：轮询、加权随机和一致性哈希。轮询适合无状态 Agent；加权随机适合实例性能不一的场景；一致性哈希适合需要把同一个用户的请求固定到同一个 Agent 实例的场景，比如会话 Agent。

除了基本策略，还要支持灰度路由。比如新版本库存 Agent 只上线了 10% 的流量，可以在路由表里配置版本标签和流量比例。配置中心里加一条规则就行：version=v2 且 grain=10%。这个灰度切换不影响调用方，是触达层比较实用的能力之一。

治理策略这块，重点说三个：超时、重试和熔断。

超时我分成三档。快速档适合查询类能力，比如查库存、查订单状态，超时设为 2 秒。慢速档适合需要调第三方 AI 模型的能力，比如意图识别、文本生成，超时设为 15 秒。后台档适合异步任务，比如批量打标签、数据同步，超时放宽到 60 秒，并配一个回调接口通知结果。这样分档的好处是，查询类请求因超时堆积导致的雪崩，能被及时兜住。

重试策略必须配合幂等键使用。每次触达请求的 Meta 里带上幂等键，接收方根据幂等键去重。没有幂等键的重试就是耍流氓，轻则重复下单，重则重复退款。重试次数我一般设 2 次，指数退避，间隔 200ms 起步、400ms、800ms，最多到 3 秒。重试只在目标 Agent 返回可重试错误（比如 503、超时）时触发，业务校验错误比如"库存不足"坚决不重试。

熔断我用的是滑动窗口算法。每个目标 Agent 维护一个最近 60 秒的调用结果窗口，失败率超过 50% 且调用量超过 20 次时，触发熔断。熔断状态下，新请求直接返回"目标不可用"的降级响应，不再往目标 Agent 发。熔断 10 秒后半开，放一个探测请求进去，成功则恢复，失败则继续熔断。这套逻辑和微服务里的熔断器一样，但应用在 Agent 场景时有一个关键差异：熔断后要给调用方返回一个对 Agent 友好的降级响应，而不是一个冰冷的错误码。比如订单 Agent 调库存 Agent 熔断了，触达层返回"库存未知，请转入人工审核"，这个响应本身就是 Agent 可以处理的语义。

4. 从 0 到 1 接入实操实录

4.1 先画触达清单

我把 Agent-Reach 落地到具体项目时，第一步不是写代码，而是画一张触达清单。你把项目里所有 Agent、业务系统、人工处理节点都列出来，然后逐对标注"谁要调用谁、调用的什么能力、走什么协议、失败的影响是什么"。

这个清单长什么样？我拿订单自动化项目举例。

这张表的作用是让所有触达需求一目了然，也方便排优先级。我习惯用 Excel 或者在线文档维护，每周过一遍，新增一个 Agent 或系统时先更新清单再动代码。这看起来笨，但确实能避免"漏接一个调用，线上才炸"的情况。

清单里还要额外标注一行"触发条件"。比如风险 Agent 调用人工审核台，触发条件是风控评分超过 70 分。有了触发条件，后面配置路由和编排时才知道什么时候该走哪条触达链路。

4.2 配置与注册：一份能跑的配置

Agent-Reach 的配置我建议用 YAML，结构清晰、注释友好。下面这份配置是一个真实的接入示例，包含注册、路由和治理三部分。

agent: name: order-service protocols: grpc: port: 9001 health_check: /healthz capabilities: - id: cap_parse_intent name: 解析订单意图 schema_version: "1.0" - id: cap_check_inventory_wrapper name: 查询库存（包装库存Agent） target: capability: check-inventory routing: strategy: weighted_random candidates: - agent: inventory-service version: v2 weight: 90 - agent: inventory-service version: v1 weight: 10 fallback: type: degraded_response message: "库存服务暂时不可用，请稍后重试或转人工" timeout: fast: 2000 slow: 15000 background: 60000 retry: max_attempts: 2 backoff: [200, 400, 800] retry_on: [503, timeout, 429] circuit_breaker: window_seconds: 60 failure_threshold: 0.5 min_calls: 20 open_seconds: 10

这段配置里有几个细节值得展开说。cap_check_inventory_wrapper 这个能力不是库存 Agent 自己上报的，而是订单 Agent 的触达层里声明的一个"转发能力"。它让订单 Agent 像一个轻量代理，把能力的请求经过路由层转发给库存 Agent。好处是订单智能体自身的逻辑不用关心库存 Agent 的实例细节，路由策略由触达层统一维护。

fallback 配置在很多人看起来小事一桩，实际很关键。我见过没有 fallback 的项目，库存一熔断，订单 Agent 直接抛异常，用户看到一条"系统繁忙"的报错。加上 lin回退消息后，订单 Agent 拿到的是"库存暂不可用，请转人工"，它可以自己走人工确认流程，体验完全不一样。这就是我前面说的"Agent 友好的降级响应"。

4.3 联调过程中踩过的三个坑

第一个坑是超时配置不匹配导致的连锁超时。我把库存 Agent 的超时设为 2 秒，但库存接口本身要调一个第三方物流服务，平均耗时 3.5 秒。结果触达层全部超时，重试两次，大量请求堆积在库存 Agent 手里，雪崩。排查下来是触达层超时时间设置得比业务实际耗时还短。教训是：超时时间要以"完整业务链路耗时"为准，不能拍脑袋。先跑一次线，记录真实耗时，再加 30% 的余量。

第二个坑是幂等键设计失误。最开始我用"Agent 名加时间戳"做幂等键，结果同一毫秒内两次重试生成了不同键，重复请求漏到下游，导致一张订单被创建了两次。后来改成"业务唯一 ID 加动作类型"的组合键，比如 order_99813_refund_request，接收方按这个键做去重，才真正解决问题。幂等键一定不能用时间戳，要用业务里本来就唯一的 ID。

第三个坑是人工审核触达的确认回执没接好。客服 Agent 把异常订单推给了人工审核台，人工在系统里点了"确认放行"，但确认消息没回到客服 Agent，Agent 一直卡在"等待人工确认"状态。原因很典型：A2H 触达只做了"发出去"，没做"收回来"。我们在触达层为每一条 A2H 消息生成一个 confirmation_token，人工点击确认后带着这个 token 调回执接口，触达层再把回执转成普通消息发给源 Agent，Agent 才继续执行。这个机制现在是我做 A2H 触达的标配。

5. 触达链路观测与日常运维

5.1 触达事件埋点规范

触达层跑起来之后，你要是不做观测，基本等于盲飞。我给 Agent-Reach 定义了一套触达事件埋点规范，每个触达事件记录五个核心字段：来源 Agent、目标 Agent、动作、状态、耗时。再加上消息 ID 和 traceId，组成事件主体。

{ "event_type": "agent_reach", "source_agent": "order-service", "target_agent": "inventory-service", "action": "check-inventory", "status": "success", "cost_ms": 287, "msg_id": "msg_8f3a2c9e1b4d", "trace_id": "trace_7e1a5c9d0f22" }

埋点数据统一写到 ClickHouse 或者 Elasticsearch。我推荐 ClickHouse，因为触达事件是典型的时序写入场景，量大了以后 ClickHouse 的压缩比和查询性能明显好于 ES。每条触达事件最好都带一个 action_name，方便后面按动作聚合统计。

埋点规范里最容易忽略的是"消息在途状态"。一条触达消息从发出到收到回执，中间可能经历多个阶段，比如已路由、已发送、已到达、已处理。我建议每个阶段都打一个事件点，而不是只记录最终结果。否则你只能知道"失败了"，不知道失败在哪一跳。

5.2 全链路 Trace 设计

多智能体系统里，一个用户请求往往要经过好几个 Agent，链路特别长。比如"用户问订单状态 -> 客服 Agent -> 订单查询 Agent -> 数据库 Agent -> 通知 Agent"。要排查这类问题，没有全链路追踪几乎不可能。我在 Agent-Reach 里用的是 W3C Trace Context 标准，在信封的 Meta 里塞 traceparent 字段，格式是"版本号-trace-id-parent-id-flags"。

当触达层路由一个请求时，它会生成或透传 traceId，如果目标 Agent 自身也有子调用，就往下传递同一个 traceId，并追加新的 parentId。这样从用户入口到最终的数据库查询，整条链路可以被串联起来。

实践上，我依赖 Jaeger 做 trace 可视化，埋点里上报的触达事件会和 Jaeger 的 span 做关联。排查问题时，只需要拿着用户反馈里带的 traceId，去 Jaeger 上一查，就能看到这个请求经过了哪些 Agent、每段耗时多少、哪一段失败或超时。没有这套东西的时候，我排查一次"订单 Agent 为什么不回复用户"至少要半个小时，现在基本五分钟内定位。

新手容易犯的错误是只在触达层打 trace，没有要求业务 Agent 的日志也带上 traceId。这会导致你看到触达链路是完整的，但进了 Agent 内部就断了。最好在 Agent 的日志框架里统一配置 MDC，把 traceId 自动注入，让所有日志都带这个 ID。这一步能让你在排查时省下大量时间。

5.3 健康巡检与告警

服务上线的日常运维里，我最依赖的是一个"触达巡检 Agent"。它本质是个定时任务，每隔 30 秒向注册中心里的每个 Agent 发一次 ping 类型的触达请求，就是查个心跳，确认目标 Agent 能正常响应。

巡检的响应时间、成功率直接接到告警系统。我配了三条告警规则：

• 触达成功率低于 99% 且持续 5 分钟，告警 P1，需要立即处理；
• 平均响应时间比基线慢 3 倍，告警 P2，可能是下游系统变慢或者资源不足；
• 注册中心路由表发生非预期变更，告警 P2，比如某个 Agent 实例下线没通知。

告警渠道我接的是钉钉和企业微信机器人。这里有个实用心得：告警消息里一定要带触达链路的 trace 查询链接，值班的人收到告警可以直接点开看链路，不用再自己去找日志入口。这个细节看着小，却能显著拉低 MTTR。

巡检 Agent 本身也要做成无状态的，最好跑在独立的容器里，不要跟业务 Agent 混部。否则业务 Agent 一崩，巡检 Agent 也跟着挂，你连"谁挂了"都看不清楚。

6. 避坑速查表与后续思路

6.1 高频踩坑速查表

我把实际操作里遇到的高频问题整理成一张速查表，方便你接入 Agent-Reach 时逐项自查。

这张表不是一次性列完的，是我在多个项目里迭代出来的。每次线上出问题，我都会往表里补一行，定期对照排查。你接自己的场景时，也建议建一张类似的历史坑表，后面会越用越顺手。

6.2 Agent-Reach 还能用在哪些地方

这套触达层设计的适用范围不止于多智能体系统。我用同样的思路改造过几个存量项目，效果都不错。

第一个是内部系统服务编排。公司里有订单系统、客服系统、仓库系统，彼此之间接口混乱。我把它们统一注册进 Agent-Reach，能力标签对应各自的业务接口，路由和熔断由触达层接管。系统之间不再互相硬调，而是通过触达层按能力名调用，改造后接口变更的影响面明显收窄。

第二个是 RPA 任务调度。RPA 机器人上一堆自动化脚本，哪个脚本负责什么流程、跑在哪个机器上，以前全靠人肉记录。用上注册机制后，每个 RPA 机器启动时上报自己的脚本清单和状态，调度器按能力标签精准下发任务，失败自动重试和切换机器。

第三个是客服工单智能分发。把工单系统的不同队列抽象成不同能力，一个"工单分发 Agent"根据上下文路由到正确队列。这在本质上就是把路由策略泛化——不路由到 Agent，而是路由到服务、到队列、到人。

我自己的体会是，Agent-Reach 的核心价值不在于它用了多少高大上的技术，而在于它把"Agent 之间怎么协作"这个常被忽略的问题，变成了一个有注册、有路由、有治理、有观测的工程问题。先把触达这条地基打牢，后面换模型、加 Agent、接新系统，都会轻松很多。如果你也在搞多智能体，建议别急着堆功能，先从一个真实场景的触达闭环跑起来，再逐步完善规范和治理。这一步走稳了，整个系统才能真正立住。