去年到现在我陆陆续续帮几个团队做过智能体落地有意思的是几乎每一轮复盘都落在同一个地方模型本身很少是瓶颈真正卡住业务的是够不着。用户问一句帮我把上周那批异常订单拉出来顺便通知一下负责的同事模型答得头头是道、流程拆得清清楚楚可到了真要查库、真要发通知的那一刻整条链路就断了。Agent-Reach 这个词最近被提得越来越多说的本质上就是这件事——让智能体从会聊天变成够得着把能力伸到模型参数之外的系统、数据和协作通道里去。我理解的 Agent-Reach 不是某个具体的库也不是某家厂商的专有功能而是一套围绕智能体触达能力的工程结构工具怎么被描述、意图怎么被路由到具体动作、执行时怎么做权限和稳定性兜底、结果又怎么被压缩回上下文窗口。这套东西说起来抽象拆开来看每一块都很具体而且每一块都有各自典型的坑。下面我按自己搭这套东西的顺序一层层讲清楚能抄的地方我会直接给配置和代码踩过的雷我也会把排查过程原样写出来。1. Agent-Reach 解决的到底是什么问题从会说话到够得着1.1 一个把问题暴露得最清楚的场景设想一个售后场景的智能体。用户说我上周买的那台机器好像坏了算了别修了能不能直接换这句话里藏着至少四个动作查出这个用户最近的订单、判断商品落在哪个保修政策下、核对是否满足换货条件、最后在工单系统里开一张单并把结果告诉用户。任何一个环节够不着回答就会退化成建议您联系客服——用户立刻知道这是个假智能体。我见过的最典型做法是把这四个动作硬编码成一个超长的提示词再把结果拼成固定话术。这版能演示但一上真实流量就露馅商品类目一变、政策一改、系统接口一调整提示词就要重写。更麻烦的是它没有失败路径接口超时了它还在那儿一本正经地编。Agent-Reach 要解决的正是这段最后一公里。它把模型能触达的外部能力显式地建模出来让模型只负责决定做什么而能不能做、怎么做、做失败了怎么办交给一层稳定的工程结构去兜。这个分工一旦立住你会发现提示词反而变短了因为大量边界逻辑被挪到了代码里而代码是可以测试、可以灰度、可以回滚的。1.2 大多数团队的第一版实现断在这三个地方我梳理过十几个失败的早期版本断点高度集中在三处。第一处是工具注册靠 if-else 堆。一开始只有三个工具写三个分支很自然等到二十个工具时路由逻辑变成了一坨意大利面而且模型完全不知道有这些工具存在因为它从来没在上下文里见过它们。这里的关键认知是工具不是给程序员看的接口而是给模型看的可选项它的描述质量直接决定路由准确率。第二处是权限用一个万能账号。为了图快很多团队给智能体配了一个几乎什么都能读写的服务账号。演示阶段没问题一旦接入真实数据就是事故预备役。Agent-Reach 里我把权限当成一等公民来处理每个工具、每个调用都要带上调用者身份和参数范围执行层做一次收口的策略校验。第三处是结果原样塞回上下文。某个查询接口返回了 300KB 的 JSON直接塞进上下文要么触发长度截断要么把 token 成本推到天上去。回流层要做的事情恰恰是压缩与摘要——这一步做得好不好直接决定整套系统的单位成本。1.3 Reach这个词的准确含义触达等于四件事的串联我把触达拆成四个环节每一个环节对应一类典型的失败现象。这张表我建议在方案评审时直接摆出来它能让讨论快速收敛。环节该做的事做不好时的典型表现描述把外部能力写成模型能理解的结构化说明模型不知道有这个工具或者选错工具路由从意图匹配到具体工具并消解歧义参数抽错、在多个相似工具间反复横跳执行鉴权、限流、重试、幂等与超时兜底重复下单、越权查询、接口雪崩回流把结果裁剪压缩成模型可消费的形式上下文爆掉、成本失控、答非所问四个环节里最容易被人忽略的是第一个。很多人默认工具描述写给自己看就行但在 Agent-Reach 的语境里描述就是产品界面。一个写得好的描述会把什么时候该用和什么时候绝对不要用都写清楚模型的误调用率能下降一大截这比后面调多少次提示词都管用。注意工具描述的受众是模型不是人类工程师。判断标准不是我能不能看懂而是一个没有任何业务背景的人读完能不能准确判断该不该调用、该传什么参数。2. 拆开 Agent-Reach 的内部结构四层能力模型2.1 接入层把外部世界翻译成统一契约接入层干的是化整为零再归一的活。外部系统千奇百怪有 REST 接口、有数据库、有消息队列、有内部 RPC它们的鉴权方式、错误码体系、返回结构全不一样。接入层要把这些统一成一份契约让上面的路由层不需要关心底下接的是什么。我在这一层最看重三件事。一是描述与实现分离工具的元信息用声明式的方式单独维护改描述不用动代码改代码不用动描述。二是副作用标注读操作和写操作必须显式区分因为它们的执行策略完全不同——读可以激进重试写必须谨慎并且要幂等。三是成本提示给每个工具打一个粗略的成本标签低成本的可以多调高成本的要有预算约束这一点在后面控制成本时会救命。一个可用的工具描述长这样{ name: query_order_status, description: 根据订单号或下单手机号查询订单当前状态与最近一次履约节点。, when_to_use: 用户询问订单进度、是否已发出、预计到达时间时使用。, when_not_to_use: 用户咨询退换货政策、发票、优惠券问题时不要调用本工具。, parameters: { order_id: { type: string, required: false, description: 订单号形如 SO-2024-00000通常 14 位 }, phone_tail: { type: string, required: false, description: 下单手机号后四位当用户没有提供订单号时使用 } }, side_effect: read_only, timeout_ms: 3000, cost_hint: low }注意when_not_to_use这个字段它不是可选项。我实测下来加上它之后一个和查订单高度相似的工具比如查物流轨迹的误调用率能降三成左右。原因很简单模型在相似选项之间摇摆时需要的就是一条明确的排除规则。2.2 路由层从一句话到一次确定的调用路由层的输入是一段自然语言意图输出是用哪个工具、传什么参数。这里有个反直觉的经验不要让模型直接输出最终参数而是让它先输出候选工具再由代码去抽取参数。原因是模型在选工具时判断力不错但在生成结构化参数时经常凭空捏造字段值。把这两件事拆开每一件都能单独优化和评测。消歧是路由层最费心思的部分。真实用户的话往往缺主语、缺关键标识比如那个单子怎么样了。这时候路由层要做的不只是匹配工具还要判断信息是否充分。信息不足时正确行为不是硬猜而是生成一个反问。很多团队把这步省了结果是智能体用错误的参数调了一堆接口最后给出一个自信的错答案这比直接说我不知道伤害大得多。我给路由层留了三个必须落地的机制候选打分与阈值截断分数太低就不调用转为反问、信息充分性检查必填参数缺失时触发追问、以及一次会话内的工具调用预算比如最多连续调三个防止死循环。第三个机制听起来粗暴但它挽救了至少两次线上事故。2.3 执行层所有脏活累活都在这里执行层是真正和外部系统打交道的地方也是稳定性问题的集中区。这一层需要处理的东西列出来能吓死人鉴权凭证管理、连接池、超时、重试退避、熔断、限流、幂等键、审计日志、脱敏。我一般把它们分成两类来对待。第一类是通用横切能力用统一的中间件实现所有工具共享包括超时、重试、熔断、日志、脱敏。这类东西千万别在单个工具里各自实现否则二十个工具就有二十套超时逻辑排查问题时痛不欲生。第二类是工具特有逻辑比如某个接口要求签名、某个接口有特殊的分页约定这些才放进工具自己的适配器里。一个我反复强调的原则是读操作允许激进重试写操作默认不重试。写操作的重试必须依赖幂等键而且幂等键要由执行层统一生成和透传不能指望上游系统自己识别重复请求。我吃过一次亏一次网络抖动触发了三次重试结果同一张工单开了三张用户收到三条通知场面相当尴尬。2.4 回流层把一卡车数据压成一句话回流层是最容易被低估的一层但它是成本和质量的分水岭。外部系统的返回往往是给程序看的字段多、嵌套深、体积大而模型的上下文窗口是稀缺资源。回流层要做的是把原始返回转换成回答当前问题所必需的最小信息集。我的做法是三层处理。第一层是硬裁剪按工具声明的字段白名单挑出需要的字段其余直接丢弃这一步能在零成本的情况下砍掉七八成的体积。第二层是分页与聚合长列表转成总数 摘要 前几条样例模型需要细节时再触发二次查询。第三层才是模型侧的摘要也就是让一个小模型把结构化结果转成一段自然语言这一层有成本所以只在前两层处理完还不够小的时候才启用。这三层的顺序不能反。我见过直接拿大模型去摘要 300KB JSON 的方案效果时好时坏成本还高得离谱。先用确定的规则砍体积永远比让模型去理解一堆冗余字段更划算。3. 从零跑通第一条 Reach 通道3.1 环境与依赖准备不要一上来就上全量搭这套东西最常见的错误是第一天就想着把公司所有系统接进来。我的建议是反过来先挑一个只读、返回量小、业务价值明确的外部能力把描述、路由、执行、回流这四层全部走通一遍哪怕只有这一个工具。跑通之后再复制你会发现第二个工具花的时间不到第一个的四分之一。环境上需要的东西不多一个能跑服务的运行时Python 或 Node 都行、一个配置存储初期用文件就行别急着上配置中心、一个日志出口。模型侧需要一个支持工具调用的接口。下面我用 Python 写最小闭环思路和语言无关。第一步是把工具描述组织成一个注册表。我不建议把描述散落在代码里而是统一放在一份清单中启动时加载校验import json from pathlib import Path class ToolRegistry: def __init__(self, path: str): raw json.loads(Path(path).read_text(encodingutf-8)) self._tools {} for item in raw[tools]: self._validate(item) self._tools[item[name]] item def _validate(self, item: dict) - None: required [name, description, when_to_use, parameters, side_effect] missing [k for k in required if k not in item] if missing: raise ValueError(f工具 {item.get(name)} 缺少字段: {missing}) if item[side_effect] not in (read_only, write): raise ValueError(f工具 {item[name]} 的 side_effect 取值非法) def all(self) - list[dict]: return list(self._tools.values()) def get(self, name: str) - dict: return self._tools[name]这段校验代码看着琐碎但它挡住的是最讨厌的一类问题某个同事新加的工具字段写漏了模型看到的是一个残缺描述于是开始乱调。启动时就报错远比线上猜谜强。3.2 路由与执行的骨架代码路由我分两步先让模型在候选工具里做选择再由代码做参数抽取和策略校验。下面这段是骨架重点是那个逐级降级的循环——它比一次性选一个工具鲁棒得多。def reach(intent: str, ctx) - dict: candidates router.rank(intent, ctx.registry.all(), top_k3) if not candidates or candidates[0].score 0.45: return {type: clarify, question: router.ask_back(intent)} for cand in candidates: tool ctx.registry.get(cand.name) args extractor.fill(intent, tool) if not args.complete: return {type: clarify, question: args.missing_prompt} decision policy.check(ctx.user, tool, args.values) if not decision.allowed: ctx.audit.log(policy_denied, ctx.user, tool[name], decision.reason) continue result executor.run(tool, args.values, ctx) if result.ok: return {type: answer, payload: reducer.shrink(tool, result.data)} return {type: fallback, message: 暂时没能取到相关信息你可以换个说法再试一次。}有三处细节值得展开。score 0.45这个阈值不是拍脑袋定的我是拿一批真实问句做标注画出准确率随阈值变化的曲线选了一个准确率高、拒答率还能接受的折中点你们自己的语料上这个值大概率不一样。policy.check放在参数抽取之后是因为它常常需要看具体参数值才能判断比如同一个查询工具查自己的订单可以查别人的就不行。reducer.shrink是回流层的入口它的职责单一就是缩小体积。3.3 用三条测试用例验证够得着骨架跑起来之后别急着加工具先用三条用例把链路验证扎实。第一条是正常路径信息完整、工具匹配、返回正常看能不能一路走到答案。第二条是信息缺失只说那个单子看是否正确触发反问而不是瞎猜一个订单号。第三个是执行失败把下游接口的超时设成 1 毫秒人为制造失败看是否走到降级话术而不是抛异常或者编造答案。第三类用例最容易被忽略但它是区分能演示和能用的关键分界线。我习惯在本地环境加一个故障注入开关能强制某个工具超时、返回空、返回超大 payload、返回 500四种故障各跑一遍。这四遍跑完你对这条通道的信心会完全不一样。提示把执行失败当成一等测试场景而不是异常处理的分支。真实环境里下游的失败率远比你想象的高。4. 我在并发、超时和幂等上踩过的坑4.1 超时预算的分配问题第一个坑很隐蔽。我给单个工具设了 3 秒超时觉得挺合理结果线上偶尔出现 12 秒才返回的情况。查下来才发现路由层为了消歧会并行调用几次模型每次自己也有超时几次叠加再加上工具本身的重试总耗时就成了乘法关系。修法是把超时当成预算来管理而不是给每个环节单独设一个数。一次用户请求分配一个总预算比如 8 秒路由层花掉的要在执行层的预算里扣掉。实现上很简单就是往下传一个 deadline 时间戳每个环节开始前先检查剩余时间不够就直接降级。class Budget: def __init__(self, total_ms: int): self.deadline time.monotonic() total_ms / 1000 def remaining_ms(self) - int: return max(0, int((self.deadline - time.monotonic()) * 1000)) def take(self, want_ms: int) - int: return min(want_ms, self.remaining_ms())改完之后最坏情况下的耗时被压到了预算以内用户感知从卡住变成了想了想然后给了个降级答案体感差异非常大。4.2 重试导致的重复副作用前面提过一次工单开三张的事故这里把完整的排查链路写一下因为它的推理过程比结论更有价值。现象是用户收到三条重复的通知时间戳差了不到两秒。第一反应是通知服务有问题但查通知服务日志发现是三次独立请求都带着不同的请求 ID。顺着往上查发现是工单系统的调用被重试了三次。为什么重试因为超时——工单系统那次写入实际成功了只是响应慢超过了 1.5 秒的超时阈值于是重试逻辑又发了两次。为什么会超时那天工单系统在做索引重建写入延迟普遍在 2 秒左右。根因是一句话写操作的重试没有幂等保护。修复分两步短期是把所有写操作的超时放宽并关闭自动重试长期是引入幂等键。幂等键的生成我放在执行层用会话 ID 工具名 参数指纹拼一个哈希同一秒内重复的请求会命中同一个键下游系统按这个键去重。这个改动上线后同类问题再没出现过。问题现象表层原因根因修复动作通知重复三条通知服务收到三次请求写操作超时后自动重试无幂等保护写操作关闭自动重试引入幂等键延迟忽高忽低单环节超时设置合理各环节超时叠加缺少总预算引入 deadline 预算传递4.3 工具返回值过大把上下文撑爆第三个坑是某次查询接口返回了一个包含上万条明细的数组。裁剪逻辑当时只做了字段白名单没做条数限制于是白名单保留了五个字段乘以一万条依然是个灾难。模型的行为很有趣它没有报错而是抓了前几条开始编给出一个整体情况良好的结论。修法是给回流层加上硬性条数上限和聚合规则超过 50 条时返回总数 统计摘要 前 5 条样例同时在结果里明确标注仅展示前 5 条。这个标注很重要它让模型知道自己看到的是采样回答时会主动说明数据范围而不是把采样当成全量。4.4 权限放大一次越权查询的排查链路最后一个坑最值得警惕。有个查询类工具的参数是手机号后四位本意是让用户查自己的订单。上线后发现有人能通过构造输入查到别人的订单——因为后四位重复率高工具本身没有校验调用者身份。排查过程先看审计日志发现同一个会话里出现了多个不同的手机号后四位再看策略校验发现它只检查了这个角色能不能用这个工具没检查这个参数是不是属于这个用户最后确认根因是策略校验的粒度太粗。修复是把策略校验从工具级下沉到参数级校验函数拿到完整的参数值之后做归属判断查不到归属就直接拒绝。def check(user, tool, values) - Decision: if not user.can_use(tool[name]): return Decision(False, role_not_allowed) if tool[name] query_order_status and values.get(phone_tail): if not user.owns_phone_tail(values[phone_tail]): return Decision(False, resource_not_owned) return Decision(True, ok)这个改动让我彻底改变了对权限的理解权限不是一个开关而是调用者、工具、参数三者的联合判断。任何一个维度缺失都会留下放大的口子。5. 让 Reach 从能用变成好用观测、成本与效果评估5.1 需要埋哪些指标系统跑起来只是开始能不能持续优化取决于你有没有数据。我在这一层固定埋四类指标缺一类都会在某个时刻变成盲区。第一类是路由质量包括工具命中率、候选第一名的准确率、拒答率、反问触发率。这几个数一起看才有意义单看命中率会因为拒答率上升而虚高。第二类是执行健康度包括 P50/P95 耗时、失败率、重试率、超时率、熔断触发次数。第三类是成本指标包括每次请求的模型调用次数、token 消耗、工具调用次数。第四类是回流指标包括原始返回体积和裁剪后体积的比值、触发模型摘要的比例。我特别想强调的是第四个比值。这个数如果长期偏高说明你的字段白名单写得不够精细有大量的无用数据在链路上空转。我优化过一次把某个工具的裁剪比从 0.18 提到 0.04单这一个改动就让整体 token 成本降了一成多。5.2 成本控制的三个抓手成本控制这件事在 Agent-Reach 里主要靠三个抓手。第一个是减少模型调用轮次很多链条里模型被调了四五次其中有一两次完全可以用规则替代比如参数格式校验、必填字段判断这些用代码做又快又准。第二个是缓存读操作的缓存命中率往往能到四五成尤其是政策类、配置类这种低频变化的数据加一层短 TTL 缓存几乎是白捡的收益。第三个是上下文瘦身把工具描述本身也当成成本来管理二十个工具的完整描述本身就占掉不少 token我一般按需注入只把和当前意图相关的几个工具描述放进上下文。5.3 效果评估集怎么建没有评估集所有的优化都是盲改。我的做法是攒一个两三百条的真实问句集每条标注正确工具 关键参数 可接受的回答要点。这个集子不需要多精美但一定要有你自己的真实语料公测数据集上的表现和你的业务分布差异往往很大。评估跑起来之后每次改动都跑一遍看四个数工具命中率、参数准确率、端到端成功率、平均耗时。我定过一个规矩任何改动导致端到端成功率下降超过两个百分点就回滚不管它在别的指标上多好看。这个规矩挡住过好几次局部优化全局变差的改动。5.4 灰度与回滚工具是可以独立灰度的这一点比整体灰度模型要友好得多。新增工具或修改工具描述时我会先放 5% 流量观察两三天重点看误调用率和失败率。描述变更的风险其实不小一段措辞的调整有可能让模型的行为整体偏移所以我把工具描述也纳入了版本管理和审查流程。回滚要能做到分钟级。做法是工具描述和执行策略全部走配置下发服务本地缓存配置变更实时生效。这样出问题时改一行配置就能回到旧版本不用重新发版。6. 哪些场景值得先上 Agent-Reach6.1 优先做的三类场景按我的经验有三类场景的性价比最高。第一类是查询密集但只读的场景比如订单进度、库存、账单明细这类没有副作用风险低且价值直观。第二类是高频重复的结构化操作比如固定格式的工单创建、批量状态更新人工做很枯燥自动化收益明确。第三类是需要跨系统拼接信息的场景比如把工单、合同、履约记录拉在一起给一个综合判断这类正是人最费时、模型最擅长的地方。三类场景有一个共同点结果可以验证。做完之后你能明确说这次答对了还是答错了而不是模棱两可。可验证性是能不能持续迭代的前提。6.2 暂时别碰的三类场景反过来有三类场景我建议先放一放。第一类是不可逆的高风险操作比如直接扣款、删数据、对外发正式函件这些即使准确率做到 99% 也不够。第二类是强合规约束下的敏感数据操作涉及大量个人信息的读写审计和授权成本极高。第三类是需求本身还很模糊的场景用户自己都说不清要什么工具边界就定不下来这属于先理业务再谈自动化。6.3 一条渐进式的接入路线如果让我重来一次我会按这个顺序推第一周只做一个只读工具把四层结构跑通把评估集建起来第二周加两到三个同域工具重点打磨路由层和回流层第三周引入策略校验和审计把权限模型做对第四周才开始接写操作并且从低风险、可撤销的写操作开始。这条路线的核心逻辑是先证明质量再扩大范围。我见过太多团队反过来做一上来就接五六个系统结果每个都半生不熟出问题时连根因在哪一层都定位不出来。慢就是快这四个字在智能体工程里体现得尤其明显。最后分享一个小技巧也是我踩了几次坑才养成的习惯每次新增工具我都会先写三条绝对不应该调用的用例比如用户问退款政策时不能调订单查询、用户只发了句你好时不能调任何工具。这三条用例通过之后我才开始写正向用例。这个顺序看着别扭但它把最常见的误调用问题挡在了上线之前。实际用下来一次误调用带来的用户信任损失远比多花半天写测试要贵得多。 
长河君 · 2026/9/18 17:27:25 · 阅读 1.2k Agent-Reach 实战：智能体工具调用四层架构与落地避坑
去年到现在我陆陆续续帮几个团队做过智能体落地有意思的是几乎每一轮复盘都落在同一个地方模型本身很少是瓶颈真正卡住业务的是够不着。用户问一句帮我把上周那批异常订单拉出来顺便通知一下负责的同事模型答得头头是道、流程拆得清清楚楚可到了真要查库、真要发通知的那一刻整条链路就断了。Agent-Reach 这个词最近被提得越来越多说的本质上就是这件事——让智能体从会聊天变成够得着把能力伸到模型参数之外的系统、数据和协作通道里去。我理解的 Agent-Reach 不是某个具体的库也不是某家厂商的专有功能而是一套围绕智能体触达能力的工程结构工具怎么被描述、意图怎么被路由到具体动作、执行时怎么做权限和稳定性兜底、结果又怎么被压缩回上下文窗口。这套东西说起来抽象拆开来看每一块都很具体而且每一块都有各自典型的坑。下面我按自己搭这套东西的顺序一层层讲清楚能抄的地方我会直接给配置和代码踩过的雷我也会把排查过程原样写出来。1. Agent-Reach 解决的到底是什么问题从会说话到够得着1.1 一个把问题暴露得最清楚的场景设想一个售后场景的智能体。用户说我上周买的那台机器好像坏了算了别修了能不能直接换这句话里藏着至少四个动作查出这个用户最近的订单、判断商品落在哪个保修政策下、核对是否满足换货条件、最后在工单系统里开一张单并把结果告诉用户。任何一个环节够不着回答就会退化成建议您联系客服——用户立刻知道这是个假智能体。我见过的最典型做法是把这四个动作硬编码成一个超长的提示词再把结果拼成固定话术。这版能演示但一上真实流量就露馅商品类目一变、政策一改、系统接口一调整提示词就要重写。更麻烦的是它没有失败路径接口超时了它还在那儿一本正经地编。Agent-Reach 要解决的正是这段最后一公里。它把模型能触达的外部能力显式地建模出来让模型只负责决定做什么而能不能做、怎么做、做失败了怎么办交给一层稳定的工程结构去兜。这个分工一旦立住你会发现提示词反而变短了因为大量边界逻辑被挪到了代码里而代码是可以测试、可以灰度、可以回滚的。1.2 大多数团队的第一版实现断在这三个地方我梳理过十几个失败的早期版本断点高度集中在三处。第一处是工具注册靠 if-else 堆。一开始只有三个工具写三个分支很自然等到二十个工具时路由逻辑变成了一坨意大利面而且模型完全不知道有这些工具存在因为它从来没在上下文里见过它们。这里的关键认知是工具不是给程序员看的接口而是给模型看的可选项它的描述质量直接决定路由准确率。第二处是权限用一个万能账号。为了图快很多团队给智能体配了一个几乎什么都能读写的服务账号。演示阶段没问题一旦接入真实数据就是事故预备役。Agent-Reach 里我把权限当成一等公民来处理每个工具、每个调用都要带上调用者身份和参数范围执行层做一次收口的策略校验。第三处是结果原样塞回上下文。某个查询接口返回了 300KB 的 JSON直接塞进上下文要么触发长度截断要么把 token 成本推到天上去。回流层要做的事情恰恰是压缩与摘要——这一步做得好不好直接决定整套系统的单位成本。1.3 Reach这个词的准确含义触达等于四件事的串联我把触达拆成四个环节每一个环节对应一类典型的失败现象。这张表我建议在方案评审时直接摆出来它能让讨论快速收敛。环节该做的事做不好时的典型表现描述把外部能力写成模型能理解的结构化说明模型不知道有这个工具或者选错工具路由从意图匹配到具体工具并消解歧义参数抽错、在多个相似工具间反复横跳执行鉴权、限流、重试、幂等与超时兜底重复下单、越权查询、接口雪崩回流把结果裁剪压缩成模型可消费的形式上下文爆掉、成本失控、答非所问四个环节里最容易被人忽略的是第一个。很多人默认工具描述写给自己看就行但在 Agent-Reach 的语境里描述就是产品界面。一个写得好的描述会把什么时候该用和什么时候绝对不要用都写清楚模型的误调用率能下降一大截这比后面调多少次提示词都管用。注意工具描述的受众是模型不是人类工程师。判断标准不是我能不能看懂而是一个没有任何业务背景的人读完能不能准确判断该不该调用、该传什么参数。2. 拆开 Agent-Reach 的内部结构四层能力模型2.1 接入层把外部世界翻译成统一契约接入层干的是化整为零再归一的活。外部系统千奇百怪有 REST 接口、有数据库、有消息队列、有内部 RPC它们的鉴权方式、错误码体系、返回结构全不一样。接入层要把这些统一成一份契约让上面的路由层不需要关心底下接的是什么。我在这一层最看重三件事。一是描述与实现分离工具的元信息用声明式的方式单独维护改描述不用动代码改代码不用动描述。二是副作用标注读操作和写操作必须显式区分因为它们的执行策略完全不同——读可以激进重试写必须谨慎并且要幂等。三是成本提示给每个工具打一个粗略的成本标签低成本的可以多调高成本的要有预算约束这一点在后面控制成本时会救命。一个可用的工具描述长这样{ name: query_order_status, description: 根据订单号或下单手机号查询订单当前状态与最近一次履约节点。, when_to_use: 用户询问订单进度、是否已发出、预计到达时间时使用。, when_not_to_use: 用户咨询退换货政策、发票、优惠券问题时不要调用本工具。, parameters: { order_id: { type: string, required: false, description: 订单号形如 SO-2024-00000通常 14 位 }, phone_tail: { type: string, required: false, description: 下单手机号后四位当用户没有提供订单号时使用 } }, side_effect: read_only, timeout_ms: 3000, cost_hint: low }注意when_not_to_use这个字段它不是可选项。我实测下来加上它之后一个和查订单高度相似的工具比如查物流轨迹的误调用率能降三成左右。原因很简单模型在相似选项之间摇摆时需要的就是一条明确的排除规则。2.2 路由层从一句话到一次确定的调用路由层的输入是一段自然语言意图输出是用哪个工具、传什么参数。这里有个反直觉的经验不要让模型直接输出最终参数而是让它先输出候选工具再由代码去抽取参数。原因是模型在选工具时判断力不错但在生成结构化参数时经常凭空捏造字段值。把这两件事拆开每一件都能单独优化和评测。消歧是路由层最费心思的部分。真实用户的话往往缺主语、缺关键标识比如那个单子怎么样了。这时候路由层要做的不只是匹配工具还要判断信息是否充分。信息不足时正确行为不是硬猜而是生成一个反问。很多团队把这步省了结果是智能体用错误的参数调了一堆接口最后给出一个自信的错答案这比直接说我不知道伤害大得多。我给路由层留了三个必须落地的机制候选打分与阈值截断分数太低就不调用转为反问、信息充分性检查必填参数缺失时触发追问、以及一次会话内的工具调用预算比如最多连续调三个防止死循环。第三个机制听起来粗暴但它挽救了至少两次线上事故。2.3 执行层所有脏活累活都在这里执行层是真正和外部系统打交道的地方也是稳定性问题的集中区。这一层需要处理的东西列出来能吓死人鉴权凭证管理、连接池、超时、重试退避、熔断、限流、幂等键、审计日志、脱敏。我一般把它们分成两类来对待。第一类是通用横切能力用统一的中间件实现所有工具共享包括超时、重试、熔断、日志、脱敏。这类东西千万别在单个工具里各自实现否则二十个工具就有二十套超时逻辑排查问题时痛不欲生。第二类是工具特有逻辑比如某个接口要求签名、某个接口有特殊的分页约定这些才放进工具自己的适配器里。一个我反复强调的原则是读操作允许激进重试写操作默认不重试。写操作的重试必须依赖幂等键而且幂等键要由执行层统一生成和透传不能指望上游系统自己识别重复请求。我吃过一次亏一次网络抖动触发了三次重试结果同一张工单开了三张用户收到三条通知场面相当尴尬。2.4 回流层把一卡车数据压成一句话回流层是最容易被低估的一层但它是成本和质量的分水岭。外部系统的返回往往是给程序看的字段多、嵌套深、体积大而模型的上下文窗口是稀缺资源。回流层要做的是把原始返回转换成回答当前问题所必需的最小信息集。我的做法是三层处理。第一层是硬裁剪按工具声明的字段白名单挑出需要的字段其余直接丢弃这一步能在零成本的情况下砍掉七八成的体积。第二层是分页与聚合长列表转成总数 摘要 前几条样例模型需要细节时再触发二次查询。第三层才是模型侧的摘要也就是让一个小模型把结构化结果转成一段自然语言这一层有成本所以只在前两层处理完还不够小的时候才启用。这三层的顺序不能反。我见过直接拿大模型去摘要 300KB JSON 的方案效果时好时坏成本还高得离谱。先用确定的规则砍体积永远比让模型去理解一堆冗余字段更划算。3. 从零跑通第一条 Reach 通道3.1 环境与依赖准备不要一上来就上全量搭这套东西最常见的错误是第一天就想着把公司所有系统接进来。我的建议是反过来先挑一个只读、返回量小、业务价值明确的外部能力把描述、路由、执行、回流这四层全部走通一遍哪怕只有这一个工具。跑通之后再复制你会发现第二个工具花的时间不到第一个的四分之一。环境上需要的东西不多一个能跑服务的运行时Python 或 Node 都行、一个配置存储初期用文件就行别急着上配置中心、一个日志出口。模型侧需要一个支持工具调用的接口。下面我用 Python 写最小闭环思路和语言无关。第一步是把工具描述组织成一个注册表。我不建议把描述散落在代码里而是统一放在一份清单中启动时加载校验import json from pathlib import Path class ToolRegistry: def __init__(self, path: str): raw json.loads(Path(path).read_text(encodingutf-8)) self._tools {} for item in raw[tools]: self._validate(item) self._tools[item[name]] item def _validate(self, item: dict) - None: required [name, description, when_to_use, parameters, side_effect] missing [k for k in required if k not in item] if missing: raise ValueError(f工具 {item.get(name)} 缺少字段: {missing}) if item[side_effect] not in (read_only, write): raise ValueError(f工具 {item[name]} 的 side_effect 取值非法) def all(self) - list[dict]: return list(self._tools.values()) def get(self, name: str) - dict: return self._tools[name]这段校验代码看着琐碎但它挡住的是最讨厌的一类问题某个同事新加的工具字段写漏了模型看到的是一个残缺描述于是开始乱调。启动时就报错远比线上猜谜强。3.2 路由与执行的骨架代码路由我分两步先让模型在候选工具里做选择再由代码做参数抽取和策略校验。下面这段是骨架重点是那个逐级降级的循环——它比一次性选一个工具鲁棒得多。def reach(intent: str, ctx) - dict: candidates router.rank(intent, ctx.registry.all(), top_k3) if not candidates or candidates[0].score 0.45: return {type: clarify, question: router.ask_back(intent)} for cand in candidates: tool ctx.registry.get(cand.name) args extractor.fill(intent, tool) if not args.complete: return {type: clarify, question: args.missing_prompt} decision policy.check(ctx.user, tool, args.values) if not decision.allowed: ctx.audit.log(policy_denied, ctx.user, tool[name], decision.reason) continue result executor.run(tool, args.values, ctx) if result.ok: return {type: answer, payload: reducer.shrink(tool, result.data)} return {type: fallback, message: 暂时没能取到相关信息你可以换个说法再试一次。}有三处细节值得展开。score 0.45这个阈值不是拍脑袋定的我是拿一批真实问句做标注画出准确率随阈值变化的曲线选了一个准确率高、拒答率还能接受的折中点你们自己的语料上这个值大概率不一样。policy.check放在参数抽取之后是因为它常常需要看具体参数值才能判断比如同一个查询工具查自己的订单可以查别人的就不行。reducer.shrink是回流层的入口它的职责单一就是缩小体积。3.3 用三条测试用例验证够得着骨架跑起来之后别急着加工具先用三条用例把链路验证扎实。第一条是正常路径信息完整、工具匹配、返回正常看能不能一路走到答案。第二条是信息缺失只说那个单子看是否正确触发反问而不是瞎猜一个订单号。第三个是执行失败把下游接口的超时设成 1 毫秒人为制造失败看是否走到降级话术而不是抛异常或者编造答案。第三类用例最容易被忽略但它是区分能演示和能用的关键分界线。我习惯在本地环境加一个故障注入开关能强制某个工具超时、返回空、返回超大 payload、返回 500四种故障各跑一遍。这四遍跑完你对这条通道的信心会完全不一样。提示把执行失败当成一等测试场景而不是异常处理的分支。真实环境里下游的失败率远比你想象的高。4. 我在并发、超时和幂等上踩过的坑4.1 超时预算的分配问题第一个坑很隐蔽。我给单个工具设了 3 秒超时觉得挺合理结果线上偶尔出现 12 秒才返回的情况。查下来才发现路由层为了消歧会并行调用几次模型每次自己也有超时几次叠加再加上工具本身的重试总耗时就成了乘法关系。修法是把超时当成预算来管理而不是给每个环节单独设一个数。一次用户请求分配一个总预算比如 8 秒路由层花掉的要在执行层的预算里扣掉。实现上很简单就是往下传一个 deadline 时间戳每个环节开始前先检查剩余时间不够就直接降级。class Budget: def __init__(self, total_ms: int): self.deadline time.monotonic() total_ms / 1000 def remaining_ms(self) - int: return max(0, int((self.deadline - time.monotonic()) * 1000)) def take(self, want_ms: int) - int: return min(want_ms, self.remaining_ms())改完之后最坏情况下的耗时被压到了预算以内用户感知从卡住变成了想了想然后给了个降级答案体感差异非常大。4.2 重试导致的重复副作用前面提过一次工单开三张的事故这里把完整的排查链路写一下因为它的推理过程比结论更有价值。现象是用户收到三条重复的通知时间戳差了不到两秒。第一反应是通知服务有问题但查通知服务日志发现是三次独立请求都带着不同的请求 ID。顺着往上查发现是工单系统的调用被重试了三次。为什么重试因为超时——工单系统那次写入实际成功了只是响应慢超过了 1.5 秒的超时阈值于是重试逻辑又发了两次。为什么会超时那天工单系统在做索引重建写入延迟普遍在 2 秒左右。根因是一句话写操作的重试没有幂等保护。修复分两步短期是把所有写操作的超时放宽并关闭自动重试长期是引入幂等键。幂等键的生成我放在执行层用会话 ID 工具名 参数指纹拼一个哈希同一秒内重复的请求会命中同一个键下游系统按这个键去重。这个改动上线后同类问题再没出现过。问题现象表层原因根因修复动作通知重复三条通知服务收到三次请求写操作超时后自动重试无幂等保护写操作关闭自动重试引入幂等键延迟忽高忽低单环节超时设置合理各环节超时叠加缺少总预算引入 deadline 预算传递4.3 工具返回值过大把上下文撑爆第三个坑是某次查询接口返回了一个包含上万条明细的数组。裁剪逻辑当时只做了字段白名单没做条数限制于是白名单保留了五个字段乘以一万条依然是个灾难。模型的行为很有趣它没有报错而是抓了前几条开始编给出一个整体情况良好的结论。修法是给回流层加上硬性条数上限和聚合规则超过 50 条时返回总数 统计摘要 前 5 条样例同时在结果里明确标注仅展示前 5 条。这个标注很重要它让模型知道自己看到的是采样回答时会主动说明数据范围而不是把采样当成全量。4.4 权限放大一次越权查询的排查链路最后一个坑最值得警惕。有个查询类工具的参数是手机号后四位本意是让用户查自己的订单。上线后发现有人能通过构造输入查到别人的订单——因为后四位重复率高工具本身没有校验调用者身份。排查过程先看审计日志发现同一个会话里出现了多个不同的手机号后四位再看策略校验发现它只检查了这个角色能不能用这个工具没检查这个参数是不是属于这个用户最后确认根因是策略校验的粒度太粗。修复是把策略校验从工具级下沉到参数级校验函数拿到完整的参数值之后做归属判断查不到归属就直接拒绝。def check(user, tool, values) - Decision: if not user.can_use(tool[name]): return Decision(False, role_not_allowed) if tool[name] query_order_status and values.get(phone_tail): if not user.owns_phone_tail(values[phone_tail]): return Decision(False, resource_not_owned) return Decision(True, ok)这个改动让我彻底改变了对权限的理解权限不是一个开关而是调用者、工具、参数三者的联合判断。任何一个维度缺失都会留下放大的口子。5. 让 Reach 从能用变成好用观测、成本与效果评估5.1 需要埋哪些指标系统跑起来只是开始能不能持续优化取决于你有没有数据。我在这一层固定埋四类指标缺一类都会在某个时刻变成盲区。第一类是路由质量包括工具命中率、候选第一名的准确率、拒答率、反问触发率。这几个数一起看才有意义单看命中率会因为拒答率上升而虚高。第二类是执行健康度包括 P50/P95 耗时、失败率、重试率、超时率、熔断触发次数。第三类是成本指标包括每次请求的模型调用次数、token 消耗、工具调用次数。第四类是回流指标包括原始返回体积和裁剪后体积的比值、触发模型摘要的比例。我特别想强调的是第四个比值。这个数如果长期偏高说明你的字段白名单写得不够精细有大量的无用数据在链路上空转。我优化过一次把某个工具的裁剪比从 0.18 提到 0.04单这一个改动就让整体 token 成本降了一成多。5.2 成本控制的三个抓手成本控制这件事在 Agent-Reach 里主要靠三个抓手。第一个是减少模型调用轮次很多链条里模型被调了四五次其中有一两次完全可以用规则替代比如参数格式校验、必填字段判断这些用代码做又快又准。第二个是缓存读操作的缓存命中率往往能到四五成尤其是政策类、配置类这种低频变化的数据加一层短 TTL 缓存几乎是白捡的收益。第三个是上下文瘦身把工具描述本身也当成成本来管理二十个工具的完整描述本身就占掉不少 token我一般按需注入只把和当前意图相关的几个工具描述放进上下文。5.3 效果评估集怎么建没有评估集所有的优化都是盲改。我的做法是攒一个两三百条的真实问句集每条标注正确工具 关键参数 可接受的回答要点。这个集子不需要多精美但一定要有你自己的真实语料公测数据集上的表现和你的业务分布差异往往很大。评估跑起来之后每次改动都跑一遍看四个数工具命中率、参数准确率、端到端成功率、平均耗时。我定过一个规矩任何改动导致端到端成功率下降超过两个百分点就回滚不管它在别的指标上多好看。这个规矩挡住过好几次局部优化全局变差的改动。5.4 灰度与回滚工具是可以独立灰度的这一点比整体灰度模型要友好得多。新增工具或修改工具描述时我会先放 5% 流量观察两三天重点看误调用率和失败率。描述变更的风险其实不小一段措辞的调整有可能让模型的行为整体偏移所以我把工具描述也纳入了版本管理和审查流程。回滚要能做到分钟级。做法是工具描述和执行策略全部走配置下发服务本地缓存配置变更实时生效。这样出问题时改一行配置就能回到旧版本不用重新发版。6. 哪些场景值得先上 Agent-Reach6.1 优先做的三类场景按我的经验有三类场景的性价比最高。第一类是查询密集但只读的场景比如订单进度、库存、账单明细这类没有副作用风险低且价值直观。第二类是高频重复的结构化操作比如固定格式的工单创建、批量状态更新人工做很枯燥自动化收益明确。第三类是需要跨系统拼接信息的场景比如把工单、合同、履约记录拉在一起给一个综合判断这类正是人最费时、模型最擅长的地方。三类场景有一个共同点结果可以验证。做完之后你能明确说这次答对了还是答错了而不是模棱两可。可验证性是能不能持续迭代的前提。6.2 暂时别碰的三类场景反过来有三类场景我建议先放一放。第一类是不可逆的高风险操作比如直接扣款、删数据、对外发正式函件这些即使准确率做到 99% 也不够。第二类是强合规约束下的敏感数据操作涉及大量个人信息的读写审计和授权成本极高。第三类是需求本身还很模糊的场景用户自己都说不清要什么工具边界就定不下来这属于先理业务再谈自动化。6.3 一条渐进式的接入路线如果让我重来一次我会按这个顺序推第一周只做一个只读工具把四层结构跑通把评估集建起来第二周加两到三个同域工具重点打磨路由层和回流层第三周引入策略校验和审计把权限模型做对第四周才开始接写操作并且从低风险、可撤销的写操作开始。这条路线的核心逻辑是先证明质量再扩大范围。我见过太多团队反过来做一上来就接五六个系统结果每个都半生不熟出问题时连根因在哪一层都定位不出来。慢就是快这四个字在智能体工程里体现得尤其明显。最后分享一个小技巧也是我踩了几次坑才养成的习惯每次新增工具我都会先写三条绝对不应该调用的用例比如用户问退款政策时不能调订单查询、用户只发了句你好时不能调任何工具。这三条用例通过之后我才开始写正向用例。这个顺序看着别扭但它把最常见的误调用问题挡在了上线之前。实际用下来一次误调用带来的用户信任损失远比多花半天写测试要贵得多。