Agent-Reach：分布式智能体注册、发现与触达网关架构实践

做智能体平台的朋友，一定遇到过这种情况：智能体好不容易写好了一个，能回答问题、能调工具、能跑流程，但真要把它接到生产环境里，让别的服务能稳定找到它、叫得动它，反而比写智能体本身还费劲。我搞这个 Agent-Reach 项目，就是冲着这个问题去的——解决智能体在分布式环境下的注册、发现和触达问题。这篇文章把整个项目的设计思路、核心细节、实操过程中踩过的坑都整理出来，给准备做多智能体系统或者 Agent 编排平台的朋友一个参考。

1. 项目概述：Agent-Reach 到底解决什么问题

先说“Agent-Reach”这个名字。Reach 直译是“触达、可达”，放在这个项目里就是指“一个请求能不能准确、稳定地到达目标智能体手里”。Agent 是智能体，不是普通的微服务节点，它有自己的能力边界、运行方式和输出形式，所以触达它的方式也需要单独设计。

一个智能体系统做大的标志，就是“智能体数量多到需要被管理”。数量一多，问题就来了：几十上百个智能体，谁能调谁？谁健康谁挂了？请求来了该把任务发给哪个智能体？同一个能力的智能体部署了两个版本，流量怎么切？还有更现实的——智能体分布在不同集群、不同环境，甚至几家供应商的平台里，网络互通、地址变化是常态。没有一层处理这些事情，只能靠手写配置硬编码地址，一改环境就全线崩溃。

Agent-Reach 做的就是这一层：它把智能体当作一类特殊的服务节点管理，提供注册中心、健康检查、能力索引、触达网关和路由策略。说得直白一点，它就是智能体之间、外部系统和智能体之间的“调度中枢”，解决的核心问题就三个：知道谁存在、知道谁健康、知道怎么把请求送过去。

这个项目适合谁？如果你在做 AI Agent 平台、多智能体编排、智能客服或自动化流程系统，并且已经遇到了“智能体越来越多、调用关系很乱”的阶段，那这套设计思路应该能帮上忙。如果你只是写单个验证 Demo，那暂时用不上，但了解下这类架构也好，因为迟早会碰到。

1.1 智能体触达和传统服务发现的最大区别

有人会问，微服务时代早就解决服务发现问题了，Eureka、Nacos、Consul 都成熟得很，为什么还要专门搞一个给智能体用的？

区别在于路由的语义。传统微服务路由，核心要素是“接口路径”，比如调用/order/create，网关根据路径转发给订单服务。但智能体的世界里，你很少按固定接口调用，更多是描述你想干什么，让系统决定交给谁。比如“帮我把下个月所有合同整理成表格”或者“分析一下这批日志里有多少支付超时”，这类请求没有固定的 HTTP 路径，它匹配的是智能体的“能力描述”。Enhance 了语义层面的问题：传统注册中心不关心能力，只关心服务名和地址；Agent-Reach 关心的是“你当前这个 Agent 能不能做这件事”。

第二个区别是智能体的状态更不稳定。一个普通微服务无论内部逻辑多复杂，对外提供的接口是确定的，健康检查也稳定。但智能体可能依赖大模型 API，模型服务一抖动，智能体的响应质量、响应时间甚至是否存活都会受影响；而且很多智能体的运行是上下文相关的，同一个智能体在某个时间段可能正忙于处理长时间任务，此时就不适合再接新的请求。这些动态因素都得纳入调度决策里。

还有一个区别是触达方式多样。微服务之间调用基本是 HTTP/gRPC 同步一轮，但智能体可能一轮普通问答，可能触发一个需要几分钟甚至几小时的编排流程，也可能通过 WebSocket 或 SSE 源源不断推送流式输出。Agent-Reach 必须同时支持同步、异步、流式三种模式，并在路由时根据任务类型选择合理的触达通道。

2. 整体设计思路：为什么不能用老一套直接改

