最近在重构团队内部的 Agent 底座时我们把很多精力花在了“模型能说出来什么”上直到被生产环境里一堆乱七八糟的工具调用问题逼疯才意识到一个被反复忽视的短板模型知道哪些工具存在、能拿到哪些能力、调得了哪些接口这个“可达范围”才是真正决定 Agent 上限的东西。于是我们花了三周时间做了一个专门解决“可达性”的组件内部代号就叫 Agent-Reach这篇文章就把它的设计思路、核心实现和踩坑过程完整记录下来。Agent-Reach 本质上是一个位于 Agent 与外部工具/数据服务之间的“能力通道层”。它不负责生成模型回复也不存储业务数据它只做一件事在正确的时间把正确且有限的工具描述、调用路径和权限边界摆在模型面前。适合正在做 AI 应用、智能体框架尤其被“工具越来越多、模型越调越傻”这个问题困扰的工程师和架构师参考。1. Agent-Reach 到底要解决什么问题1.1 工具越多Agent 越傻先说一个很反直觉的实践现象给 Agent 暴露 5 个工具的时候它调用得又准又稳给暴露到 20 个开始偶尔选错给暴露到 50 个以上错误率会明显上升甚至出现“明知有正确工具却偏要硬编一个参数凑给另一个工具”的迷惑行为。问题不在模型本身而在于当前的实现方式太粗暴。大多数 Agent 框架会把所有工具的 name、description、parameters JSON Schema 一股脑塞进 system prompt。模型注意力窗口是有限的工具描述越长越多彼此干扰就越严重。尤其两个工具描述长得像、功能有重叠时模型经常会陷入“选择困难症”或者被某个更靠前、描述更花哨的工具带偏。我当时总结出一个经验工具的可达性不等于工具列表的长度模型最需要的永远是被压缩过的、跟当前任务最相关的几项能力。1.2 从单机小工具到企业级场景的需求变化早期做一个客服问答 Agent工具就三四个查订单、查物流、查优惠券全量注入完全没问题。但当我们把 Agent 接到团队内部的多个系统上时情况立刻失控了。这些系统的 API 数量不小而且归属不同团队维护。有的团队今天加了一个新接口明天改了一个参数名有的接口只在特定业务线有意义有的工具是高权限操作绝不能在任何对话场景下都开放。如果还靠人工维护一个大而全的工具清单让 Agent 每次对话都拿全量去选不仅模型负担大维护人员也会疯掉。所以 Agent-Reach 最开始的目标不是做一个花哨的 Agent而是解决一个很实际的问题如何在服务数量动态变化、权限层级复杂、模型不能吃下全部上下文的情况下仍然保证 Agent 能稳定、安全、低延迟地触达它该用的能力。1.3 我给自己定的四个设计目标在动手写代码之前我先把需求收拢成了四条硬性设计目标后面的架构都是围绕这四条展开的延迟敏感性工具筛选不能让用户多等路由决策最好控制在毫秒级别不能在 Agent 主链路里塞一个重量级大模型 rerank。故障隔离某个外部服务挂掉不能拖着整个 Agent 一起超时必须能快速熔断并把错误变成模型可读的提示。权限收敛工具能否被调用不只取决于模型“想不想”还要取决于当前用户、当前会话、当前上下文允许不允许。可组装性不能和具体某个 Agent 框架强绑定不管是自研框架、LangChain 还是直接调 OpenAI Function Calling都能以类似的接入方式使用。这四个目标基本决定了 Agent-Reach 不会去碰“生成回复”这件事它只做接入、筛选、路由、调用、兜底像一个基础设施层。2. 整体架构与核心设计2.1 五种角色的拆分在 Agent-Reach 内部我按职责拆了五个角色这个拆分不是拍脑袋想出来的是源于线上排查时的真实痛点以前的工具调用代码把“选哪个工具”和“怎么调工具”耦合在一起出了问题根本分不清是模型选错了还是接口传参错了。Registry工具注册中心管理所有工具的元数据、版本、可见范围。谁注册了谁、什么时候上线都由它说了算。Router路由选择器基于当前对话语义和提前建立的工具索引选出候选工具列表。Resolver解析执行器负责把模型的参数补全、校验、映射成真实 API 请求。Guard权限守门员拦截所有调用请求校验用户身份、会话权限、操作风险等级。Observer观测器记录每一次“从意图到工具调用”的完整链路包括耗时、命中工具、失败原因。这样的五个角色摆出来以后一个请求从进来出去的路径非常清晰先走 Guard 做前置校验再走 Router 做工具筛选Resolver 负责跑通真实调用Observer 在旁边全程记录。2.2 为什么是“注册 语义路由”而不是全量注入我先说为什么不能继续用全量注入。全量注入本身不是绝对错误在工具少于 10 个、描述差异很大的场景下它简单直接。但一旦工具数量超过几十个全量注入会带来两个很难接受的问题模型把大量注意力花在不相关的工具描述上导致对用户意图本身的理解变弱。某些工具的参数 Schema 特别长比如一个接口有 30 个字段全量塞进去直接吃掉宝贵的上下文空间。Agent-Reach 的设计思路是“预选 精选”。先用轻量级的语义匹配把几十个甚至上百个工具快速筛到 3 到 5 个候选再把这几个候选的完整描述注入模型。本质上相当于给模型做了一次“信息降噪”。这里有一个常见的误区很多人会认为筛选应该直接用大模型来做让模型自己选工具。这个我强烈不建议在主链路里做因为大模型一次的延迟都在数百毫秒甚至几秒再做一轮筛选用户体感直接就垮了。更合理的做法是提前对工具描述做向量化索引查询时用用户问题做一次快速的向量召回再用关键词规则或轻量分类模型做兜底。2.3 与现有框架的兼容策略Agent-Reach 的定位不是一个“新框架”而是一个可以插进现有框架的模块。对外它暴露的东西很简单输入是一个包含用户意图和上下文的请求输出是一组可执行工具调用。因此在接入 LangChain 时可以把 Agent-Reach 包装成一个自定义 Tool Retriever接入 OpenAI Function Calling 时可以把”候选工具列表“直接拼进 functions 参数接入自研框架时也只需要在调度层加一个中间调用。这样做有一个明显好处团队未来就算换了 Agent 框架Agent-Reach 这一层基本不用动工具注册信息、权限配置、路由索引都照样生效。这也是我为什么坚持把“工具管理”和“Agent 对话逻辑”拆开的原因。这两个东西的生命周期完全不同不该被绑死在同一个类里面。3. 核心实现让工具真正“可达”3.1 三个核心抽象Catalog、Endpoint、Policy技术落地时我把 Agent-Reach 内部最核心的抽象收敛成三个Catalog工具目录。一个工具本质上是一条带元数据的记录里面包括唯一名称、描述、可见范围、版本、所属域。Endpoint真实调用入口。描述协议类型HTTP/gRPC/本地函数、地址、参数映射、认证方式。Policy调用策略。包括谁能调用、什么上下文允许调、是否需要人工审批、失败后的动作是什么。这三个抽象是递进的关系Catalog 决定“Agent 知不知道有这个能力”Endpoint 决定“调得通调不通”Policy 决定“该不该调”。以前很多项目只做了 Endpoint忽视了 Catalog 和 Policy所以工具一多就乱。3.2 工具注册表的数据结构实际写代码的时候我没有搞特别复杂的东西直接用 Pydantic 定义了一个带校验的工具模型。关键是name 和 description 的写法在入 Catalog 之前就要规范化因为后面 Route 依赖的就是这两个字段。from pydantic import BaseModel, Field, field_validator from typing import Any, Dict, List class ToolSchema(BaseModel): Agent-Reach 的工具元数据模型 name: str Field(description工具唯一名称如 order.query) description: str Field(description工具职责描述控制在120字以内避免和其他工具语义重叠) domain: str Field(description所属业务域如 order / logistics / coupon) input_schema: Dict[str, Any] Field(descriptionJSON Schema 参数定义) endpoint_id: str Field(description绑定的端点ID) visibility: str Field(defaultinternal, descriptioninternal / restricted / public) version: str Field(default1.0.0) enabled: bool Field(defaultTrue) tags: List[str] Field(default_factorylist) field_validator(name) def validate_name(cls, v): if len(v.split(.)) 2: raise ValueError(工具名建议命名空间格式域.动作) return v field_validator(description) def validate_desc(cls, v): if len(v) 120: raise ValueError(工具描述过长请压缩到120字以内) return v这里有两个容易踩的细节。第一个是工具名必须带命名空间比如“order.query”、“logistics.track”而不是一个笼统的“query”。因为 Router 做规则兜底的时候需要靠前缀快速过滤掉无关工具。第二个是描述不能超过 120 字太长的描述不仅浪费 token还会导致 embedding 向量区分度下降经常把两个不同功能的工具揉到同一个语义区域里。3.3 路由选择向量召回 规则兜底 Top-K 微调路由流程我分成三步把用户当前输入包括最近几轮对话摘要转成一个查询向量。在工具描述向量库里做相似度召回取 top 10。再用一个非常轻量级的规则集对 top 10 做过滤和排序最终给模型 3 到 5 个候选。为什么要做二次过滤因为纯向量召回经常有两个毛病召回的相似度普遍都很低时说明没有特别匹配的工具这时候宁可让 Agent 诚实回答“没有这个能力”也不要硬选一个最接近的上去乱调另外向量召回偶尔会被同义描述误导比如“物流轨迹”和“订单揽收状态”在语义上很像但实际是两个系统规则集在这里能帮忙做硬性纠偏。Top-K 的选择也有讲究。我一开始把 K 设为 5结果发现模型偶尔会忽略最相关的工具反而选择列表里描述更“诱人”的。后来我把工具列表的排序规则从“按相似度降序”改成“相似度 日志调用频次的加权排序”效果好了很多。实现起来就是维护一个最近 7 天的工具调用成功次数计数用对数形式把高频工具稍微往前挪一点。def rerank(candidates: list[dict], usage_stats: dict[str, int]) - list[dict]: 对召回结果做二次排序相似度为主调用频次微调 from math import log1p scored [] for c in candidates: freq usage_stats.get(c[tool_name], 0) # 相似度占 80% 权重调用频次占 20% 权重避免冷门工具完全没有曝光 hybrid 0.8 * c[score] 0.2 * min(0.1 * log1p(freq), 1.0) scored.append((hybrid, c)) scored.sort(keylambda x: x[0], reverseTrue) return [c for _, c in scored[:5]]这个加权逻辑是我自己在实践中反复调过参数的不一定适合所有场景但它解决了一个特别真实的问题新上线的工具由于还没有历史调用记录会被模型略微冷落但也不能让新工具直接排最前因为可能描述得不够准确先让它出现在候选区等用户用几次之后再自然上位。3.4 执行链路设计把失败变成模型可读的信息工具被选中之后剩下的执行链路同样不能掉链子。传统做法是模型输出一个 JSON里面带 tool_name 和 argumentsAgent 框架直接拿着参数去调接口。这里有个很大的隐患外部接口返回的错误五花八门很多框架不会对这些错误做语义包装直接把底层报错抛回模型模型很容易被误导。Agent-Reach 在处理上做了三层包装第一层网络错误统一翻译成“服务暂时不可用请告知用户稍后重试”。第二层业务错误保留状态码和业务 message拼成紧凑字符串返回模型。第三层如果连续失败次数超过阈值直接触发熔断并在这一轮对话里主动不再给模型推荐这个工具。这层处理极大提升了线上稳定性。有一次下游物流服务半夜升级接口返回了大量 502如果直接把这些原始报错丢给模型模型会一本正经地跟用户说“物流系统出现了 com.xxx.Exception”简直灾难。包装之后模型只会说“暂时查不到晚点再问我”并且下次路由时不再把这个工具排进候选。4. 实操把 Agent-Reach 接入现有 Agent4.1 准备工作定义你的第一个工具我先拿最常见的“查天气”来演示虽然简单但整条链路是完整的。在 Agent-Reach 里工具定义有两种方式一种是在工程代码里用 Pydantic 模型定义另一种是通过 YAML 配置文件热加载。我个人更推荐先用 YAML 做原型稳定后再固化到代码里因为改配置比改代码快得多。# tools/weather.yaml name: weather.query description: 查询指定城市的实时天气情况包括温度、湿度、风力预报 domain: weather visibility: public version: 1.0.0 endpoint: protocol: http url: https://api.example.com/weather method: GET auth: type: apikey header_name: X-Api-Key input_schema: type: object properties: city: type: string description: 城市中文名或拼音 days: type: integer description: 预报天数1-3 required: - city additionalProperties: false你可能会发现这里没有直接把 API Key 写在文件里而是用 auth 引用了一个凭证 ID。这是刻意为之配置文件要能进 Git但不能把真实密钥带进去。Agent-Reach 在启动时会从环境变量或密钥管理服务里解析认证信息这样即使配置文件泄露也只是暴露一个占位符。4.2 建立索引并快速验证路由配置文件写好后需要把它注册进 Catalog 并写入向量索引。这一步在 Agent-Reach 里是一条命令agent-reach-cli register --config tools/weather.yaml agent-reach-cli rebuild-index --model text-embedding-3-small索引重建这个操作我特意设计成显式命令而不是每次启动自动做。原因很简单embedding 模型调用有成本而且批量重建时如果工具数量在几千耗时能到几十秒放 Agent 启动链路里会拖慢发布速度。所以平时只在新增或修改工具描述后执行一次。验证路由效果也很直接跑一个交互式查询agent-reach-cli route --query 明天杭州热不热期望输出repo root: tools/weather.yaml tool candidates: 1. weather.query (score0.913, sourcevector) 2. weather.alarm (score0.731, sourcevector)这里“sourcevector”表示是向量召回命中的。如果某个工具是通过关键词规则命中的会标成 sourcerule这在排查时候很好用。4.3 在 Agent 主链路里调用Agent-Reach 在 Agent 主链路里非常轻。下面这段是把它接入一个最简单 OpenAI Function Calling 流程的示意import openai from agent_reach import ReachClient client ReachClient.from_config(./reach_config.yaml) # 1. 输入用户消息Agent-Reach 返回候选工具 candidates client.route(明天杭州热不热) # 2. 把候选工具转换成 OpenAI Functions 格式 functions [c.to_openai_function() for c in candidates] # 3. 正常走模型调用 response openai.chat.completions.create( modelgpt-4o, messageshistory, functionsfunctions, function_callauto, )这里最核心的一点是传给 OpenAI 的 functions 列表不再是几十个而是 Agent-Reach 精选出的三五个。请求体大小直接小了一个数量级模型输出的准确率肉眼可见地提升。我在一次测试里同样问题下工具调用错误率从原来的 18% 降到了 4% 左右。很多现成框架的用户会纠结“要不要让 Agent-Reach 帮我直接执行函数”我的答案很明确不要。Agent-Reach 负责把“模型应该考虑什么”这件事做好至于真正的执行最后还是要 Agent 框架自己完成。因为 Agent 框架通常有自己的消息历史管理、human-in-the-loop 机制如果 Agent-Reach 强制接管执行反而破坏现有生态。5. 踩坑记录与排查速查表5.1 工具描述太长导致语义漂移这是我遇到的第一个坑。一开始写工具描述时总想把所有细节都写进去比如“查询天气支持国内主要城市数据来自某某气象平台返回格式包括温度、湿度、气压、紫外线指数、7 天预报……”。结果 embedding 做出来之后这个工具和“查询水质”、“查询空气质量”几乎分不开。后来我把描述改成类似“查询指定城市实时天气温度、湿度、风、降水”并且把额外信息全部塞进参数项的 description 里。向量召回效果立刻变好。工具描述的核心是职责边界不是实现细节。5.2 两个工具语义重叠模型反复选错有一个真实案例我们有“订单查询”和“订单列表查询”两个工具。前者按订单号查单件详情后者按时间范围查订单列表。从业务上讲它们完全不同但模型经常用错。我最后用了两个手段解决。首先修改 description分别强调“只能按订单号查询单笔订单”和“只能按用户和时间范围查询列表”其次在 Catalog 里加了 disable_dependency 限制当路由候选同时出现这两个工具时强制靠参数类型过滤用户输入包含订单号则只保留前者用户输入包含日期范围则只保留后者。5.3 外部服务超时拖垮整个 Agent这个问题几乎每家做 Agent 的公司都会遇到。某个下游接口偶尔响应 5 秒导致模型调用这一个工具时整个用户请求就定格了 5 秒。这几乎是不可接受的体感。我在 Agent-Reach 的 Endpoint 层做了三件事设置默认超时 2.5 秒超过一次直接返回“服务繁忙”包装消息连续 3 次失败则把该工具状态置为 degraded。degraded 状态下Router 会主动把该工具从候选里移除或者放到最后。下一次 Agent 再遇到同样问题就直接告诉用户现在查不了而不会傻等。5.4 参数 Schema 频繁变化下游团队经常加接口参数比如原来“创建订单”只要一个商品 ID后来又要求必须传门店 ID。如果 Agent-Reach 的 Catalog 里 Schema 没更新模型就会持续少传参数然后接口校验报错。我建议给每个工具维护一个 version 字段并且把 Schema 变更当成一次发布行为变更后必须重建索引。为了防止“改完工具忘了重建”我写了一个 git pre-push 钩子检测到 tools/ 目录下有文件变更时强制要求本地重建索引并跑一次 route 冒烟测试。我把这些排查经验整理成一张速查表团队新同学基本能照着定位现象可能原因排查手段模型选错工具描述重叠、排序干扰检查候选分数、对比工具描述向量相似度候选列表为空索引未重建执行 rebuild-index 验证索引数量调用接口报错参数缺失或 Schema 过期对比 Catalog 版本与实际接口 OpenAPI 文件工具一直不被选中无历史调用记录导致排序靠后查看 routed 日志考虑手动提高初始权重响应延迟过高下游接口慢查看 observer 输出的 p99 耗时检查熔断状态这张表可能看着简单但每一条背后都是线上真实事故换来的教训。特别是“候选列表为空”这个情况第一次遇到时我排查了很久最后发现是部署新环境时忘了执行索引重建命令。6. 可观测性与安全实践没有被记录的能力等于不存在6.1 每一次“可达”都要有痕迹Agent-Reach 的 Observer 从设计之初就不是一个可有可无的日志模块而是把它当成一个独立的数据源来做。每次路由请求输出一条结构化事件内容包括会话 ID、用户 ID、输入摘要、候选工具列表及各工具分数、最终选中工具、调用结果状态、耗时。这些数据最大的价值不是给开发人员看控制台日志而是用来做两件事分析工具覆盖情况。每周跑一次“所有注册工具的被选次数和被成功调用次数”能快速看出哪些工具是僵尸工具、哪些工具虽然被频繁选中但成功率极低。反推模型偏见。如果观测到某个工具出现次数异常高但用户反馈并不好很可能不是工具好用而是描述写得过于显眼把模型带偏了。有一次我通过观测数据发现“订单催单”工具被选中的概率是其他类似工具的三倍点进去看上下文才发现用户只是说“帮我看看快递怎么还没到”模型就自动动了催单接口。这在没有观测数据的情况下几乎无法察觉因为从单次对话看模型调用的工具和用户意图似乎沾边。6.2 可达范围的边界就是风险边界Agent-Reach 里每个工具都可以设置一个 visibility 和 policy我强烈建议把“高权限工具”默认设为 restricted。比如“退款审批”、“删除用户”、“发送营销短信”这类的操作即使是模型认为最合适的工具也必须经过 Guard 的二次校验。具体实现上我在 Guard 里加了一个简单的上下文检查器如果当前工具是 restricted 状态就强制走一轮“用户确认”动作而不是让模型直接执行。别觉得这个流程重实际经历一次“模型误调用发券接口导致资损”的事故之后你会明白一个硬性的“Permission denied”返回是多么让人安心。6.3 后续演进从单 Agent 到多 Agent 协作Agent-Reach 短期内解决的是单 Agent 的工具可达性问题但长期来看它完全可以扩展成一个多 Agent 服务发现层。当系统里有多个 Agent 分别负责订单、售后、营销时它们之间的能力也可以像“工具”一样注册进 CatalogRouter 路由到的不再是一个 API 而是一个 Agent。我已经在内部做了这个方向的实验把另一个团队的“售后分析 Agent”作为一个带特殊 endpoint 的工具注册进来模型在对话中可以通过 Agent-Reach 触发它并拿到结果摘要。这种做法的好处是各个 Agent 的边界仍然清晰又不会把对话系统变成一个层层调用的混乱网状结构。基于这几次实战我个人对做这一类基础组件的最大体会是不要贪多把每一条调用链路都做透明把每一个失败都变成模型能理解的话。Agent-Reach 不是什么玄乎的设计它只是把“模型该知道什么”这件事从感觉变成了工程这比在后端堆一大堆漂亮但说不清用途的抽象有用得多。