1. 项目背景与整体设计思路Agent-Reach 不是某一个开源仓库的名字而是我们组里给一套“智能体触达诊断与编排组件”起的内部代号。做 AI 应用落地久了你会发现一个尴尬事实模型本身已经很能打了可一旦要把 Agent 接到真实业务系统里问题往往不出在“模型聪不聪明”而是出在“它够不够得着”。这里的“够得着”包含三层意思接口通不通、授权有没有、执行结果能不能被确认。Agent-Reach 要解决的就是把这层“触达能力”从玄学变成可量化、可测试、可复盘的工程问题。我给不少团队讲过这个判断如果把大模型比作大脑Agent-Reach 处理的就是它的手和脚。大脑知道应该调什么接口、看什么数据、做什么操作但如果手伸不过去一切都停在想法阶段。很多项目在演示时一切正常一上生产就频繁失败根因大多不是模型能力退化而是工具链不够稳定代理在运行时触达不到预期的外部系统。这篇文章会完整复盘 Agent-Reach 从需求拆解、模块设计、代码实现到踩坑排错的全过程既说清楚设计逻辑也给出可以直接参考的落地方法。1.1 “触达失败”才是 Agent 落地的真正瓶颈我们先看一个典型场景。某个客服工单系统接入大模型 Agent 后用户问“帮我查一下订单 ZD20240901 的物流状态”模型立刻识别出意图生成一段正确的函数调用参数然后呢调用物流查询接口时网关返回 401因为该接口要求动态签名或者返回 403因为该接口只开放给特定网段再或者接口能通但底层物流数据库连接超时。这些失败和模型能力毫无关系但它会让用户以为“AI 很蠢”。这类问题在传统软件工程里其实有对应解法叫依赖健康检查。但在 Agent 场景下情况复杂得多Agent 是动态决策的它可能在一个任务中任选五个候选工具之一工具状态需要在“决策发生之前”就对 Agent 可见而不是等它选了之后才报错。Agent-Reach 把这个过程称为“触达探测Reach Probe”目标是在主流程运行前、运行中持续回答一个关键问题当前环境下Agent 可用的手和脚真正能触及哪些能力这看起来像个基础设施问题实际上会直接决定业务可用性。我见过一个团队上线了 30 个 Agent 工具但从不检查工具覆盖最后模型 60% 的工具调用都在给用户报错体验可想而知。后来他们加了一层类似 Agent-Reach 的能力注册与探测错误率立刻从 12% 降到 1% 以下。1.2 为什么“逐个联调”解决不了这个问题一定有朋友会问工具是开发同学自己接的联调时都测过有必要做一套专门系统吗这个问题很专业也很有迷惑性。单独看每个工具联调确实能通过但 Agent-Reach 解决的是系统性问题不是单个接口问题。首先工具数量一多联调就失去意义。我们组接入的业务工具有几十个分布在客服、订单、库存、供应链等多个域每个工具又有多个方法全量手工联调一次要半天而且第二天可能就有某个环境挂了。其次生产环境的状态是动态变化的。数据库主从切换、上游 API 加鉴权、网关限流阈值调整任何一个变化都会让昨天的可用工具今天变得不可用。最关键的Agent 是在运行时动态选择工具的你无法预判它会选哪个只能保证候选池里的每个工具都时刻处于“可探测、可确认”的状态。所以 Agent-Reach 的设计核心不是“联调一次”而是“持续探测”。它把“Agent 决策期需要知道的工具状态”作为一种一等公民数据实时维护再喂给 Agent 的二次决策层。这样 Agent 拿到的不只是工具的 OpenAPI 文档还包括“此刻它是否真的可用”“预期延迟是多少”“当前身份是否有权限”这才是真正意义上的“触达范围”。1.3 Agent-Reach 的定位和适用场景Agent-Reach 适合的团队画像比较清晰你正在做基于大模型的 Agent 应用而且应用需要调用的外部依赖超过 10 个你的业务对可用性有要求不能让 Agent 在用户面前反复用错误工具你想让 Agent 的行为可观测、可排查而不只是看日志里飘着一堆报错。它不是一个模型训练框架也不是一个 Agent 编排框架它位于 Agent 框架与外部系统之间相当于一个能力触达底座。在动手做之前我建议先明确边界。Agent-Reach 不对模型生成的工具调用参数做校验那是 function calling 层或校验层的事它也不代替网关做流量控制。它只负责回答三个问题有哪些能力可用哪些能力现在真的够得着如果够不着是网络问题、认证问题还是权限问题把边界划清楚项目才不会越做越臃肿。2. 核心模块与关键技术点拆解Agent-Reach 从零到上线大概用了三周后面又磨了两周做稳定性和兼容性。整体分四个核心模块能力注册中心、可达性探测器、上下文路由策略、触达评分与观测。四个模块之间的关系可以这样理解注册中心提供“有什么”探测器告诉“通不通”路由策略决定“选哪个”评分系统记录“好不好”。2.1 能力注册中心把“有什么”结构化能力注册中心是 Agent-Reach 的数据基础。它的作用不是简单存一份接口文档而是把所有 Agent 可调用的能力整理成统一、结构化、可程序访问的元数据。每个能力我们称为一个 Node包含基础标识、类型、入口信息、认证要求、依赖说明、状态数据等。我整理了实际使用的 Node 字段这里列成表格供参考字段含义示例key全局唯一标识order.query.statusname展示名称订单状态查询kind能力类型api / database / browser / rpaentry入口地址或标识https://gateway.internal/v1/ordersauth认证配置引用auth_id: oss-auth-01tags业务域标签[order, logistics]health最近一次探测结果ok / fail / unknownlatency_ms最近一次探测延迟320capability_schema工具语义描述JSON Schema略这里最容易忽略的是capability_schema。Agent 要正确调用一个工具必须知道它的参数结构所以注册中心不能只存“接口地址”还必须存一份标准的 JSON Schema 工具描述。我们在实践中直接复用了主流 Agent 框架的 function calling schema 格式避免两套数据、两套维护。每个 Node 的 schema 会被转换成 OpenAI、Claude、本地模型等不同格式但底层数据源始终是同一份。注册中心的另一件重要工作是依赖关系的维护。比如“订单查询”这个 Node 依赖“用户 Token 服务”“用户 Token 服务”又依赖某一个内部认证接口。如果一个上游依赖挂了下游即使接口本身正常也功亏一篑。因此我们在 Node 里增加了一个depends_on字段探测的时候会先根据依赖拓扑排序上游挂了就跳过下游探测并标记为“dependent_failure”而不是真的去跑一次下游接口。这一点在排查时省了很多时间。2.2 可达性探测器把“通不通”变成可执行任务可达性探测器是整个系统最核心的部分。它的任务不是模拟一次完整业务调用而是对每个 Node 执行一次低成本、无副作用的“触达验证”。听起来简单做起来需要非常克制因为你随时可能在探测过程中把生产环境的数据改了。我定了一个铁律探测计划只能包含只读操作或幂等的元信息查询。对于 API 类 Node优先请求GET /health、GET /metadata或HEAD方法如果接口没有合适的只读端点则探测认证节点和网络链路对于数据库类 Node执行SELECT 1或从系统表读取版本信息对于浏览器自动化类 Node只打开页面并读取标题或关键元素不提交任何表单。这一条规则几乎可以消灭“探测导致生产故障”这一类事件。探测执行的细节也很关键。我们会构造一个ProbeTask包含 Node key、探测类型、预期结果判断逻辑、超时时间和重试策略。超时时间通常设置为正常业务超时的三分之一比如业务接口允许 3 秒探测就只给 1 秒。为什么这么设计因为探测的目的是快速发现问题如果探测本身也要等很久就会拖慢主流程而且一个长期超时的接口探测只要确认“它不在预期时间内返回”就已经足够判断为不可用不需要等它真正报错。2.3 上下文路由策略让 Agent 在手和脚里做选择有了探测数据Agent-Reach 还需要把结果用起来。我们设计了一个路由策略层可以理解为 Agent 触达范围的“最后一公里”。当一个 Agent 准备调用工具时它原本只有一个工具列表现在 Agent-Reach 会在工具列表之上再叠一层动态过滤和排序逻辑。这里的实现不复杂但效果非常明显。我们把每个 Node 的探测结果映射成三层状态green表示可用yellow表示可用但延迟升高red表示不可用或未认证。路由层在做 tool selection 时会先把red状态的 Node 从候选集里剔除把yellow状态的 Node 排序往后挪并可以附加一段提示文本“该工具当前延迟较高推荐使用替代工具”。这样模型在生成一次完成时就天然避开了不可用的通道。我特别想强调一点路由层不应该阻断 Agent 调用因为探测结果只是一个近似的健康状态有可能刚探测完接口又恢复了。更稳重的做法是把路由结果作为附加信息传给模型让模型结合任务上下文做最终决定。只有一种情况我会建议强制阻断——该 Node 明确返回“认证缺失”或“依赖失败”因为这种失败几乎不可能在几秒内自动恢复继续让 Agent 调用只会浪费一次交互。2.4 触达评分与观测把“好不好”暴露出来最后一块拼图是可观测性。没有观测Agent-Reach 本身也会变成黑盒。我们为每个业务域、每个 Node、每次探测都生成了结构化事件最终汇总成几个关键指标。首先是可用率统计一个时间窗口内探测成功的比例。其次是覆盖率统计所有已注册 Node 中最近一个周期内处于可探测且可调用状态的比例。然后是延迟变化查看每个 Node 的 P50/P95 延迟如果 P95 突然翻倍路由层会自动把该 Node 降级为yellow。最后是失败原因分布把失败归因为网络、认证、超时、依赖故障、非只读限制等类型。这些指标除了上监控大屏还被一个更重要的消费者使用——Agent 本身。我们在系统提示词里注入一份简短的健康摘要例如“订单查询接口可用率 98%延迟正常库存接口认证失败请勿调用。”虽然这会让系统提示词变长一些但收益远大于成本。很多决策错误其实不是因为模型不够聪明而是因为它不知道哪个选择是可落地的选择。让 Agent 看见触达范围它才能做出有根据的推理。3. 实操过程与关键环节实现接下来是代码层面的拆解。我不会把完整项目贴出来而是把最核心的几个环节拿出来讲清楚包括 Node 和探测任务如何定义、调度器如何设计、如何与 function calling 层对接以及评分公式怎么定才不忽悠人。3.1 定义 Node 数据模型和探测任务我们用 Python 写 Node 数据模型因为团队 AI 应用和服务端都偏好 Python。一个 Node 的简化定义如下实际会多一些字段但核心结构一致from dataclasses import dataclass, field from enum import Enum class HealthState(str, Enum): UNKNOWN unknown GREEN green YELLOW yellow RED red dataclass class Node: key: str name: str kind: str # api / database / browser_page entry: str # 地址、连接串或页面标识 auth_ref: str # 认证配置标识 tags: list[str] field(default_factorylist) depends_on: list[str] field(default_factorylist) health: HealthState HealthState.UNKNOWN latency_ms: float 0.0 last_error: str schema: dict field(default_factorydict) # 工具描述 Schema这里auth_ref值得多说一句。很多团队会把账号密码、Token 直接塞进 Node 里方便倒是方便但每次打印日志、序列化配置时都会有泄漏风险。我们把认证信息全部被外部引用式管理Node 里只有一个 ID真正读取凭据发生在探测执行器的独立模块中且要求凭据不回写日志。这是一个迟早就必须做的安全设计越早越好。探测任务ProbeTask则包含 Node、计划动作和判断逻辑。我们给 API 类 Node 准备的计划动作有三种http_health、http_metadata、tcp_ping。http_health是请求健康检查端点http_metadata是只读元查询tcp_ping用于无法安全调用的接口只做链路检查。判断逻辑是一个回调根据状态码、响应体关键字或响应时间决定成败。这个设计把探测从“针对每个接口写一遍”变成了“声明式配置”新增一个 Node 只需几行配置。3.2 调度中心并发控制、超时与重试探测任务不能一股脑全量并发跑。几十个 Node 同时打向生产环境轻则触发网关限流重则被安全团队约谈。调度中心需要做四件事并发控制、超时控制、重试和去重。我们用 Pythonasyncio.Semaphore做并发控制默认最大并发量不超过 8。示例代码如下import asyncio import time async def run_probe(node: Node, executor, semaphore, timeout1.0): async with semaphore: start time.perf_counter() try: plan build_readonly_plan(node) result await asyncio.wait_for( executor.execute(node, plan), timeouttimeout ) latency (time.perf_counter() - start) * 1000 return ProbeResult( nodenode.key, okresult.ok, latency_mslatency, reasonresult.reason or ) except asyncio.TimeoutError: return ProbeResult( nodenode.key, okFalse, latency_mstimeout * 1000, reasontimeout )超时时间这里特意设置为 1 秒前面说过理由探测不是业务调用。但需要补充的是探测失败后的重试策略。按我的经验只有两类失败值得立即重试网络抖动导致的瞬时失败以及上游返回 5xx 但响应很快的失败。重试次数最多两次且重试间隔要短否则会因为重试拖慢整个探测周期。我们实际逻辑是第一次超时不再重试只有连接拒绝和 5xx 会间隔 200ms 重试一次。另外调度中心还要支持“依赖感知”。如果一个 Node 声明depends_on依赖 Node 必须先行探测。实现上不需要太复杂的拓扑算法只要把任务列表按依赖深度排序然后分批提交即可。依赖节点失败后续节点直接标记为dependent_failure不执行真实探测既节约时间又避免掩盖根因。3.3 与 Function Calling 层的对接Agent-Reach 的价值最终要反映到 Agent 的决策质量上所以对接 function calling 的方式很重要。主流大模型框架都支持工具描述列表比如 OpenAI 风格的tools参数。我们的做法是写一个适配层从注册中心读取 Node 状态然后动态生成工具列表。核心逻辑如下def build_tools_for_agent(actor: str, task_tags: list[str]) - list[dict]: candidates registry.query(tagstask_tags) tools [] for node in candidates: state state_cache.current(node.key) if state in (auth_failed, dep_failed): continue if state yellow: node.schema[description] 当前延迟偏高功能可用但需注意耗时 tools.append(node.schema) return tools这一步看着简单实际操作时有个很大的坑工具描述的大模型提示词空间非常宝贵。如果注册中心有几万个 Node不可能全塞给模型即使只有几百个把所有工具一股脑发给模型也会导致工具选择准确率下降。所以我们增加了task_tags维度根据业务域先过滤一轮。比如客服域的任务只会看到订单、退款、物流相关 Node库存域的 Node 完全不会进候选集。这才是真正体现了 Agent-Reach 的“触达范围”思想范围不仅是“能不能触达”还包含“该不该出现在这次决策中”。路由层还有一个不太起眼但很实用的设计候选工具排序。我们把 Node 的latency_ms作为排序参考值之一延迟低的排前面。大模型在选择工具时虽然不看数组顺序但实测发现把可用性高的工具排前面能略微提高选择准确率。也有一种说法是数组顺序会影响部分模型的选择倾向虽然不是决定性因素但既然没有副作用我就会保留这个排序。3.4 触达评分公式不只看成功率做评分模块时我们争论了很久到底什么是好的触达范围是成功率越高越好吗后来达成共识成功率只是基础还要考虑覆盖率和性能。我们的评分公式最终定为加权和REACH_WEIGHTS { availability: 0.5, # 可用率 coverage: 0.2, # 覆盖系数 performance: 0.2, # 性能系数 stability: 0.1, # 稳定性系数 } def compute_reach_score(domain: str) - float: metrics stats.aggregate(domain) availability metrics.ok_count / max(metrics.total_count, 1) coverage metrics.green_nodes / max(metrics.registered_nodes, 1) performance 1.0 / (1.0 metrics.p95_latency_ms / BASELINE_LATENCY_MS) stability compute_stability(metrics.history) return 100 * ( REACH_WEIGHTS[availability] * availability REACH_WEIGHTS[coverage] * coverage REACH_WEIGHTS[performance] * performance REACH_WEIGHTS[stability] * stability )为什么性能系数要除以一个基线因为延迟是不可跨系统直接比较的。内部接口 P95 可能是 50ms第三方物流接口 P95 是 800ms同一个公式必须按各自基线归一化。基线可以从历史 P95 计算也可以由人工配置。稳定性系数则参考最近 10 次探测结果的波动情况如果成功率忽高忽低稳定性系数就会下降。这套评分不直接参与 Agent 的工具选择而是用于团队复盘和报警阈值设定。实测下来一个域得分低于 70 时用户反馈中的“AI 出错”明显增多所以我建议把 70 分作为预警线。4. 上线后最常踩的坑与排查实录无论设计时想得多周全落地时还是会有意外。 Agent-Reach 上线后我们积累了厚厚一叠问题记录下面挑几个最有代表性的既列出现象也给出具体的排查思路和解决办法。4.1 工具注册表膨胀导致探测风暴一开始我们很兴奋把所有能接的接口全部注册成 Node一个月后注册中心里多了几百个 Node探测调度周期从 5 秒一次被拉长到 60 秒一次而且每次探测都会在生产网关产生一波流量安全团队开始投诉。排查后发现根源是注册中心没有任何分域和分级机制所有 Node 都在同一个探测队列里。解决办法是引入多级探测策略。高频 Node比如订单、用户信息每 10 秒探测一次普通 Node 每 30 秒低频 Node 只在业务出现失败时触发按需探测。同时探测的开始时间做了随机抖动避免整点并发斗。这之后网关流量下降 70%探测数据反而更有参考价值因为高频 Node 的实时性更高。这里还有一个建议注册 Node 时要提供expected_usage字段标注该 Node 的真实调用频率。注册中心定期清理超过 30 天未使用且无明确规划的 Node避免整个系统被无效数据拖垮。4.2 认证失效是最大的隐形杀手运维过程中我发现大半的red状态 Node 并不是接口挂了而是认证凭证过期了。第三方接口的 Token 有效期各不相同有的 1 小时有的 24 小时而且部分平台不允许自动刷新。探测器检测到 401 时会立即把状态标记为auth_failed后续的路由层就会屏蔽这个 Node。问题是如果 Agent 被屏蔽掉一个关键工具它可能会“硬着头皮”选择另一个可用工具结果用户问题没有得到精确解决。这提醒我们auth_failed状态不能只依赖探测被动发现还要在凭据管理侧做一个提前预警。我们的做法是给每个认证配置加一个expire_warning时间在 Token 过期前 10 分钟就触发一次手动刷新流程刷新成功后主动探测一次确保状态在进入业务高峰期前变为green。如果凭据刷新失败还有一个细节不要把老的可用状态覆盖成失败态太早。因为有些第三方系统对刷新限制很敏感重试太频繁反而会被封禁。我们设置了一个冷却期auth_failed状态下 5 分钟内不重复探测同时通知值班人员去检查。4.3 超时设置不合理探测要么太慢要么误伤超时参数一开始统一设置结果两个系统差异巨大。内部 Redis 查询 10ms 就能返回某些外部报表 API 正常也要 1.5 秒统一超时 1 秒导致外部系统被大量误判为不可用。后续我们把超时设计成 Node 级别的配置基础默认值 1 秒但允许单独指定probe_timeout。同时探测判断不再只看“是否超时”还会看“是否在合理时间窗内”。合理的超时判断逻辑是如果接口在probe_timeout内没返回但在一个可容忍的安慰窗口内返回了那么不要立即标记为red而是标记为yellow只有连续两个探测周期都超时才真正降级。这个“两次确认”机制有效减少了偶发抖动对 Agent 决策的影响。不过一定要设置一个绝对上限比如yellow状态最多持续 3 个周期否则又会走向另一个极端——探测永远在等待恢复。4.4 不同模型的工具描述格式兼容团队后来接入的不只是 OpenAI 兼容接口还有本地部署的 Qwen 和 Claude 格式。不同平台对工具描述的要求有细微差异OpenAI 要求parameters字段Claude 要求input_schema字段有些模型对工具描述里的枚举值严格有些允许宽松匹配。如果只维护一套 schema就可能在某个模型上工具名乱了或者参数校验失败。我们写了一个适配层把注册中心的统一 schema 渲染成不同平台的格式。核心数据还是那一份 JSON Schema通过一个renderer函数转换。另外每个平台可能会有默认值处理差异所以适配层还负责填充默认值比如把空字符串转成nullable。这个踩坑让我意识到Agent-Reach 这类底座在设计时一定要把“多格式兼容”当作一等需求否则后面每接一个新模型都要改核心代码。5. 落地效果与实际体会Agent-Reach 上线后在两个业务域产生了比较明显的变化。首先是客服工单域Agent 工具调用成功率从 87% 提升到 97%用户反映“AI 开始能听懂人话并且办成事”其次是内部知识库问答域过去有几个知识库接口经常超时Agent 会偶尔给出“我不确定”或者读到旧数据现在探测层会在接口超时前就提示模型换通道回答准确率提升了约 6 个百分点。我个人最满意的其实不是数字而是排查效率。之前一个 Agent 调用失败要翻模型日志、网关日志、接口服务日志才能拼凑出原因。现在打开 Agent-Reach 的观测面板能直接看到每次失败的失败原因分类——认证失败、依赖失败、超时、网络错误——大约 30 秒就能定位具体环节。这对于一个几十个 Node 的系统来说省下的何止是时间。最后分享一个后续可以扩展的方向Agent-Reach 现在做的是“工具触达状态”的实时维护下一步我们准备把“业务数据是否满足 Agent 任务条件”也纳入范围。举例来说某物流查询工具接口正常但当前没有该订单的物流轨迹这时 Agent 再去调用虽然不会报错但结果也是空。如果把这种“业务语义上的触达”也做成可探测、可反馈的状态Agent 的质量还能再上一个台阶。这个思路我们已经开始验证期待下一次有机会再把新的踩坑记录整理出来分享。