Agent-Reach 第一版之前，我把市面上的方案都过了一遍：直接上 Nacos 或 Consul，外面加一层网关行不行？服务网格是不是更彻底一些？基于消息队列做分发呢？逐个试下来后放弃了，原因挺具体。

拿 Nacos 这类注册中心来说，解决“地址拿得到”没问题，但它不解决“能力匹配”。要让它帮智能体做路由，就得在注册时把能力标签塞进 metadata，然后在网关侧自己写一堆匹配逻辑。越写越觉得是在造一个半成品注册中心+半成品路由引擎，还不如从模型上把智能体当作一等公民来设计。

API 网关也是候选方案，但它偏向“南北向流量”，也就是外部请求打到后台服务。而智能体之间大量的“东西向调用”，两个 Agent 协同完成任务，这种场景用网关转发不太顺手。服务网格更偏基础设施层，对老版本的 Spring Cloud 应用还好，但智能体大量跑在 Python 脚本、Node 服务、甚至临时函数计算里，Sidecar 模式对它们的接入成本太高了。

最终定的思路是：把 Agent 当作“能力节点”来建模。核心抽象不是服务名和端口，而是 AgentID 和 Capability。系统里有四个核心模块：

• Agent Registry（智能体注册表）：负责 Agent 的上下线登记，维护基础元数据，比如 AgentID、地址、能力标签、版本、租户归属。
• Capability Index（能力索引）：把每个 Agent 的能力描述解析成可检索的索引，路由请求时先在这里做语义匹配。相当于给每个 Agent 建了个“目录页”，查询时不用扫全表。
• Reachability Probe（可达性探测）：不只是被动收心跳，还主动发起探测请求，确认 Agent 在当前网络条件下真的可以被调用，并把探活结果反馈给路由器。
• Reach Gateway（触达网关）：统一入口，负责接收调用请求，完成路由决策、安全校验、协议转换，然后把请求真正送到目标 Agent，并把结果或数据流回给调用方。

这四个模块配合起来，就是 Agent-Reach 的整体闭环：Agent 启动后先注册，注册后持续上报心跳，同时网关侧持续探测；来请求时先做能力匹配，过滤掉不健康或不可达的节点，再按路由策略选出一个目标节点，最后经网关触达。

2.1 为什么不把 Agent 当作普通服务节点注册

设计注册表结构时，我一开始也走了弯路。最开始图省事，直接把 Agent 当普通微服务节点注册，字段就是服务名、IP、端口、权重。结果上线不到一周就发现问题：注册信息过于稀疏，路由器根本没法做决策。

举个例子。两个 Agent 都注册了“合同审核”这个能力，但一个只支持中文合同、一个支持中英双语；一个输入接受 PDF、一个只接受纯文本。如果不描述这些差异，路由到哪个都行，结果任务分给不合适的智能体，处理失败再重试，效率很低。

Agent 的注册信息至少要包括这几类：身份信息（AgentID、版本、租户）、能力声明（能力名称、输入输出格式、支持的模型列表、语种范围）、运行信息（服务地址、协议类型、当前负载、状态）、约束条件（是否只接受特定来源的请求、是否有使用配额）。这些信息一起进入注册表，路由时不只是看“谁能干”，还要看“谁适合干”和“谁现在能干”。

这也是 Agent-Reach 跟普通注册中心在数据模型层面最本质的区别。普通注册中心的 metadata 是辅助信息，在 Agent-Reach 里，能力声明是核心信息，少了它路由就无法启动。

3. 核心细节解析与实操要点

接下来进入硬核部分。Agent-Reach 的注册、健康检查、路由和触达每个环节都有不少细节，光看架构图是看不出来的。

3.1 注册数据模型设计：Agent 到底需要上报什么

注册是第一步，但如果设计得不好，后续所有环节都会出问题。Agent-Reach 的注册数据模型采用 JSON 结构，核心字段如下：

