1. 项目概述与核心问题
1.1 从"Agent能做什么"到"Agent怎么被找到"
"Agent-Reach"这个名字乍一看有点抽象，但如果拆开理解就很直白：Agent代表智能体，Reach代表触达、覆盖、到达。合起来，它解决的问题是——在一个多智能体系统里，一个Agent如何稳定、高效、可观测地触达另一个Agent，以及一个业务系统如何触达它需要的Agent能力。
过去两年我一直在做AI Agent相关的基础设施，最大的感受是：单个Agent做得再聪明，也只是一个孤岛。现在很多团队的情况是，今天上线一个客服Agent，明天上线一个数据分析Agent，后天又加一个工单分类Agent。每个Agent都是独立服务，都有自己的调用协议、鉴权方式、限流策略，甚至部署在不同的环境和集群里。一开始Agent少，靠人肉记忆接口文档还凑合；一旦超过三五个，整个系统就变成一团乱麻。调用方不知道应该找谁，Agent之间没法互相协作，新增一个Agent要改一堆调用方代码，出了问题也不知道是哪个环节断了。
Agent-Reach就是冲着这个痛点来的。它定位是一个"智能体触达层"，或者说"Agent网络的中枢神经系统"：所有Agent都接入Agent-Reach，由它统一负责注册、发现、路由、调用、观测和治理。调用方不需要知道目标Agent部署在哪里、用什么技术栈、接口长什么样，只需要向Agent-Reach表达"我要什么能力"，剩下的交给触达层去解决。
这个项目适合谁看？如果你正在做多Agent系统、Agent平台基建，或者公司内部有多个Agent服务需要统一管理和调度，那这篇文章里的设计思路和踩坑记录应该能帮你少走不少弯路。即便你只是刚开始接触Agent开发，理解"触达"这个环节的设计逻辑，也能帮你更清楚Agent系统在真实生产环境里到底是怎么运转的。
1.2 Agent-Reach解决的核心痛点
我把Agent-Reach要解决的核心问题归纳成四类，这也是做Agent基建必须想清楚的四件事。
第一是发现难。Agent是动态的，今天有10个实例在跑，明天可能缩到3个，后天又新发一版。传统DNS加负载均衡的方式对普通服务够用，但Agent需要暴露的是"能力"而不是"端口"。调用方关心的是"有没有一个能做意图识别的Agent"，而不是"哪个IP的8080端口在监听"。Agent-Reach引入能力注册中心，Agent上线时登记自己能做什么、支持什么协议、容量多大，调用方按能力名去发现，而不是按地址去连接。
第二是调用乱。不同Agent可能由不同团队开发，有人用REST、有人走gRPC、有人只暴露消息队列接口、还有人需要WebSocket长连接才能交互。如果让调用方同时兼容所有这些协议，基本是灾难。但统一协议又不能太重型，否则Agent接入成本太高。Agent-Reach的做法是定义一个轻量的"智能体调用协议"，统一封装成JSON-RPC风格的请求-响应模型，底层协议差异由SDK屏蔽掉。
第三是治理缺。Agent是有生命周期的，有上线就有下线，有健康就有异常，有稳定就有抖动。没有治理机制的话，一个Agent卡死了，调用方只能等超时；一个Agent被流量打爆了，其他Agent还不知道绕开它。Agent-Reach把健康检查、熔断、限流、灰度这些治理能力做进触达层，让调用方不需要自己实现这些逻辑。
第四是观测弱。多Agent调用链的排障比普通微服务更复杂，因为Agent内部还有模型推理这一层，一次调用可能几秒甚至几十秒，中间还涉及工具调用和上下文传递。Agent-Reach在触达层统一埋点，记录每一次调用的发起方、目标能力、路由路径、耗时、Token消耗和最终结果，形成完整的调用链路数据。没有这套数据，出了问题只能靠猜。
一句话总结：Agent-Reach不解决"Agent怎么变得更聪明"，它解决的是"Agent怎么被稳定地触达和协作"。
2. 整体架构与关键设计决策
2.1 三层Hook架构：接入层、注册中心、路由与执行层
Agent-Reach整体上分为三个层次，每一层的职责边界非常清晰。
接入层是Agent接入Agent-Reach的方式。我们提供官方SDK，目前支持Python和Go两个语言版本。SDK的核心作用有四个：启动时向注册中心登记能力、周期性地发送心跳和上报健康状态、接收路由层的调用请求并执行、把执行结果返回给触达层。接入层的设计原则是"最小侵入"，Agent业务代码只需要在初始化时调用一次SDK的注册方法，然后在合适的位置加上一行装饰器或者拦截器标记触达入口，剩下的逻辑SDK全部接管。实测下来，一个普通的FastAPI服务接入Agent-Reach，代码改动量控制在30行以内。
注册中心是整个系统的大脑，保存所有Agent的元数据。每个Agent注册时需要声明三样东西：能力标识符（比如intent.detect、data.analyze）、调用协议类型（REST、gRPC、MQ等）、以及扩展属性（地域、可用区、模型名称、速率限制参数等）。注册中心负责维护这些元数据的一致性，并实时计算所有Agent的"可达状态"——只有心跳正常并且通过健康检查的Agent实例才会被纳入可用路由池。这里有个非常容易踩的坑：Agent的数量和状态是高频变动的，如果注册中心直接依赖MySQL来存取状态，并发一高就会锁表。我们最终采用内存存储加WAL日志落盘的方案，注册信息变更先写日志再更新内存状态，读写性能不在一个量级。
路由与执行层是触达的核心路径。调用方发起请求后，先到路由层做目标决策：根据能力标识符找到可用Agent集合，再结合路由策略选出一个或多个目标实例，最终把请求转发过去。执行层负责全链路的超时控制、重试、熔断和协议转换。这个层次最考验工程细节，因为Agent调用的耗时分布极不均匀。普通HTTP接口的P99可能也就几十毫秒，但一个带模型推理的Agent调用，P99可能到几十秒，甚至因为模型排队还会出现分钟级的响应。用传统的"三秒超时自动重试"策略去调Agent，系统必炸。针对这个问题，我们把超时控制做成了多级可配置——连接超时、首包超时、全链路超时三个维度独立设定，并且重试策略默认关闭，只有明确配置了幂等标记的调用才允许自动重试。
2.2 为什么不能只做一套"API网关"？
在做Agent-Reach的过程中，被问得最多的一个问题是：这不就是个API网关吗？Kong、APISIX、Traefik不都能做路由和治理吗？
我承认，从功能表象上看，Agent-Reach确实和API网关有大量重叠，但核心差异在"路由维度"上。传统API网关路由的是路径，比如/api/v1/orders对应订单服务。Agent-Reach路由的是能力，调用方发出的是"我要识别这段文本的意图"，而不是"我要请求哪个接口"。
这个差异带来三个非常实际的设计区别。
第一是发现机制不同。API网关的路由配置是相对静态的，新增一个服务需要手动配一条转发规则。Agent-Reach的注册中心允许Agent动态上下线，Agent发布新版本时自动注册新能力，下线时自动移除，不需要人工维护路由表。这个动态性是多Agent系统的基础要求，因为Agent的能力经常会随着模型迭代或提示词调整而更新。
第二是调用语义不同。API网关转发的是完整的HTTP请求，语义信息包含在URL和Header里。Agent-Reach定义了统一的调用负载，核心是一个capability字段加一个payload字段——前者指名要调用的能力，后者放语义化的输入参数。这样做的好处是，路由层可以基于capability做精细的意图匹配，而调用方不需要关心目标Agent的接口结构。
第三是上下文传递机制不同。多Agent协作时，一个用户的请求可能会在多个Agent之间流转，比如先经过意图识别Agent，再进入业务处理Agent，最后经数据查询Agent返回结果。在这个过程中，会话ID、用户ID、链路追踪ID、Token预算等信息必须全程携带。API网关的Header传递方式太松散，Agent-Reach在调用协议层面把上下文对象做成了显式字段，每次触达都自动透传完整上下文。
2.3 统一的智能体触达协议：以MCP为参考的简化描述
在设计调用协议时，我们参考了MCP（Model Context Protocol）的思路，但没有照搬，因为MCP对很多场景来说太重量级了。
MCP做的事情是把模型上下文获取标准化，让应用通过一个统一的协议去访问工具、数据源和上下文资源。这在Agent和外部工具之间建立了一个很好的标准。但对于Agent与Agent之间的内部触达，我们更需要的是一个轻量、快速、可扩展的协议，所以Agent-Reach定义了自己的"智能体触达协议"（Agent Touch Protocol，简称ATP）。
ATP使用JSON-RPC风格的封装，一次完整的调用分为三帧：
- 请求帧：包含
request_id、capability、payload、context（上下文）、timeout_hint（超时预期）。 - 响应帧：包含
request_id、status（success/error/busy）、result、context_update（上下文增量更新）。 - 错误帧：包含
request_id、error_code、error_message、can_retry（是否允许重试）。
选择JSON-RPC风格而不是纯REST，是因为多Agent调用的语义更接近函数调用，而不是资源操作。调用方就是想"做一件事"，用动词化的capability表达比用URL表达更自然。
协议确定后，我们做了一轮面向内部Agent开发者的可用性测试。结论是：对直接用SDK的开发者来说，感知到的只是SDK内部的一个方法调用，协议细节基本透明；对需要走裸协议接入的Agent（比如用C++写的性能敏感型Agent），配合协议文档也能在半天内完成接入。这个复杂度控制符合预期。
3. 核心机制解析与关键实现
3.1 智能体注册与心跳维护
注册机制是整个触达系统的地基，注册做不好，后面全是空中楼阁。
Agent启动时，SDK会读取本地配置文件，拿到Agent-Reach的注册中心地址和自身的能力标识符列表，然后发送注册请求。注册请求里包含的信息比一般服务注册要多：
{ "agent_id": "agent-intent-v3-7f3a", "capabilities": [ { "name": "intent.detect", "version": "3.2", "protocol": "rest", "endpoint": "/internal/intent", "timeout_sla_ms": 5000, "max_payload_bytes": 1048576 } ], "metadata": { "zone": "cn-east-1", "model": "qwen-plus-v2", "max_qps": 200, "semver": "3.2.1" } }注册成功后，SDK启动心跳协程，默认每3秒上报一次心跳，心跳包里带有Agent当前的负载状态（正在处理的请求数）、最近一次健康检查结果和累计调用指标。注册中心会根据心跳的到达情况维护一个"最后心跳时间"，一旦超过阈值（默认10秒）就认为该实例失联，将其从可用池中摘除，同时触发告警。
这个设计里最需要盯紧的是误摘除问题。一次GC停顿、一次网络抖动、甚至机器被重启了一下，都可能让心跳超时。Agent实例被摘除本身不是大问题，问题在于摘除引起流量抖动，进而导致其他实例被压垮，形成雪崩。我们的解决方案是"心跳超时只降权不移除"：失联实例仍然被保留在候选池里，但优先级被降到最低，必须连续三次健康检查失败才会真正摘除。这样既避免了雪崩，又保证了容错性。
3.2 可达性探测与触达率计算
Agent-Reach这个名字里的"Reach"直接对应的就是我们定义的触达率指标。这个指标用来衡量一个Agent能力在给定时间段内被成功调用的比例，公式是：
触达率 =（成功完成的调用次数 + 可降级的调用次数）/ 总调用次数 × 100%
这里"可降级"指的是虽然有部分实例异常，但通过路由策略找到替代实例并成功完成调用的场景。比如主实例group-A超时了，路由层自动切换到group-B，最终调用成功，这笔请求计为可降级调用，不计入故障。
为什么要单独定义"可降级"？因为直接算成功率会把所有异常都归到Agent头上，但实际上很多失败的请求通过降级或者重试是可以救回来的。触达率这个指标衡量的是"系统整体触达目标能力的能力"，而不是"单个Agent实例的健康度"。在监控面板上，我们同时展示三个数字：原始成功率、触达率、实例健康率，三者对比就能快速判断问题的性质——是Agent本身坏了，还是路由层没做好兜底。
每个周期（默认1分钟），注册中心会基于所有调用日志计算每个能力维度的触达率，低于98%时自动触发告警。刚开始跑的时候这个阈值经常误报，因为很多Agent的P99耗时就接近调用方设置的超时时间，稍微抖动一下就会超时。后来我们加了一个缓冲机制：只有连续两个周期触达率都低于阈值，并且失败样本量超过固定下限（比如50次），才会真正告警，误报率大幅下降。
3.3 路由策略：意图路由与精准路由
路由层是Agent-Reach里逻辑最重的部分。它采用了"两级路由"方案。
第一级是意图路由：调用方只声明需要什么能力，不指定具体实例，由路由层基于能力标识符匹配候选Agent列表。匹配规则支持精确匹配和语义匹配两种模式。精确匹配就是capability名字完全相同，简单粗暴但适用性足够；语义匹配则用一层轻量的Embedding模型计算请求意图和Agent能力描述的向量相似度，适合"调用方描述不精确、Agent能力边界模糊"的场景。实测下来，语义匹配适合内部探索阶段使用，生产环境还是建议精确匹配，因为语义匹配偶尔会选错Agent，排查起来比较费劲。
第二级是精准路由：在候选Agent列表确定后，根据策略从候选集中选出具体实例。目前实现了三种策略。
- 最少负载优先：优先选择当前在处理请求数最少的实例，适合服务型Agent。
- 一致性哈希：对
request_id或session_id做哈希，保证同一个会话的请求固定打到同一个实例，适合有状态Agent。 - 亲和路由：结合request上下文中的地域、团队、业务线等信息做路由，比如要求"必须路由到cn-east-1的实例"。
实际项目里，最少负载和亲和路由用得最多，一致性哈希只在个别有状态场景下启用。一个更值得注意的点是，路由策略应该是可插拔的，因为不同Agent差异太大——一个短视频审核Agent和一个人工智能客服Agent，对路由策略的要求完全不同。Agent注册时可以在metadata里声明routing_policy偏好，不声明则用全局默认策略。
3.4 调用安全与权限控制
Agent触达层的安全，和普通API网关的安全有相似之处，也有Agent特有的问题。
基础层面，Agent-Reach支持API Key和OAuth2两种鉴权方式。每个调用方在管理后台申请自己的client_id和client_secret，绑定可访问的能力列表。授权粒度做到"调用方到能力"这一级，不允许一个Key通配所有Agent。这块不建议图省事做弱化处理，因为多Agent系统里不同Agent的数据等级差异很大，一个查天气的Agent和一个查用户订单的Agent，绝不能共享同一把钥匙。
Agent特有的一层安全控制叫能力授权校验。Agent在注册时可以声明每个能力需要的信任等级，比如"仅允许内部系统调用"或"允许经用户授权的外部应用调用"。路由层在做转发之前，会检查调用方凭证携带的信任等级是否满足目标能力的要求。这个机制解决的是"Agent被其他Agent恶意或误调用"的问题——在多Agent协作场景里，一个Agent不自觉地调用另一个Agent的敏感能力，是真实存在的风险。
另外，所有的调用日志都要求记录调用方身份、目标能力、调用的payload摘要和时间戳，这样做不是为了监控员工，而是为了在出现安全事件时有完整的溯源链路。Agent间调用产生的数据流，特别是在处理用户隐私相关任务时，必须能说清楚"数据从哪个Agent流到了哪个Agent"，这一条在我们对接合规审计时帮了大忙。
4. 实操过程：从零搭建Agent-Reach
4.1 环境准备与依赖选型
Agent-Reach的核心组件可以拆成三块部署：注册中心（registry）、路由网关（router）、管理控制台（console）。我们的部署方式是Docker Compose，生产环境再迁移到Kubernetes。
注册中心用Go实现，核心原因是Go的并发模型非常适合处理大量Agent心跳和状态更新的场景，而且部署起来就一个二进制文件，没有运行时依赖。路由网关也放在Go里，和注册中心共享核心库，网络开销更小。管理控制台是一个独立的Python Web应用，使用FastAPI加React，主要面向人工操作：查看Agent清单、调整路由策略、配置告警规则。
依赖方面主要用到了etcd做分布式协调和配置下发，这点要重点说一下。Agent-Reach在设计上支持单节点模式，就是注册中心本身不依赖外部存储，所有状态在内存里，适合测试和小规模部署。但生产环境我们强烈建议改成etcd模式：注册中心把元数据和路由规则都持久化在etcd里，Agent-Reach节点之间通过etcd的watch机制做状态同步，这样即使一个注册中心节点挂了，其他节点也能无缝接管。
# docker-compose.yml 核心服务定义（简化版） version: "3.9" services: etcd: image: quay.io/coreos/etcd:v3.5.9 command: > /usr/local/bin/etcd --name etcd0 --advertise-client-urls http://0.0.0.0:2379 --listen-client-urls http://0.0.0.0:2379 --initial-cluster etcd0=http://0.0.0.0:2380 --initial-advertise-peer-urls http://0.0.0.0:2380 --listen-peer-urls http://0.0.0.0:2380 --initial-cluster-state new ports: - "2379:2379" - "2380:2380" registry: build: ./cmd/registry depends_on: - etcd environment: REGISTRY_STORAGE: etcd ETCD_ENDPOINTS: etcd:2379 ports: - "8081:8081" router: build: ./cmd/router depends_on: - registry environment: REGISTRY_ENDPOINT: registry:8081 ports: - "8080:8080"4.2 部署注册中心与路由网关
注册中心和路由网关的部署顺序有讲究：先起etcd，再起registry，最后起router和console。原因很简单，registry启动时要连etcd做状态同步，router启动时要连registry拉取全量Agent列表。
启动完成后，用管理控制台验证一下系统状态。控制台首页会展示当前注册的Agent总数、可用实例数、每秒调用量、触达率曲线四个核心数字。首次启动时这些数字应该都是0，我们可以在控制台手动注册一个测试Agent来做连通性验证。
这里分享一个我们实际用过的验证脚本。它模拟了一个Agent实例的注册和心跳过程，不依赖SDK，直接用HTTP请求裸注册，用于快速验证注册中心是否工作正常：
# 1. 注册测试Agent curl -X POST http://localhost:8081/register \ -H "Content-Type: application/json" \ -d '{ "agent_id": "demo-agent-01", "capabilities": [ {"name": "demo.echo", "protocol": "rest", "endpoint": "http://127.0.0.1:9001/echo"} ], "metadata": {"zone": "test"} }' # 2. 查询Agent是否已在注册中心可见 curl -X POST http://localhost:8081/query \ -H "Content-Type: application/json" \ -d '{"capability": "demo.echo"}' # 3. 订阅心跳（每3秒一次） while true; do curl -X POST http://localhost:8081/heartbeat \ -H "Content-Type: application/json" \ -d '{"agent_id": "demo-agent-01", "load": 0.3}' \ > /dev/null 2>&1 sleep 3 done这套验证方式的好处是回归快，不用写任何代码就能确认触达层的基础功能是好的。Agent接入前建议先跑一遍这个脚本，排除掉"是不是注册中心没起来"这种低级的部署问题。
4.3 接入一个真实业务Agent
把部署验证做完后，接入真实Agent才是重头戏。这里用一个实际的例子来讲：假设我们有一个意图识别Agent，基于FastAPI写的，原先对外暴露了一个REST接口用于分类请求，现在要接入Agent-Reach。
第一步，安装SDK：
pip install agent-reach-sdk第二步，在Agent初始化时注册能力。原来的FastAPI代码是这样的：
from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() class IntentRequest(BaseModel): text: str session_id: str class IntentResponse(BaseModel): intent: str confidence: float @app.post("/intent") async def detect_intent(req: IntentRequest): intent, score = do_intent_detection(req.text) return IntentResponse(intent=intent, confidence=score)接入SDK后变成：
from fastapi import FastAPI from pydantic import BaseModel from agent_reach import AgentReachSDK, register_capability, atp_handler app = FastAPI() reach_sdk = AgentReachSDK( agent_id="intent-agent-prod-01", registry_url="http://registry:8081", zone="cn-east-1", ) class IntentRequest(BaseModel): text: str session_id: str class IntentResponse(BaseModel): intent: str confidence: float @register_capability(reach_sdk, name="intent.detect", protocol="rest", version="3.2") @app.post("/internal/intent") async def detect_intent(req: IntentRequest): intent, score = do_intent_detection(req.text) return IntentResponse(intent=intent, confidence=score)代码改到这里，Agent就已经具备被触达的能力了。第三步需要设置端点路径。注意，接入Agent-Reach后，外部调用方不再直接请求/intent路径，而是请求Agent-Reach的网关统一入口。原来的/intent接口对外要下线，改用/internal/intent作为内部触达端点，避免调用方绕过触达层直连Agent——这一点非常关键，一旦有调用方养成了直连的坏习惯，Agent-Reach的观测和治理能力就会失效，等于白接。
第四步，启动Agent，在管理控制台确认Agent状态从"pending"变为"healthy"。如果入库正常，控制台上能看到该Agent的能力列表和当前心跳时间。
4.4 配置路由与观测大盘
Agent接入后，需要配置路由策略和观测告警。
路由策略配置在管理控制台上操作，核心是配置"能力到策略"的映射。以intent.detect为例，建议配置成"最少负载优先+亲和路由"，因为意图识别服务通常是无状态的，更看重的是负载均衡；而亲和路由可以保证同一个会话的数据尽量落在同一个实例上，利用实例级的缓存优化体验。
{ "capability": "intent.detect", "policy": "least_load", "affinity": { "enabled": true, "key": "session_id", "ttl_seconds": 300 }, "timeout": { "connect_ms": 200, "first_byte_ms": 2000, "total_ms": 10000 }, "retry": { "enabled": false }, "circuit_breaker": { "error_threshold_percent": 30, "min_requests": 30, "reset_seconds": 30 } }比较值得聊的是熔断策略。刚开始我们把熔断阈值设得很灵敏，错误率超过10%就打开熔断，想让问题快速暴露。结果测试环境里有个Agent因为训练数据过期，有一小段时间准确率下降但接口依然返回200，反而没有触发熔断。后来我们把指标从"返回值错误率"改成了"业务错误率"，Agent的响应里如果带有business_error标记，也算在错误计数里。这个改动让我们能对"接口通但业务输出不可用"的情况也做到感知和熔断。
观测大盘方面，我们习惯把监控分成四个维度看：触达透视看全局成功率、触达率和调用量趋势；Agent透视看单个Agent的QPS、P95/P99耗时、Token消耗；路由透视看路由决策的分情况统计，比如多少次走了哈希路由、多少次走了最小负载；链路透视看具体的调用链，从请求进入网关到目标Agent返回结果的全过程。每个维度都有实时数据和小时级聚合数据，排障的时候从链路透视入手能最快定位问题。
5. 常见问题与排查技巧实录
5.1 Agent上线后始终注册不成功
这是接入过程中遇到最多的一个问题。Agent启动后，控制台上一直看不到它的状态，或者状态一直是"unhealthy"。
排查路径一般按三层走。先看SDK日志，确认注册请求有没有发出、响应是什么。多数情况卡在第一步：Agent配置里的registry_url填错了，或者网络不通。如果注册请求成功但控制台不显示，检查Agent声明的capability是不是重复了——Agent-Reach对同一Agent重复注册相同能力名会直接拒绝，防止路由表被污染。有一条必须要记住：能力名是全局唯一的，不同Agent之间也不能注册相同的名字。这个设计让意图路由的语义保持干净，但也意味着如果你真的有两个Agent都做意图识别，需要给它们分配不同的能力名，比如sales.intent.detect和support.intent.detect。
还有一种隐蔽的情况：Agent注册成功了，但控制台上显示unhealthy，因为Agent启动后没有正常发送心跳。常见原因有两个，一是Agent的event loop被长时间阻塞（比如某个同步调用卡住了），心跳协程没法执行；二是Agent所在宿主机的系统时间被NTP拨动了一下，导致心跳时间戳和注册中心时间不一致，注册中心认为心跳是过期数据。后一种情况我们遇到过两次，解决方案是心跳报文里不依赖时间戳，只用接收方的本地时间判断。
5.2 请求超时但Agent实际执行正常
这类问题最迷惑。调用方收到的响应是超时错误，但跑到目标Agent的日志里一看，Agent其实已经成功执行了，而且结果也生成了。多Agent协作场景里这个现象不是个别案例，归因下来有三类原因。
第一类是响应帧延迟。Agent成功执行完后，在回传响应帧时发生了网络抖动，或者Agent的SDK进程本身因为GC停顿暂时没有能力发送数据。这种情况下Agent日志层面看起来是完全正常的。排查手段是看Agent-Reach网关侧的日志：如果网关收到了Agent的执行成功标记但没有收到响应帧，日志里会有一条"execution_success_but_response_timeout"记录。
第二类是超时预算配置不合理。调用方的total_timeout设成5秒，但Agent从模型推理到返回结果需要6秒，每次都超时。这个问题的核心不是Agent慢，而是调用方和Agent对耗时的预期不一致。我们的建议是Agent在注册时声明timeout_sla_ms，路由层做转发时把这个值带给调用方，让调用方可以做校准。如果Agent确实经常超过阈值，要么调大超时，要么对前置模型层做优化。
第三类是链路中某个环节被限流。比如路由网关到Agent之间加了一层防火墙，或者Agent所在集群的网络策略限制了并发连接数，都会导致请求实际没到达Agent，但Agent侧看不出问题。我们的排查套路是：先在Agent侧查access log，确认目标请求是否真的进来了；如果没进来，再检查网络链路；如果进来了但调用方还是超时，才回到第一类和第二类原因。
5.3 触达率指标低于预期
触达率低于98%的时候，先把失败请求按错误码分桶，看集中在哪个错误类型上。
经验来看，触达率低最常见的原因是"调用方超时设置比Agent实际耗时短"，这在5.2里已经说过。第二个常见原因是熔断打开之后的连锁反应。熔断器打开后，新请求会直接被拒绝，路由层返回circuit_open错误，这段时间内触达率必然是断崖式下降。当初用30%错误率作为熔断阈值，触发后30秒内拒绝所有新请求，对触达率的影响非常明显。后来把策略改成"熔断只对目标能力生效，并允许路由层把一部分流量导给降级Agent"，触达率就好看了很多。
另外一个容易被忽视的原因是Agent实例太少。比如某个能力只有1个实例，它做模型推理时就算并发不高，也很容易出现排队。模型推理不像普通HTTP请求可以用多线程快速处理，CPU密集型的推理任务会让新请求在进程里排队。我们的注册表里有一个max_qps字段，路由层会根据Agent申报的容量做流量分配，不会粗暴地把所有请求都打给一个实例。如果Agent申报的max_qps明显低于实际流量峰值，就会出现"大量请求在路由层排队，最终超时"的情况。
5.4 路由到错误的Agent实例
"触达了错误的Agent"比"触达失败"更麻烦，因为结果不稳定，排查起来更困难。
最典型的分组路由问题：测试环境的调用方，请求打到了生产环境的Agent实例上。这通常是因为测试环境的路由网关和生产环境共用了一个注册中心，或者Agent注册时带的zone标签没用上。我们的解决办法是调用方在发起请求时通过context的routing_hint声明流量环境，比如{"env": "staging"}，路由层会优先匹配zone标签一致的实例；没有匹配到就报错而不是擅自发给其他环境。
另一个情况是语义匹配模式造成的误匹配。之前为了探索方便，用Embedding模型做能力名的语义匹配，结果有一次需要调用"order.query"，它匹配到了一个名称相近的"order.qps"能力，执行逻辑完全对不上。后来我们把语义匹配的阈值调高，并且要求匹配度超过0.95才允许自动路由，低于这个值一律转人工确认。在Agent能力数量超过50个以后，建议直接关闭语义匹配，全部改成精确匹配，稳定性优先。
5.5 排查问题的小技巧清单
按自己的实践经验总结一份排查技巧清单，分享给正在或准备做Agent触达层的读者。
第一，日志全部带上request_id和capability两个字段。没有这两个字段，跨Agent链路的排障基本无从下手。Agent内部调用外部工具时的日志也要带上，方便把"Agent调外部工具"和"Agent被调用"两个维度串联起来。
第二，注册中心的管理界面要有"动态调试"入口。调试入口能直接输入一条ATP协议报文，手动触发某次调用，不用临时写脚本模拟调用方。这个功能在一次线上事故中救过我们：调用方团队说是Agent-Reach导致的超时，我们用动态调试入口手动调用了一次目标Agent，发现Agent本身要8秒才返回，问题定位在Agent侧，前后只花了五分钟。
第三，注意Agent-Reach自身的容灾。Agent-Reach是一个集中式触达层，如果它挂了，所有依赖Agent的调用都会失败。我们从一开始就坚持了"Agent直连链路保留"的设计：Agent注册时启用direct_fallback选项，调用方可以在Agent-Reach不可用时自动降级为直连Agent原始接口。这个降级通道平时不用，但一旦Agent-Reach集群出现故障，它是整个系统不瘫痪的保命绳。
6. 个人实践感受与后续规划
Agent-Reach这个项目从设计到落地，前后大概花了三个多月。实践下来我最大的体会是：一套多Agent系统的复杂度，并不在Agent本身的模型和提示词上，而是在Agent之间的"连接逻辑"上。模型推理能力再强，如果Agent之间互相找不到、调不动、出了问题也无法定位，这个系统的可用性就是零。Agent-Reach解决的就是"怎么让Agent真正连成一张网"的问题。
对于正在做Agent基建的团队，我的建议是不要一上来就堆功能，先把四件事做扎实：注册与发现的可靠性、路由策略的可控性、观测数据的完整性、降级通道的可用性。这四件事做好，Agent-Reach就立得住。
后续计划上，我们在尝试两个方向。一个是在路由层引入"成本感知"策略，因为不同模型Agent的调用成本差异很大，路由时可以根据调用方的预算标签选择更经济的实例。另一个是在触达协议里加入流式响应支持，让长耗时Agent可以先返回一个token流，调用方边收边处理，而不是干等最终结果。等这两个方向跑出稳定效果，我再写一篇更新的实践总结分享出来。
