1. 把能碰到和能做成拆开Agent-Reach 到底管哪一段Agent-Reach 这个词直译过来就是智能体的触达能力。我第一次看到它的时候脑子里冒出来的第一反应不是某个具体框架而是一类非常具体的问题一个再聪明的 Agent如果伸不出手去够外部的东西它就只是个会聊天的模型。能写代码、能读文件、能查订单、能发消息、能改配置——这些动作背后都有一层东西在支撑这层东西就是 Reach。不同团队对它的叫法不一样有人叫工具层有人叫插件系统有人叫 function calling 编排但本质上说的都是同一件事让 Agent 从一个只会说话的东西变成一个能对外部世界产生作用的东西。这篇文章想聊的就是这一层。它适合两类人看一类是刚开始给 Agent 接工具、被各种乱七八糟的问题折磨的工程师另一类是把 Agent 功能接上了、以为万事大吉结果上线之后发现调用成功率上不去、用户天天骂它又说错了的人。我会把 Reach 这一层拆成注册、权限、结果处理、观测四块来讲中间会带上我自己踩过的坑和一些不太常规但很管用的做法。需要提前说明的是下面涉及具体实现的部分都是基于这类系统的常见实践做的合理补充不同团队的技术栈不一样思路可以借鉴代码别照抄。1.1 一次看起来成功了的调用先讲个特别典型的场景。用户在对话里说帮我看看上周那笔订单到哪了Agent 判断该调用query_order工具参数写得也对调用返回 HTTP 200日志里打了一个绿色的成功。然后 Agent 回复您的订单已发货预计明天送达。听起来没问题对吧但如果我告诉你这个query_order返回的其实是三个订单Agent 只读了第一个或者返回体里status字段的值是SHIPPED_PENDING_REVIEWAgent 把它当成了已发货再或者这个工具本身有 3 秒超时网关那边其实已经超时降级返回了一个空对象程序判断只要不抛异常就算成功——那这次成功就是彻头彻尾的假象。这就是我想强调的第一个核心判断Reach 这一层的失败绝大多数不是调用失败而是调用成功了但结果没被正确理解。前者你能从监控里看到红色的错误曲线后者什么都看不到只有用户在骂。所以当我们讨论 Agent-Reach 的时候不能只盯着工具能不能调通必须把注册可达、权限可达、结果可达这三件事分开看。1.2 Reach 的三层含义注册可达、权限可达、结果可达我把这三层拆开定义一下后面几节基本就是围绕它们展开的。注册可达指的是这个工具存不存在、模型知不知道它、调用它的路径通不通。这一层出问题最容易发现比如工具没注册进列表、名字写错了、参数 schema 校验直接拒了、网络不通。这一层的错误率一般是最低的因为它有明确的是/否。权限可达指的是就算工具存在、路径也通这次调用到底该不该被执行。这里的判断维度很多——调用方有没有这个权限、这个操作有没有副作用、要不要人工确认、这笔操作是不是重复的。这一层是事故高发区也是最容易被产品经理忽略的一层。一个删除文件的工具如果没做确认就直接执行了注册可达做得再完美也没用。结果可达指的是工具返回的原始数据经过处理之后模型到底能不能正确理解。这一层最隐蔽也最考验工程功力。原始返回可能是 200KB 的 JSON、可能是一个嵌套五层的数据结构、可能是一个只有错误码没有错误信息的失败响应。你不做处理直接塞回上下文模型要么被淹没要么被误导。把这三层分开之后排查问题就有了顺序。我一般是这样定位的先看调用日志确认注册可达没问题再看权限判定日志确认权限可达没拦住最后把返回的原始 payload 和处理后的 payload 都打出来对比看结果可达这一层丢了多少信息。按这个顺序走八成的问题能在十分钟内定位到具体是哪一层。提示三层里最容易做假的就是第一层。因为工具能调通、返回 200 是个强正反馈很容易让人误以为整条链路都健康。建议从一开始就把结果可达的验证指标单独埋出来别和调用成功率混在一起。2. 工具注册表三个月后不失控的设计方式工具数量从 3 个涨到 30 个的过程往往比想象中快得多。前两周你还在小心翼翼地写每一个工具描述三个月后你面对的是一个几百行没人敢动的配置文件里面躺着十几个名字相似、功能重叠、谁写的都记不清的工具。我可以很负责任地说Agent-Reach 这一层后期的维护成本九成来自注册表的失控。所以这一节我想聊聊怎么从一开始就把它设计得能活久一点。2.1 工具描述是写给模型看的接口文档大多数人写工具描述的方式是复制粘贴后端接口的注释或者写一句查询订单信息。这种做法在工具只有三五个的时候勉强能用一旦工具多了模型挑错工具的概率会陡增。原因是这样模型选工具靠的是语义匹配它只能看到工具名和描述这两样东西。如果描述里没有明确的什么时候该用、什么时候不该用模型就只能靠猜。我给你一个我一直在用的描述模板结构是做什么 什么时候用 什么时候别用 关键约束{ name: query_order, description: 按订单号精确查询单个订单的状态和物流信息。仅在用户明确给出了订单号形如 SO- 开头的 16 位字符串时调用。不要用它来搜索用户的订单列表或按商品名查订单那类需求应该用 search_orders。返回的是单条记录不是数组。, side_effect: read, timeout_ms: 3000, idempotent: true }这段描述里什么时候别用那半句是关键。我实测下来加上明确的负向约束之后工具误选率能降一大截。很多人不舍得在这里花时间觉得描述写得长会浪费 token但你想想一次误调用带来的重试、错误回复、用户追问成本比多写那两句话高得多。还有一点描述里不要出现内部黑话和缩写。像调用 OMS 的 queryV2 接口拉取 SO 主表这种描述模型看不懂而且它会把OMS当成一个实体名到处乱用。描述要写成给一个刚入职的同事看的说明书而不是给老员工看的便签。2.2 参数 schema 是契约不是装饰参数校验这件事我见过两种极端。一种是完全不做校验模型传什么就往下传什么后端抛错再说另一种是校验做得极严多一个字段就拒导致模型反复重试同一个错误。比较靠谱的做法是必填字段严格校验可选字段宽松处理并给默认值。校验的目的不是为了拒绝模型而是为了在参数有问题的时候给出人能看懂、模型能自愈的提示。def validate(args, schema): missing [k for k in schema.get(required, []) if k not in args] if missing: return { ok: False, error: f缺少必填参数 {, .join(missing)}, hint: 请从用户原话中提取订单号格式为 SO- 开头加 14 位数字 } for name, spec in schema[properties].items(): if name in args and spec[type] string and not isinstance(args[name], str): args[name] str(args[name]) # 模型经常把数字写成数字类型 return {ok: True, args: args}注意那个把数字转成字符串的小处理。模型传参时把12345写成12345是非常高频的事情如果你 schema 里写的是 string 类型又严格校验就会频繁失败。这种可容忍的类型偏差我一般会主动做转换而不是让整个调用失败。2.3 命名、分组与工具数量膨胀工具一多命名规范就变成硬需求。我的经验是三条动词开头 业务域做前缀 不用缩写。比如query_order、create_ticket、update_user_profile而不是orderQry、tkt_new、updProf。其次是分组。工具数量超过 15 个之后我强烈建议不要把全部工具一次性塞进模型的上下文。有两个原因一是上下文会被大量工具描述占满挤压真正有用的信息二是候选太多选错的概率直观上升。常见的做法是按场景动态挂载——用户问订单相关的问题就只挂载订单域的三五个工具进入另一个场景再换一批。具体怎么判断挂载哪一批可以是规则匹配也可以是先让模型做一次轻量的意图分类再按分类结果挂载。后者效果更好但多一次模型调用。如果业务对延迟敏感规则匹配就够了别过度设计。工具规模建议挂载策略主要风险1-8 个全量挂载基本无风险9-20 个全量挂载 描述严格区分误选率上升需盯紧20-50 个按意图分类动态挂载分类错误会连带选错工具50 个以上分层先选域再选工具链路变长延迟和失败点增加3. 伸手之前先过闸权限分档与副作用控制工具能调通之后下一个要面对的问题就是这次调用到底该不该放行。这一节的很多内容是从事故里学来的写出来可能有点啰嗦但每一条都有代价。3.1 只读、可写、需确认的三档划分我给所有工具都强制标一个side_effect字段只有三个取值read、write、destructive。read类的工具比如查询、搜索、获取详情可以自由调用不需要额外确认。这类工具占了绝大多数也是收益最高的部分。write类的工具比如创建工单、发送消息、修改配置我一般要求它们必须是幂等的或者至少带一个幂等键。这类工具可以自动执行但必须在返回结果里明确告诉模型这次操作已经生效了否则模型可能会重复调用。destructive类的工具比如删除数据、批量修改、转账扣款这类必须走人工确认。确认的交互设计有个小细节不要弹一个是否确认 Y/N的通用弹窗而是把即将执行的具体参数原样列出来让用户看。用户看到的应该是即将删除 ID 为 8821 的记录创建于 2024-03-11而不是是否执行该操作。前者用户能判断对错后者只能瞎点。def dispatch(tool_name, args, ctx): spec REGISTRY[tool_name] result validate(args, spec[parameters]) if not result[ok]: return result if spec[side_effect] destructive and not ctx.get(confirmed): return { status: need_confirmation, preview: render_preview(spec, result[args]), message: 该操作不可撤销请确认参数后继续 } return execute(spec, result[args], ctx)3.2 幂等键重试这件事没你想的那么便宜超时重试是 Reach 这一层的标配。但很多人只做了重试没做幂等结果就是一次超时变成两次执行。我见过最离谱的一个案例是消息发送工具超时之后自动重试了三次用户收到了四条一样的通知。我的做法是给所有write类调用生成一个幂等键规则是trace_id tool_name 参数哈希。同一个 trace 里如果出现完全相同的调用第二次开始直接返回第一次的缓存结果不真正执行。def build_key(trace_id, tool_name, args): payload json.dumps(args, sort_keysTrue, ensure_asciiFalse) return f{trace_id}:{tool_name}:{hashlib.md5(payload.encode()).hexdigest()}这里有个容易忽略的点幂等键必须包含参数。如果只用trace_id tool_name那么同一轮对话里用户先改 A 再改 B第二次调用会被当成重复请求直接吞掉用户会发现改了两次只有一次生效。这种 bug 特别难查因为日志里看起来一切正常。3.3 超时、熔断与降级返回超时时间怎么定我的一般做法是参考下游接口的 P99 延迟再乘个 1.5 倍取整到秒。比如下游 P99 是 800ms工具超时就设 1500ms。设太短会导致大量无谓超时设太长会把整个对话卡住——用户等一个 30 秒的回复体验是灾难级的。熔断这块我建议至少做一个简单的连续失败计数。同一个工具在 30 秒内连续失败超过 5 次就直接熔断返回固定文案该功能暂时不可用避免所有请求都去撞那个已经挂掉的下游。等 30 秒后自动半开放一个探针请求过去试探。关于超时之后返回什么这里有个细节值得说不要返回空对象或者 null。模型拿到{}之后往往会开始自由发挥编出一些看起来合理的内容。正确做法是返回一个明确的结构化失败并且带上升级提示{ status: timeout, message: 查询订单超时可能是系统繁忙, suggestion: 请告知用户稍后重试不要猜测订单状态 }最后那句suggestion是专门写给模型看的。它会显著降低模型在失败时的胡编概率这个技巧我用了很久效果很稳。4. 结果回来的那一段才是重灾区工具执行完了数据拿到了看起来大功告成。实际上从这一刻开始到模型给出回复之间是最容易丢信息的一段。这一节讲三个具体处理。4.1 原始返回的裁剪与结构化先说裁剪。一个查询接口返回 3000 行数据是完全正常的事情但你不能把 3000 行塞进上下文。我的做法是设置一个字符上限超出就截断并在截断处加上明确说明def shape(raw, limit4000): text json.dumps(raw, ensure_asciiFalse) if len(text) limit: return text return ( text[:limit] f\n[内容已截断原始长度 {len(text)} 字符。如需完整数据请缩小查询范围或分页获取。] )那个截断说明不是可选项。没有它模型会以为自己拿到了全部数据然后基于不完整的信息给出结论。有了它模型至少知道要去缩小范围。再说结构化。原始返回经常有很多对模型没用的字段——内部 ID、创建人、数据库时间戳、各种各样的状态码枚举。我一般会做一层映射只保留业务上有意义的字段把枚举值翻译成中文描述。比如status: 3改成status: 已发货。这一步看起来简单但能减少大量理解错误。4.2 把报错改造成模型能自愈的文本原始的技术报错比如HTTP 422 Unprocessable Entity或者一长串堆栈对模型来说基本等于噪音。它看不懂就只能随便编一个解释给用户。我的做法是把所有工具错误统一收敛成三个字段status机器可读的状态码、message一句人话说明发生了什么、suggestion下一步该怎么办。原始错误改造后的返回HTTP 401status: auth_failedmessage: 当前身份无权访问该数据suggestion: 告知用户需要重新登录不要重试HTTP 429status: rate_limitedmessage: 请求过于频繁suggestion: 等待 3 秒后重试一次仍失败则告知用户参数校验失败status: bad_paramsmessage: 订单号格式不正确suggestion: 请向用户确认订单号格式应为 SO- 加 14 位数字这张表基本覆盖了我遇到过的八成错误场景。关键在于suggestion里要写清楚能不能重试、要不要问用户、重试几次把决策给到模型比让它自己猜要靠谱得多。4.3 引用溯源让每条结论都能点到源头最后一个处理是溯源。当 Agent 基于工具返回给出结论时我要求结果里保留一个source字段记录这条数据来自哪个工具、哪个参数、什么时间。这不只是为了给用户展示来源更重要的是方便排错——当用户说你给的数据不对的时候你能立刻知道它是从哪次调用里读出来的。实现上不用太复杂在工具返回的结构里加一个固定字段就够了{ status: ok, data: { order_id: SO-20240311000821, status: 已发货 }, source: { tool: query_order, args: { order_id: SO-20240311000821 }, fetched_at: 2025-06-02T10:23:4108:00 } }这个字段在给用户展示的时候可以隐藏但在日志里必须有。吃过一次数据对不上但查不出原因的亏之后我就把这个字段设成了强制要求。5. 怎么判断 Reach 变好了指标、回放与常见反模式做完了上面这些接下来要面对的问题是我怎么知道现在这套 Reach 比上个月那套好如果只靠感觉最近回复准了不少那基本等于没有判断依据。5.1 值得埋的四个指标我不建议一上来就埋几十个指标看不过来。这四个是我一直在用的指标定义我的经验阈值工具选择准确率应选工具与实际所选一致的比例低于 90% 就要看描述参数一次通过率首次调用参数校验通过的比例低于 85% 要改 schema 提示有效结果率返回结果被模型正确使用的比例低于 80% 要查结果处理重复调用率同一 trace 内相同工具重复调用次数高于 1.2 要查幂等和提示其中有效结果率最难测我的做法是抽样人工标注每周抽 100 条标注这条回复是否忠实于工具返回。这个活儿枯燥但它是最能反映真实质量的指标。5.2 用评测集代替感觉变好了每次改动工具描述或者结果处理逻辑之后我都会跑一遍固定的评测集。评测集不用很大五六十条就够但要覆盖几类典型场景正常调用、参数缺失、下游超时、返回为空、返回歧义数据。评测集的题面要写清楚期望调用哪个工具、期望传什么参数、期望回复里包含什么关键信息。这样改完之后一跑就知道这次改动是净提升还是引入了回归。我从感觉变好了切换到跑一遍评测集之后最明显的变化是发现了好几次本来以为没问题的改动其实造成了退步。5.3 我踩过的几个反模式把全部工具一次性塞进上下文。工具超过 20 个之后误选率上升得很明显尤其是名字相近的工具。改成按场景动态挂载之后误选率降了不少。工具描述写成内部术语。有一段时间我图省事描述直接抄的后端注释结果模型经常把内部服务名当成业务实体回答里冒出一堆用户看不懂的词。后来统一改成用户视角的描述问题基本消失。报错直接把堆栈抛回去。这个坑我踩了不止一次。模型看到堆栈之后会尝试解读它然后编出一个听起来很专业的解释。现在所有报错都在网关层拦掉只保留结构化错误。没做幂等就开重试。这个前面说过了代价是被用户发现重复操作。这类问题修复成本很高因为已经产生的重复数据要人工清理。忽略空结果的语义。返回空数组到底代表查不到还是查询成功但没有数据这两个语义完全不同模型的处理方式也应该不同。我现在会强制要求工具在返回空集时显式带上reason字段。6. 几个我反复用到的取舍和小经验最后聊几个偏经验层面的东西都是这几年反复遇到的取舍没有标准答案只是我个人的做法。第一宁可多一层确认也别省那一步。刚做的时候总觉得让用户点确认很烦会降低体验。但真正上线之后你会发现用户对多问一句的容忍度远高于对它把我东西删了的容忍度。我现在对不可逆操作的判断标准很简单如果这个操作出错之后需要人工介入才能恢复那就必须确认。第二工具的数量要控制但别硬凑。我见过有人为了减少工具数量把三个功能硬塞进一个工具里用一个action参数来区分。这种设计模型理解起来更吃力参数也更容易传错。判断标准应该是功能语义是否一致而不是数量好不好看。第三日志要能还原整条链路。我现在所有工具调用的日志都带同一个 trace_id从模型决策、参数校验、实际执行、结果处理到最终回复一条 trace 全串起来。这个习惯救过我很多次尤其是排查那种偶发但说不清的问题时没有 trace 基本等于盲查。第四别指望模型会自己纠错到底。很多人在设计失败处理时默认模型会看到错误之后自己想办法。实测下来模型在错误场景下的表现比在正常场景下差很多它经常会在同一个错误上反复撞。所以错误返回里那句suggestion真的不是可选项它是在给模型指路。如果让我用一句话总结 Agent-Reach 这层的工作重点那就是把不可控的部分尽量收敛到可控的边界里。工具能调通只是起点真正决定这套东西好不好用的是权限闸门够不够严、结果处理够不够干净、失败返回够不够清楚。这三件事做好了Agent 的表现会稳定很多做不好工具接得再多也只是在放大错误的规模。