{ "agent_id": "agent-contract-checker-v3", "version": "3.2.1", "tenant_id": "t-1001", "capabilities": [ { "name": "contract_review", "input_formats": ["pdf", "docx", "text"], "languages": ["zh", "en"], "max_input_size_mb": 50, "options": { "need_signature_check": true } } ], "endpoints": { "sync": "https://agent-cluster-a.internal/contract-checker/v3", "stream": "wss://agent-cluster-a.internal/contract-checker/v3/stream" }, "protocols": ["h2c", "wss", "sse"], "load_metrics": { "running_tasks": 3, "queue_length": 5 }, "constraints": { "allow_callers": ["platform-orchestrator", "legal-affairs"], "max_concurrent_tasks": 10 } }

注册表核心设计原则有三个：

AgentID 必须是全局唯一且语义稳定。我见过很多系统把 AgentID 生成为随机 UUID，上线后运维想改都得查半天，更别提路由后日志追踪。AgentID 建议包含业务领域和版本信息，比如agent-contract-checker-v3，既能识别身份，又能一眼看出是干什么的。如果同一个智能体更新版本，不要换 ID，而是用 version 字段区分，旧版本还能保留一段时间做灰度切换。

能力描述要结构化，不能只靠自然语言。有的项目图省事，让开发者填一段自然语言“我能做什么”，然后注册中心纯靠文本匹配路由。这在小规模场景下还能凑合，规模一上来就完蛋：同义词、模糊语义的问题全来了。Agent-Reach 的做法是要求声明结构化能力和可选参数，即使有自然语言描述，也只作为辅助信息展示，不做路由依据。

endpoints 要按触发模式分类型。同步请求、流式请求、事件回调，是三种不同的触达通道。一个 Agent 可能支持其中两种或都支持，注册时必须分别声明。否则路由器只知道“这个 Agent 地址是什么”，不知道“这个请求该走哪个地址”，只能默认走同步，流式任务全都会被错误路由。

注意：注册信息不是一次性完整即可。负载指标、状态这类动态信息变化频繁，不能每次全量上报把注册中心写爆。Agent 端应该把静态信息（能力、端点、约束）和动态信息（负载、状态）分开上报。Agent-Reach 在实现上，静态信息走注册接口，动态信息走单独的健康上报通道，这也是为什么健康检查模块不能省。

3.2 健康检查策略：为什么心跳和主动探测必须共存

初期做健康检查，我也想过只用心跳机制。Agent 每隔 5 秒上报一次“我还活着”，注册表根据最近一次心跳时间判断节点是否健康。这套逻辑简单，但实际运行中发现两个致命问题。

第一个问题：心跳正常不代表真正可调。有个 Agent 部署在容器里，进程没挂，心跳一直在发，但它的数据库连接池满了，任何业务请求进来都直接超时。心跳只能证明“进程在”，证明不了“任务能处理”。针对这个场景，Agent-Reach 引入了主动探测机制。网关会定期向 Agent 发送一个轻量级的探活请求，这个请求会真实地走一遍 Agent 的请求处理器，但只执行最小化逻辑，比如检查依赖的数据库、外部服务是否可用，然后快速返回。一旦探活请求超时或失败，这个 Agent 会被标记为不健康，暂时不参与路由，直到探活恢复为止。

第二个问题：不同 Agent 的健康标准不一样。依赖大模型 API 的智能体，模型服务抖动时它可能自己都半死状态。Agent-Reach 允许在注册时声明自定义健康检查参数，比如探活路径、期望响应时间、健康阈值等。默认的探活规则是 3 次连续失败才摘除节点，但如果某个 Agent 服务要求高，可以调成 2 次；有些非核心 Agent 响应慢，可以放宽阈值，避免频繁被断开。

健康检查的结果会实时同步到路由决策里，形成一个最终一致的状态视图。注意这里用的是“最终一致”而不是“强一致”，因为 Agent 状态变化太快，追求强一致会牺牲配合，得不偿失。状态消息通过异步事件总线传播，路由节点接受的最大状态延迟是 500ms，这个范围内允许路由到刚刚不健康的 Agent，系统会通过重试机制兜底。

3.3 路由策略：能力匹配只是第一步，选人不选人门道很多

