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 需要读取 PDFAgent 只支持 DOCX就算能力名称匹配也必须排除。所以 Agent-Reach 的能力匹配不是简单的标签相交而是把输入格式、语言、校验选项全部纳入比对。能力匹配完成后如果候选节点还有多个就进入节点选择阶段。我最初只用了最简单的加权轮询后来发现不够快速加了几种策略策略适用场景关键参数加权轮询集群能力对等负载均衡分配weight一致性哈希需要相同请求落到相同 Agent比如会话保持hash_key用户ID/会话ID最少连接数任务耗时差异大防止某个 Agent 积压running_tasks、queue_length亲和路由特定租户或来源请求固定走特定集群满足数据合规tenant 匹配规则策略配置放在路由规则里请求动态设置。比如一个合同审核任务系统可以配置“优先选择租户亲和且当前负载最小的节点”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_idAgent 处理完把结果回调到指定地址。适合长耗时流程比如整个月合同报表的生成可能要跑几分钟。三种模式在注册数据模型里都映射到了对应的 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:arpostgres: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 的语义检索做深一点让路由真正支持自然语言请求直接匹配能力描述而不只是结构化标签查询。这套架构的边界其实还远没有挖到头。