一上来先把结论放在这儿Agent-Reach 不是又一个链路追踪系统也不是简单的健康检查面板它解决的是多 Agent 协作里最让人头疼的那个问题——当一个任务需要 A 去调用 B而 B 看起来活着却怎么也不回结果时你怎么办。我们内部跑了几个月靠它把一次典型的多 Agent 调用故障从“等待超时 5 分钟”压到了“15 秒内自动切走”这篇文章就把 Agent-Reach 的定位、设计、部署和踩坑过程完整拆开讲一遍。适合谁来读两类人最需要一类是把多个 AI Agent 编排成流水线但经常被“某个节点没挂、任务却卡死”折磨的工程团队另一类是准备给自己团队写类似调度基础设施想先看看别人是怎么定义“可达性”的开发者。前者可以直接抄部署方案后者可以参考它的打分模型和故障转移思路。1. 为什么先有“可达性”这个坑才有的 Agent-Reach1.1 多 Agent 系统里链路通不等于 Agent 可用最早我们其实没打算做独立组件。当时系统里有十几个 Agent 节点负责不同的子任务有的做内容理解有的做工具调用有的只做数据清洗。节点之间通过一个简单的路由层互相调用路由层怎么判断某个 Agent 是否可用用的是最朴素的 TCP 连通性检测端口能连上就认为活着。这套机制在单体应用时代没什么问题但在多 Agent 场景里很快就失真了。最常见的现象是进程没死端口也通但 Agent 内部的线程池已经挤满了排队任务新任务进去后只能在队列里死等还有的是 Agent 的下游工具超时导致 Agent 表面响应“我收到了”实际结果迟迟出不来。链路是通的但交付是断的。TCP 探测对这种“通而不达”的状态完全无感。另一个更隐蔽的情况是 Agent 在某些时间段出现过载。比如某个数据清洗 Agent 平时处理一个任务要 300ms但上游突然涌进来大量请求后它每个任务要排队 3 分钟。从网络层面看它一切正常从业务角度看它已经“不可达”了。你继续把任务发给它等于把整个流程的尾部延迟无限拉长。Agent-Reach 的出发点就是补上这个空白我们需要的不是“端口能不能连上”而是“现在把任务交给它它在可接受的时间内能不能返回有效结果”。这个区别非常重要因为它把判断标准从基础设施层抬高到了业务交付层。1.2 我们怎么定义“reach”不是 ping 通而是能交付结果“可达”这个词在 Agent-Reach 里被拆成了三层基础连通进程在跑注册信息存在探活请求能收到响应业务活性Agent 本身没有被内部的队列、锁或下游依赖卡死交付可信把任务实际交给它之后在预期时间窗口内产出合格结果的概率足够高。只看第三层太理想因为每个任务质量还和输入数据有关只看第一层又回到老路。所以我们把 Agent-Reach 的定位设定为负责量化基础连通和业务活性并为交付可信提供辅助信号。它不直接判断“这个结果好不好”但它持续观测“过去一段时间里你交付成功还是失败”用真实任务的结果反过来修正可达性评分。这个设计思路很像电商里的“履约率”。一个仓库仓库容量、网络、存续都不错和它是否合作伙伴但最终衡量这个仓库有没有用要看它接单后能不能按时发货。Agent-Reach 的核心逻辑就是给每个 Agent 维护一个类似“履约指数”的实时评分把网络探活、队列状态、历史任务成功率混合在一起作为路由决策的动态依据。2. Agent-Reach 从探活到路由的完整设计2.1 整体拓扑注册中心、探活器、策略引擎各管什么Agent-Reach 的架构不复杂核心由三个角色组成注册中心 Registry保存所有 Agent 的元数据包括 agent_id、能力标签、请求地址、当前状态、最近上报的负载信息。探活器 Probe以固定周期主动访问每个 Agent 的探活接口收集响应时间、状态码、队列深度、任务积压量等数据。策略引擎 Policy Engine把探活数据和注册信息汇总成“可达分”并结合路由规则生成当前可用的 Agent 候选列表也就是一份动态路由表。三个角色可以部署在同一个进程里也可以拆开。小规模团队建议上一套 Docker Compose后边我会给最小配置。大集群会把探活器分布到多个区域避免探活器自己所在的网络出问题后产生误判。这里有一个容易被忽略的设计点注册中心只记录 Agent“期望状态”探活器才负责维护“实际状态”。Agent 崩溃后注册中心不会立刻清掉它的信息而是等待探活器连续多轮确认不可达后再标记为 offline。这么做是为了防止注册中心频繁抖动也让路由表保持一定程度的稳定不会一有瞬时波动就大规模切流。2.2 健康打分从离散探活结果到连续“可达分”探活器每轮探活拿到的是一个离散状态通、不通、超时、响应异常。但路由决策不想要离散状态它需要一个可比较的连续分这样才能做优先级排序和阈值控制。Agent-Reach 使用一个加权打分公式reach_score w1 * liveness_ratio - w2 * latency_penalty - w3 * queue_penalty其中liveness_ratio最近 N 个探活周期内成功响应的比例取值 0 到 1latency_penalty最近探活响应延迟经过 EMA 平滑后除以容忍延迟上限得到的惩罚项queue_penaltyAgent 每次上报的待处理任务数与处理能力的比值超过阈值后线性放大。举个例子如果w1100w20.2w330某个 Agent 最近 10 次探活成功 10 次平均延迟 200ms容忍延迟 500ms队列积压率为 10%那么它的分数大约是100 * 1.0 - 0.2 * (200 / 500) - 30 * 0.1 100 - 0.08 - 3 96.92另一个 Agent 同样能连通但平均延迟已经到 800ms队列积压率达到 80%分数就会明显下降。这里有个关键经验分数不需要绝对精确只要相对排序稳定即可。路由引擎每次选优时自然会把流量倾向于分数更高的 Agent就达到了目的。还要注意探活周期不能太频繁。默认建议 10 秒一次故障检测和资源消耗之间取平衡。如果探活本身采取了阻塞式 HTTP 请求探活器并发量还要加限制否则 Agent 抖动时探活请求会在探活器内部堆积成雪球。2.3 为什么没有再写一个“链路追踪”而是做路由前置很多人问我这不就是给 Agent 加个健康检查吗和链路追踪有什么区别做链路追踪记录一次跨 Agent 调用的完整路径能帮你排查“任务为什么慢”Agent-Reach 做的事情则是在调用发生之前提前判断“这个 Agent 还值不值得把任务给它”。两者是一个事后一个事前。事前判断的设计目标决定了 Agent-Reach 必须非常轻量。链路追踪需要透传 trace_id、采样、存储、聚合链路全链路所有组件都会感知Agent-Reach 则只需要在路由层和 Agent 上报层做改动接入负担小得多。对很多团队来说给现有 Agent 加一套完整链路追踪系统的成本远高于部署一个调度前置组件。而且从故障转移这个目标出发链路追踪解决不了“任务已经发给了坏 Agent”的问题。等你在链路数据里看到异常时任务早就超时了。Agent-Reach 的价值在于把判断节点前移把坏 Agent 挡在任务下发之前。实践下来这对线上稳定性的提升比事后追踪要直接得多。3. Agent-Reach 最小接入方案从零跑通一套 Agent 网络3.1 安装与配置一个编排文件搞定核心链路先展示一套最简架构一个 Agent-Reach 服务端三个 Agent 节点。服务端用嵌入式注册中心适合五十个节点以内的规模再大的规模可以换成外置存储。这里是一份可直接落地的docker-compose.ymlversion: 3.8 services: agent-reach: image: agentreach/server:latest ports: - 8080:8080 volumes: - ./agent-reach.yaml:/etc/agent-reach/config.yaml restart: unless-stopped agent-alpha: image: agentreach/example-agent:latest environment: AGENT_ID: alpha AGENT_CAPABILITIES: text_processing,tool_use AGENT_REACH_REGISTRY: http://agent-reach:8080 AGENT_REACH_PUSH_INTERVAL: 10s agent-beta: image: agentreach/example-agent:latest environment: AGENT_ID: beta AGENT_CAPABILITIES: data_cleaning,text_processing AGENT_REACH_REGISTRY: http://agent-reach:8080 AGENT_REACH_PUSH_INTERVAL: 10s服务端的agent-reach.yaml可以做精细调整server: listen: :8080 probe_interval: 10s probe_timeout: 3s probe_concurrency: 10 registry: type: embedded evict_after: 90s policy: min_reach_score: 60 fallback_order: round_robin enable_auto_failover: true notify: webhook: http://monitor.internal/agent-reach/eventsprobe_interval建议 10 秒probe_timeout建议 3 秒两者比值决定了系统发现一次故障需要的最长时间。如果你想更快切换interval 可以调到 5 秒但探活器的压力会翻倍。启动之后Agent 会自动向注册中心上报身份和地址探活器开始周期访问 Agent 暴露的/healthz接口。查看所有 Agent 状态curl http://localhost:8080/v1/agents正常情况下会返回每个 Agent 的reach_score、最近探活时间和状态。如果看到某个节点分数低于配置的min_reach_score策略引擎就会把它从候选列表里摘掉。3.2 Agent 端上报与探活的两种方式对比Agent 端接入有两种主流方式主动上报和被动探活。Agent-Reach 默认两种都支持但实际使用中不能只依赖一种。主动上报适合自带运行时 SDK 的 Agent。Agent 内部起一个轻量协程每 10 秒把队列深度、当前处理线程数、最近任务平均耗时、内存水位推给 Agent-Reach。这种方式的优势是信息丰富Agent 能看到自己内部的真实负载。被动探活则由 Agent-Reach 直接请求 Agent 的 HTTP 探活接口优势是客观不依赖 Agent 是否诚实上报。我的建议是两个都开但权重不同。上报数据用于计算队列惩罚和交付信号探活数据用于计算连通性和延迟。如果 Agent 端没法嵌入 SDK只有被动探活也能跑只是业务活性判断会弱一些。下面这段伪代码描述了简单上报客户端的样子import time import requests REGISTRY http://agent-reach:8080 AGENT_ID alpha def collect_metrics(): return { queue_depth: get_queue_depth(), active_threads: get_active_threads(), last_task_duration_ms: get_last_task_duration_ms(), task_success_count: get_task_success_count(), task_fail_count: get_task_fail_count(), } def loop(): while True: metrics collect_metrics() requests.post( f{REGISTRY}/v1/agents/{AGENT_ID}/report, jsonmetrics, timeout2, ) time.sleep(10)上报接口要设计成幂等的因为网络抖动可能导致重试。服务端只取最新一次上报的数据不叠加计数。3.3 从日志到指标容易被忽略的上线验收项很多团队上线这类组件时只确认了“Agent 状态能在控制台显示”就觉得完了。我建议多做三个验收项否则后期会很痛苦。第一确认探活接口不会因为 Agent 自身过载而延迟响应。有些 Agent 把健康检查处理和业务请求放在同一个线程池里业务高峰时健康检查也跟着排队导致 Agent-Reach 误判它不可用。正确做法是给健康检查一个独立的、极小优先级的线程池保证它在大压力下仍然能快速响应。第二检查时钟是否一致。Agent 上报的timestamp和 Agent-Reach 服务端的时间不能差太多否则分数计算公式里的时间窗口会失真。容器环境的机器如果没同步 NTP很容易出现 Agent 上报的数据被当成过期数据丢弃。第三用故障注入验证自动切换真实生效。单纯看控制台分数下降还不够必须发一个真实业务任务观察它是否被路由到备用 Agent。这个验收项我们会在后面第四节展开讲。4. 实测网络抖动与 Agent 故障时Agent-Reach 如何切换4.1 混沌实验设计断网、进程终止、延迟注入为了验证 Agent-Reach 不是“听起来合理”而是“真能切”我们搭了一套三节点测试环境alpha 负责处理主要任务beta 和 gamma 是备用节点。测试任务是模拟一个内容处理流水线每次请求打到路由层路由层根据 Agent-Reach 返回的候选列表选择目标。我们做了三类故障注入进程终止直接kill -9掉 alpha 的主进程模拟 Agent 崩溃网络分区用防火墙规则丢弃 alpha 所在容器出方向的数据包模拟网络不可达延迟注入给 alpha 的请求响应加上 1500ms 延迟模拟 Agent 过载或下游依赖变慢。每种故障持续 45 秒恢复后继续观察 60 秒。每次实验固定发送 1000 个请求记录成功率和任务平均完成时间。4.2 故障转移时间、误判率与恢复行为三类故障的实验结果如下故障类型未启用 Agent-Reach 时的不可用请求启用后不可用请求平均切换时间恢复后回切时间进程终止全部请求等待超时23约 20 秒约 30 秒网络分区全部请求等待超时41约 25 秒约 40 秒延迟注入470 个请求耗时超过 5 秒5约 35 秒约 45 秒进程终止时Agent-Reach 反馈最快因为 TCP 连接直接断开探活器在下一轮就发现了。网络分区稍慢因为超时判定需要等到探活请求超时。延迟注入最慢因为 Agent 进程还活着探活也成功只是分数里的延迟项随时间累积慢慢下降直到低于阈值才触发切换。这里有一个重要认知Agent-Reach 不是瞬间切换。它需要几轮探活数据才能确定一个节点状态是否稳定否则恢复期间的抖动会引发频繁切换。25 秒到 35 秒的切换时间对大多数内部调用的超时设置来说完全够用但如果你的业务要求 5 秒内必须切换那就得把探活周期降到 2 秒同时承担更高的误判风险。恢复行为上我们刻意让 Agent-Reach“慢回切”。一个节点恢复后不会立刻拿回全部流量而是先给它分配少量探测性任务连续多轮成功率达标后才恢复全额权重。这样做是为了避免刚恢复的 Agent 因为缓存冷启动或线程池重新热身又被流量打垮。4.3 把 Agent-Reach 接到业务路由后的效果接入业务路由后Agent-Reach 扮演的不再是一个监控面板而是一个动态路由过滤器。业务请求发起前先拉取策略引擎生成的候选列表agents reach_client.get_route(capabilitytext_processing, limit2) target_agent agents[0] result await call_agent(target_agent, task)当 alpha 被摘掉后get_route返回的列表自动变成 [beta, gamma]业务代码不需要改动。这种设计让 Agent-Reach 和业务路由解耦后者不需要知道故障切换的细节只需要负责“从给的列表里选一个”。实测中还发现一个意外好处因为探活接口会返回队列深度Alpha 的分数会在真正的故障发生前就开始下降。比如某个模型推理 Agent 因为上游请求暴增队列从 500 涨到 5000探活周期结束时队列惩罚直接把分数拉到阈值以下路由层在它完全卡死之前就开始分散流量。这种“梯度劣化而不是二值死亡”的感知比任何事后告警都有用。5. 常见误判与掉坑记录Agent-Reach 真实使用中的边界5.1 探活成功但任务失败Agent-Reach 覆盖不到的“质量”维度最容易踩的坑是以为 Agent-Reach 能直接保证任务质量。实践里最常见的情况是某个 Agent 探活一切正常但实际交付时因为模型 prompt 配置错误连续返回不合预期的结果。Agent-Reach 对这类“质量级不可达”天然无感。我们的解决办法是引入任务结果回执。每个 Agent 在完成任务后把成功或失败的结果回传给策略引擎。策略引擎不只看探活分数还维护一个“近一百次任务成功率”的滑动窗口。一旦成功率持续低于某个阈值即使探活分数很高路由层也会降低它的优先级。这个机制不是 Agent-Reach 初版就有的是上线两周后加上的。如果你也遇到类似情况建议不要试图把所有判断都塞进探活逻辑。探活管“有没有能力接”任务回执管“接不接得住”让两个信号各司其职比硬凑一个万能公式更清晰。5.2 脑裂、clock skew 与探活风暴三个经典的“分布式陷阱”Agent-Reach 虽然简化了路由判断但它本质上还是一个分布式协调组件分布式系统里的经典坑一个都不会少。脑裂发生在网络分区时。两个探活器可能得出相反结论探活器 A 和 Agent 在同一个分区里觉得 Agent 完全正常探活器 B 在另一个分区连续几次探活失败认为 Agent 不可用。如果不引入多数派机制两个探活器会把互相矛盾的路由信息发给业务层。我们在设计里强制要求探活器数量超过两个时只有超过半数的探活器判定不可达才允许把 Agent 从候选列表摘除。clock skew 主要影响 Agent 上报的时间戳。不同容器时间偏差超过几秒后服务端在计算任务耗时时会得到异常数据例如“任务耗时 -3 秒”。后来我们统一要求所有容器使用宿主机的时钟同步并在上报数据里同时携带一个单调递增的序号服务端丢弃序号乱序或时间倒跳的数据。探活风暴是故障恢复时的连锁反应。某个 Agent 恢复后所有等待发送的任务瞬间涌向它同时探活器也开始高频访问它导致它再次过载。我们给恢复后的节点加了一顶“冷却帽”恢复后的前 30 秒只接受 20% 流量同时探活请求采用指数退避和随机抖动从根源上避免恢复节点被打崩。5.3 扩展把上下文能力、权限策略也纳入可达性评分Agent-Reach 使用到后期我们把“可达性”这个概念又往外扩了一步。AI Agent 场景里一个 Agent“不可达”不一定因为进程挂了也可能因为它当前不具备处理该任务的前置条件。比如一个具备工具调用能力的 Agent其可用的工具权限是分等级的。某项任务需要调用一个高权限工具但当前 Agent 的 token 或权限已经失效那它对这个任务而言就是“功能不可达”。我们在注册元数据里增加了capability_requirements字段路由引擎在计算可达分时会额外检查 Agent 的能力标签和权限状态。另一个扩展是把上下文窗口纳入可达性。大模型 Agent 能处理的上下文长度有限当某个 Agent 负责的任务上下文占用已经接近上限时即使它的网络响应很快也不适合再接新任务。Agent 主动上报里增加了context_usage_percent策略引擎把它作为一项软约束分数相同的情况下优先选上下文余量大的 Agent。这个扩展方向让 Agent-Reach 从“网络层面的探活器”慢慢变成了“任务层面的适配器”。现在团队里如果有一个新 Agent 要接入我们不再只问它“健康检查接口写了吗”还会问它“你的能力标签、上下文上限、任务成功率回执都配好了吗”。正是这些在别人看来不起眼的小参数决定了一个多 Agent 系统在大流量下是平稳运行还是连环超时。