路由决策分两个阶段：先做能力匹配，再做节点选择。能力匹配阶段把请求中描述的“要做什么”和注册表里的能力索引比对，筛掉能力不匹配的节点。这一步看似简单，但“做了部分匹配”和“能做”完全是两个概念。Task 需要读取 PDF，Agent 只支持 DOCX，就算能力名称匹配也必须排除。所以 Agent-Reach 的能力匹配不是简单的标签相交，而是把输入格式、语言、校验选项全部纳入比对。

能力匹配完成后，如果候选节点还有多个，就进入节点选择阶段。我最初只用了最简单的加权轮询，后来发现不够，快速加了几种策略：

策略配置放在路由规则里，请求动态设置。比如一个合同审核任务，系统可以配置“优先选择租户亲和且当前负载最小的节点”：

route_rules: - name: contract_review_route priority: 10 match: capability: contract_review tenant_id: t-1001 select: strategy: least_connection filters: - require_healthy: true - require_reachable: true fallback: strategy: weighted_round_robin weight_by: agent_version_preference

这套路由策略的设计有个原则：任何选择策略都必须有 fallback。现实情况下，你可能指定了某个 Agent 版本，但它已经下线了；或者一致性哈希命中的节点刚好不健康。如果没有 fallback，整个请求直接失败。Agent-Reach 里 fallback 默认启用，策略是先尝试同能力同租户的其他节点，再拓展到同能力所有节点，最后返回明确的无可用节点错误。

3.4 触达协议与网关实现：支持多种产出形态

路由决策做完了，最后一步是把请求真正送过去。Agent 这个特殊之处，在触达阶段体现得最明显。硬编码只支持 HTTP 同步调用的网关，在遇到流式输出的 Agent 时会直接卡死。

Agent-Reach 的触达网关设计了三种通道适配器：

• 同步模式：标准的 HTTP 请求，请求发出后阻塞等待 Agent 返回完整响应。适合一次问答、短流程任务。底层实现时要特别注意客户端连接超时时间，不能设成固定值，因为 Agent 处理时间差异巨大，3 秒能回的接口和 20 秒才能回的接口可能需要不同的超时配置。
• 流式模式：基于 SSE 或者 WebSocket，请求发出后持续接收数据流，一边收一边转发给调用方。适合大模型生成式的输出场景，用户要求一个字一个字蹦出来才有体验。
• 异步模式：请求发出后立刻返回一个 task_id，Agent 处理完把结果回调到指定地址。适合长耗时流程，比如整个月合同报表的生成，可能要跑几分钟。

三种模式在注册数据模型里都映射到了对应的 endpoints 字段。网关侧根据请求中声明的 mode 参数选择适配器、校验目标 Agent 是否支持该模式，不支持就提前报错，而不是发出去等超时。这一个细节帮我们避免了不少可以预见的线上事故。

另一个网关侧的关键点是协议转换。调用方可能用的是 HTTP 接口，但目标 Agent 内部走的是 gRPC；或者调用方期待 JSON 返回，Agent 返回的是 XML。Agent-Reach 网关内置一层轻量转换器，通过配置把入站消息转成目标 Agent 期望的格式。这听起来像一个简单功能，但实际做的时候能感觉到——协议适配越灵活，Agent 接入就越省心。

3.5 安全语义：不是所有系统都能调用所有智能体

最后一块核心细节是安全控制。智能体不是公共资源，尤其在企业环境里，合同审核这种智能体和数据脱敏这种智能体，不能随便让任何服务调用。Agent-Reach 把安全控制做实到了租户 + 调用方 + 智能体能力的三元授权限定。

每一次网关转发，都会校验三件事：调用方是否有权访问这个租户空间、是否在 Agent 的 allow_callers 列表里、是否对用到的能力有授权。没有三元校验之前，我们吃过亏——有一个部署在测试环境的智能体因为没加任何访问控制，被一个内部巡检任务误调用，生成了几百条垃圾数据。从那以后，新接入的 Agent 默认安全配置是最小权限，只有显式放开调用方，才算真正开放调用。

凭证管理上，Agent-Reach 为每个 Agent 生成独立的调用凭证，凭证可以定时轮换。Agent 侧为了防止凭证泄露，支持双向 TLS 认证，网关和 Agent 各持证书，安全性比较可靠。配了证书之后，探活探测也会走加密通道，避免探活请求加密强度不足导致 Agent 状态被伪造或篡改。

4. 实操过程与核心环节实现

理论部分讲得够多了，直接上手看 Agent-Reach 是怎么部署和使用的。我用自己的两个智能体做一次完整演示：一个是合同检查智能体，另一个是发票验真智能体。

4.1 演示环境准备

Agent-Reach 由三部分组成：控制面（含注册表和路由规则管理）、触达网关、状态存储。控制面是无状态多副本的，状态放在 PostgreSQL 和 Redis 里，部署使用 Docker Compose 串起整个环境：

services: agent-reach-control: image: agentreach/control:latest ports: - "8080:8080" environment: DB_DSN: postgres://ar:ar@postgres:5432/agentreach REDIS_ADDR: redis:6379 agent-reach-gateway: image: agentreach/gateway:latest ports: - "9090:9090" - "9091:9091" environment: CONTROL_ADDR: agent-reach-control:8080 postgres: image: postgres:16 environment: POSTGRES_USER: ar POSTGRES_PASSWORD: ar POSTGRES_DB: agentreach redis: image: redis:7

这里注意，网关是整个流量的入口，如果生产环境有多个可用区，网关最好在多可用区部署，避免单点故障。状态存储虽然中心化了，但控制面本身无状态，可以通过负载均衡水平扩展，性能瓶颈一般不会出现在这里。

4.2 接入一个智能体：注册能力和配置路由

接入智能体的完整生命周期是注册 -> 配置路由 -> 验证通路。以一个合同检查智能体为例，先通过控制面接口注册：

curl -X POST http://localhost:8080/v1/agents/register \ -H "Content-Type: application/json" \ -d '{ "agent_id": "agent-contract-checker-v3", "version": "3.2.1", "tenant_id": "t-1001", "capabilities": [ {"name": "contract_review", "input_formats": ["pdf", "docx", "text"], "languages": ["zh", "en"]} ], "endpoints": { "sync": "http://localhost:9001/review", "stream": "ws://localhost:9001/stream" }, "protocols": ["http", "ws"], "constraints": { "allow_callers": ["legal-affairs"], "max_concurrent_tasks": 5 } }'

注册成功后，控制面会返回agent_key，这是调用该 Agent 时的凭证，相当于它的专属令牌。这一步要注意，返回的凭证只显示一次，丢掉后只能重新生成，重新生成会导致旧凭证失效，所以记得放在安全的地方。

注册完成后配置路由规则。沿用上面的 YAML，这里把strategy设置为least_connection，并开启 fallback。配置的方式是向控制面提交规则，控制面在做校验之后推送给所有网关节点。网关节点拿到规则后，不需要重新加载配置，路由逻辑会即时生效。

最后验证通路，通过网关发起一个实际请求：

curl -X POST http://localhost:9090/v1/reach \ -H "Content-Type: application/json" \ -H "X-Agent-Reach-Key: {agent_key}" \ -d '{ "mode": "sync", "capability": "contract_review", "payload": { "document": "base64_encoded_pdf", "options": {"check_signature": true} } }'

这个请求的流程是：网关校验凭证 -> 能力匹配池子 -> 健康过滤 -> 最少连接数选择 -> 转发给合同检查智能体 -> 拿回结果返回给调用方。整个链路在演示环境有一次完整的日志可以观察，网关会记录一个reach_id，后续排查问题都靠这个 ID 串联日志。

4.3 流式模式配置与测试

再演示一下流式任务的配置。流式请求与同步请求不同，网关需要保持长连接，持续转发数据流。我顺手把刚才那个 Agent 的stream端点也演示一次：

curl -N -X POST http://localhost:9090/v1/reach \ -H "Content-Type: application/json" \ -H "X-Agent-Reach-Key: {agent_key}" \ -d '{ "mode": "stream", "capability": "contract_review", "payload": {"document": "base64_encoded_docx"} }'

网关识别到mode: stream后，不会等待 Agent 返回完整响应，而是立刻建立到目标 Agent WebSocket 端点的连接，后续 Agent 输出的每个流式块直接透传给调用方。拿到第一块就推给客户，客户能明显感觉到响应更快，这在对接大模型类的智能体时尤其重要。

这里有个我之前踩过的坑：流式模式下网关的缓冲区设置。缓冲区太小，高频小块数据推送时性能极差；缓冲区太大，Reach 的第一块数据迟迟不返回，体验退化。最终把默认块大小设为 4KB，对于大多数文本生成场景比较均衡。如果输出的是泛化渲染的富文本，块大小要相应调大。

4.4 接入过程中的一次真实踩坑记录

注册过程中出现过一起比较典型的问题。某个智能体注册成功，但流量一进来就报错，查看详细日志发现 Agent 返回的是 401。排查后发现原因在于 Agent 强制开启了双向 TLS，但注册时没有上报证书指纹，网关端没有同步证书信息，双方握不上手。

这个问题提醒了一点：接入流程要当成一个完整的握手过程，而不是单向控制面单方面定规格。所以在实际项目推进中，Agent 接入文档里都会包含证书交换、凭证生成、探活联调三个环节，少了任何一环，系统可能都不会按预期工作。

5. 常见问题与排查技巧实录

项目上线后，我整理过一个 Agent-Reach 相关的常见问题排查备忘，挑几个最典型的分享下。

5.1 Agent 注册成功但路由不生效

这类问题出现的概率非常高。注册成功，控制面也能查到节点，但请求就是不往这个 Agent 上走。排查方向不是看注册是否成功，而是看路由规则里是否真的命中了这个 Agent。

常见原因是路由规则里的capability名称和注册时声明的名称不一致。比如注册填了contract_review，规则里填了contract-review，一字之差匹配不上。另一个原因是租户不一致——注册时tenant_id填t-1001，请求的调用方凭证关联的租户是t-1002，租户被过滤掉，节点自然不可见。

排查技巧：用控制面提供的试路由接口模拟一次请求，看路由决策日志，里面会详细输出每个匹配环节的过滤原因。比起看调用日志翻来翻去，这个方法定位问题最直接。

5.2 Agent 显示健康但请求超时

健康检查全部通过，路由也选择了这个节点，但请求就是超时。这种问题最令人抓狂，因为状态面板看起来一切正常。

根据实际经验，最常见的原因是探活接口和真实业务接口的处理能力不对称。有些 Agent 开发者为了通过探活，把探活逻辑写得很轻，不检查依赖服务，只返回 OK。探活自然通过，但真实业务请求一来，要等数据库、要等模型 API，一排队就超时。

解决思路有两个：一是优化 Agent 自己的探活逻辑，让它真实检查下游依赖；二是在网关侧调整请求超时策略——对同步问题，不再一刀切固定 5 秒，而是参考 Agent 注册时申报的“期望处理时长”，超时上限为该值的 2 到 3 倍。这个改动上线后，误超时投诉少了很多。

5.3 智能体间歇性失联

本来一直好好的，某段时间开始 Agent 时不时被标记不健康，过一会又自动恢复。这种“抽风式失联”排查起来比较麻烦，因为问题可能不在 Agent 自身，而在网络链路或者部署环境。

从实际发生的场景看，最常见的是容器环境资源限制。Agent 所在容器 CPU 配额设得太低，高负载时进程没死，但心跳上报、探活响应的响应时间被拖长，网关判定超时，临时摘除。负载过去后又恢复，看起来就是间歇性失联。观察指标重点看从网关到 Agent 的“探活响应时延”曲线，如果响应时延和 CPU 利用率同步飙升，基本能确认是资源瓶颈。

还有一种情况是 Agent 内部存在长时间阻塞的操作，比如同步等待某个外部 API，导致事件循环阻塞，心跳发送线程也被卡住。运行逻辑是否正常不好说，但至少说明 Agent 本身需要优化内部并发模型。

5.4 跨环境跨集群的地址不可达

这是多环境部署时绕不开的问题。Agent 注册时上报的地址，在另一个集群里根本访问不通。最典型的是 Agent 上报了内网 IP，调用方在另外一个专有网络里，如果流量直接打到 Agent 地址，必然失败。

这里的关键是：到达 Agent 的路径不应该由调用方直接拼地址，而是应该统一走 Gateway 转发。Agent-Reach 的推荐做法是，Agent 上报的 endpoint 注册为网关代理地址，请求先到了网关，由网关去访问实际的 Agent 地址。生产环境里，网关和智能体部署在同一个网络域内，跨网的问题都收敛到网关这一层解决，Agent 不用关心外部集群的网络策略。

经验之谈：面对跨网络问题，千万不要试图把每个 Agent 的地址暴露到所有环境。把“访问 Agent 的路径”收口到网关，是唯一值得长期坚持的方案。这样做网络策略维护量最小，排查链路也清晰，配置安全策略时只需要处理网关一个入口。

5.5 只想调用“某个版本”的智能体怎么办

灰度发布是智能体上线无法回避的场景。新版本 Agent 上线，不能直接全量切换，需要先把一小部分流量导过去，验证没问题再扩大。

Agent-Reach 的路由规则里，weight_by: agent_version_preference就是干这个的。配置旧版本权重 90、新版本权重 10，持续观察新版本的调用成功率、平均响应时延、错误率，一切正常再把权重逐步调整到 100。

这个灰度过程非常依赖可观测性。每条经过网关的请求都自动带上reach_id，调用日志里可以查到落到了哪个版本的 Agent。切勿在 net 侧就把“版本是否健康，应该调度多少比例”这种动态决策写死，要保持规则引擎的灵活性。适应新版本异常回滚的场景，可以通过控制面一键把新版权重降到 0，比直接在 Agent 端改配置快得多。

5.6 调用凭证过期导致大面积失败

凭证轮换是安全机制的必选项，但轮换设计不好反而会引起事故。有一次我们把某个 Agent 的调用凭证设置为 24 小时过期，结果第二天同一时间整条链路的调用全部失败——原因是一个内部调度任务用的凭证缓存没有刷新，凭证过期后缓存里还是旧值。

排查到根因后，调整了轮换策略：凭证有效期从 24 小时延长到 7 天，同时将“凭证轮换”和“Agent 上线发布”绑定，随版本发布一起更新，避免在无感知的情况下凭证突然失效。如果确实需要频繁轮换，调用方必须实现凭证自动刷新逻辑，不能依赖人工改配置。而且控制面在凭证即将过期前，应该提前发告警，让运维有足够缓冲时间。

写在最后

Agent-Reach 从立项到现在跑通生产环境，我最深的体会是：技术方案的选择，不要照搬服务发现的老套路，要顺着智能体的特性重新思考。智能体不是“加了 AI 的微服务”，它的状态、能力、输出形式都跟传统服务不一样，用传统思路硬套，最后一定会在某个细节上磕得很难受。

如果现在让我给后来者提建议，就一条：先把注册表和能力索引设计好，再谈路由策略和网关。能力描述字段的颗粒度要对齐业务需求，太粗导致路由不准，太细又增加接入负担。数据模型一旦定型，后面调整的成本会直线上升。另外再补一句，像凭证过期、探活逻辑失真这类问题，设计规范阶段多花点心思，比事后打补丁省心太多。

这个项目目前已经支持了上百个智能体的注册和调度，后面我还打算把 Agent 的语义检索做深一点，让路由真正支持自然语言请求直接匹配能力描述，而不只是结构化标签查询。这套架构的边界，其实还远没有挖到头。