我在去年接手过一个客服售后自动化的项目需求听起来很简单让大模型自动查订单、算退款、转人工。结果前后折腾了三个月最让我头疼的根本不是Prompt调优而是让Agent真正“碰到”那些外部系统。模型脑内推理再漂亮工具调用链路一塌糊涂整个系统就是空中楼阁。也就是在那一轮又一轮的踩坑里我慢慢磨出了一套自己的方案给它取名叫 Agent-Reach。它要解决的核心问题很简单智能体的能力边界不在模型有多聪明而在它能把触角伸到多远以及伸出去之后能不能安全、稳定地把活儿干完。这篇博文就分享一下 Agent-Reach 的完整设计思路、落地过程里踩过的坑以及我最后沉淀下来的配置和参数。如果你也在做 AI Agent 的工程化落地尤其是要让大模型真正操作业务系统、调用内部API、处理数据变更那这篇文章应该能帮你在动手之前避开不少弯路。1. 从会聊天到能干活Agent-Reach 要解决的问题1.1 对话式模型的尴尬大脑发达手脚没长出来先聊一个很反直觉的现象大模型在对话测试里表现近乎完美你让它分析一段评论、总结一份文档、甚至写一版营销文案它都干得像模像样。可一旦你要求它“帮我把订单状态同步到ERP里如果价格差异超过5%就发邮件给财务”模型就开始癫狂了。它会一本正经地告诉你“好的我已经完成了”实际上什么都没发生。或者它确实尝试去调接口了但参数拼得让人哭笑不得——把金额字段传成了字符串把订单号的英文字母O当成了数字0。问题的根源在于绝大多数模型在预训练阶段学的是“语言”不是“操作”。它知道订单是什么、退款流程大概怎么走但它没有手没有权限、没有接口地址也没有对真实世界状态的感知。你让一个没有手脚的人去修水管他最多给你一份图文并茂的修水管说明书但水管还是漏的。这也是我为什么一直强调智能体工程的核心不是模型推理而是触达层。用大白话说就是给模型装上“手脚”把语言能力转化为可执行动作。Agent-Reach 这个名字就是从这个想法里长出来的——Reach触达。1.2 Agent-Reach 的定位连接大脑与外部世界的调度层一个完整的 Agent 系统按我的理解可以切成三层。最底层是模型层负责理解和推理上层的任务规划、中层的工具调度最终都要落到模型的文本生成能力上。最顶层是业务层也就是你真正想完成的业务目标比如“处理退换货”“生成周报”“巡检服务器”。而中间那层就是被大多数人忽略的触达层。Agent-Reach 做的就是这个触达层。它不负责教模型“怎么想”而是负责让模型“够得着”。你给它一份外部世界的能力清单它负责把模型的意图翻译成一个个真实可执行的调用再把这些调用的结果——成功也好、失败也好——变成模型能理解的信息喂回去继续推理。具体到架构上Agent-Reach 由四个核心模块组成工具注册表所有 Agent 可以调用的外部函数、API接口、数据库操作都集中在这里登记、分类、定义输入输出格式。意图路由模块从用户的自然语言请求里识别真实意图再决定要触达哪一类工具以及用什么样的顺序触达。执行沙箱真正执行工具调用的地方负责参数校验、超时控制、错误捕获、权限检查。反馈压缩器把工具返回的原始结果加工成模型能高效消费的信息避免模型在处理结果时被海量噪声带偏。这套结构听起来不复杂但每一层都有无数细节接下来的几个小节我就按实际搭建顺序把每一层怎么设计、为什么这么设计讲清楚。2. Agent-Reach 的架构设计我最终定下的触达层方案2.1 工具注册表一切触达的前提是让 Agent 知道有什么很多人上手做 Agent 时第一反应是“怎么让模型学会调用工具”但我的经验恰恰相反第一步应该是“让模型知道世界上存在哪些工具”。你想让一个刚入职的员工干活至少得先给他一份公司通讯录告诉他谁负责什么、找谁办什么事。Agent 也一样。我在 Agent-Reach 里定义工具注册表时没有用简单的列表而是给每个工具挂了五类元信息工具名称和ID全局唯一建议用“模块.动作”的命名法比如 order.pay、order.refund、inventory.check。自然语言描述用一句话说明这个工具是干什么的、适合在什么场景下使用。这一步看似简单实际影响巨大模型对工具的理解程度很大程度上取决于这句话写得多清楚。输入输出Schema严格定义好参数名、类型、取值范围、是否必填。我用的是 JSON Schema 格式方便直接用程序做校验。调用方式是同步 HTTP 接口还是异步任务提交还是本地函数直接调用以及对应的 endpoint、认证方式、超时时间。权限标签这个工具涉及哪个业务域、最低需要什么角色、有没有敏感操作标识。给你看一下我定义工具时的一个简化示例这是注册表中“查询订单”工具的 JSON Schema 片段{ name: order.query, description: 根据订单号查询订单基本信息包括订单状态、商品明细、支付金额等。适用于用户询问订单进度、售后处理前的信息核验。, parameters: { type: object, properties: { order_id: { type: string, pattern: ^[A-Z0-9]{12}$, description: 12位订单号仅包含大写字母和数字不含I、O以避免混淆 }, include_items: { type: boolean, default: false, description: 是否返回订单内商品明细默认不返回以减少传输量 } }, required: [order_id] }, permission: customer_service, timeout_ms: 3000 }这段 Schema 里有个小细节订单号限制为不含字母 I 和 O。这是我后来才加上的因为模型在生成订单号时经常把字母 O 当成数字 0把字母 I 当成数字 1。如果没有正则约束模型可以自由发挥系统就会在数据查不到的时候疯狂重试。加了 pattern 之后模型在参数生成阶段就会被强行纠正一部分。2.2 意图路由从硬编码到语义匹配让 Agent 自己找到路工具清单有了下一步是决定怎么让模型选择该用哪个工具。最粗暴的做法是在 Prompt 里把所有工具描述扔给模型让它自己挑。这在工具数量少于十个的时候没问题一旦工具超过二十个模型的选择准确度会急速下降。它会频繁把“查库存”路由到“查订单”上或者把问题拆解成一连串和任务无关的调用。Agent-Reach 没有走这条路。我实现的是一个两段式路由。第一段是粗粒度路由先用 Embedding 把用户的输入问题转成向量同时把每个工具的描述也离线编码成向量然后做一次相似度检索从几十个工具里先锁定三到五个候选工具。这一步的开销很小毫秒级完成但能大幅减轻模型的决策负担。第二段是细粒度选择把候选工具的完整 Schema注意这里只放候选不放全部交给模型让它基于对用户意图的深度理解做最终决定。如果你对 Embedding 检索不熟可以把它想象成图书馆里的预检台——读者说“我想找一本讲怎么做红烧肉的书”预检台先根据关键词圈出烹饪类的三排书架读者再自己走进书架慢慢挑而不是把整座图书馆的书单全丢给读者。这两段式设计还有一个额外的好处工具的描述可以写得很详尽不会挤占模型的上下文窗口。候选工具之外的描述根本不会进入 Prompt模型只看到它此刻需要决策的几个选项注意力自然更聚焦。2.3 反馈压缩器工具返回的结果不能原封不动塞回给模型工具调用完了返回值要交给模型继续推理。这一步看起来稀疏平常但恰恰是我踩坑最深的地方。最典型的场景某次工具返回了一个 JSON 数组里面有用户近三年的全部订单记录差不多两百条每条都带时间戳、金额状态、物流信息。我把这一坨 JSON 原封不动地塞回 Prompt模型确实能读但它会把注意力分散到大量无关字段上甚至开始臆测物流状态的含义。更现实的问题是这些原始数据会占用大量上下文 token下一轮对话还没开始上下文窗口就要见底了。所以 Agent-Reach 在执行沙箱和模型之间强行插入了一个反馈压缩器。它的职责有三条第一字段裁剪。根据模型接下来最可能需要的信息把返回值里的无关字段剥掉。拿上面的例子来说模型要做的是“判断是否超出售后时效”那我就只保留订单号、创建时间、当前状态、实付金额四个字段物流明细、商品备注全部丢掉。第二结构化摘要。对长列表、长文本做一层预聚合把“两百条订单”变成“最近一年订单共47笔其中已完成39笔、售后中5笔、退款3笔金额总计123456元”。模型吃的是这种浓缩后的信息推理准确率明显上升。第三错误归一化。工具抛出的五花八门的异常统一转成模型能理解的标准格式比如 TIMEOUT、PERMISSION_DENIED、INVALID_PARAM、PARTIAL_SUCCESS并且附上一小段面向模型的提示语比如“这次查询超时了可以重试一次或者告诉用户稍后再试”。这一步做完Agent 从“知道调工具”进化成“懂得用好工具返回的信息”推理质量立刻拉开差距。3. 落地过程中绕不开的三类深坑3.1 工具参数幻觉大模型的手比嘴还不老实参数幻觉是我项目上线前测试时遇到的第一堵墙。模型生成的自然语言非常流畅但一旦要它填结构化参数各种匪夷所思的错误就出来了。日期格式混乱接口要求的是 ISO 格式模型给你一个“明天下午三点”枚举值凭空捏造状态字段明明只有 pending、paid、refunded 三个可选值模型能给你来个 in_progress。这东西的本质原因是在语言建模的世界里所有字符串出现的概率都是平滑分布的。模型在训练时见过太多启用的日期表达、状态词你让它做选择题它当然会但你要它严格执行有限的枚举约束它就必须“对抗”自己强大的语言惯性。我的解决办法不是指望模型变乖而是在执行沙箱里加了三道闸门。第一道是 Schema 前置校验参数生成后先用 JSON Schema 引擎做一次硬校验类型不对、枚举越界、正则不匹配直接拦截。第二道是规则化修复针对一部分高频错误做自动修复比如把中文大小写数字转成阿拉伯数字、把“明天”“下周”这类相对时间换算成具体日期、给订单号统一补上缺失的校验位。第三道是重试策略校验失败后带着模型上一次生成的参数以及具体的错误信息让模型重新生成一次。这里有个经验数据重试超过两次后成功率基本不再提升反而容易陷入死循环所以我把自动重试上限锁定为一次。3.2 反馈回路过深Agent 会把自己绕进死胡同第二个深坑是 Agent 在连环调用中把自己绕晕。有一次我让 Agent 处理一个组合任务“查询订单A的状态如果未发货就取消订单并给用户发一封补偿邮件。”理想执行序列是 query → 判断状态 → cancel → send_email。但实际跑的时候Agent 在 query 拿到结果之后没有直接走向 cancel而是又把查询结果里的几个字段拿去“分析”了一遍甚至额外调用了商品推荐接口想把“补偿邮件”写成“顺便推荐个新品”。结果整个执行链条失控调用了八个工具实际只有前两个是有意义的。后来我在日志里观察了很久总结出两个关键原因。一是模型的每一步决策都会消耗上下文窗口工具反馈信息被压缩得不够狠的时候它会“看到”太多东西就容易发散。二是模型对“当前正在干什么”的记忆非常脆弱它需要不断确认自己走到了哪一步。Agent-Reach 针对这个问题的方案是把任务执行变成有限状态机。每次用户请求解析完之后先生成一个多步骤计划但计划里的每一步都绑定了一个前置条件。比如只有 query 结果里 status 等于 unpaid 的时候才允许进入 cancel 分支只有 cancel 成功返回后才允许进入 send_email 分支。每一步执行前沙箱都会检查前置条件是否满足不满足就直接中断把“为什么中断”返回给上层。我不会让模型在任意时刻拥有“自由意志”自由发散只适合单轮创作不适合多步执行。提示在做 Agent 任务编排时尽量把步骤间的依赖关系显性化。你可以在 Tool 调用返回里附带 step_id 和 allowed_next_steps让模型没有选择困难症的机会。3.3 权限边界模糊Reach 过头的代价最后这个坑可能也是所有做 Agent 工程化的人迟早要面对的权限边界。我最早把 Agent 设计得过于开放给它挂了一个“全库查询”工具结果测试的时候用户只是问了一句“你们能不能看到我买过的所有东西”Agent 就真的调了全库接口把用户的历史订单全部拉出来准备“贴心分析”。从技术上说它做得很对从产品伦理和合规角度说这是个危险信号。Agent 的触达能力越强权限管控就必须越细。Agent-Reach 现在的规则是在工具注册表里每个工具都绑定一个最小权限标签用户的每次会话发起时系统先解析用户身份给出一张“票据”里面写清楚这个用户在这轮会话里可以触达哪些域、不可以触达哪些域。执行沙箱在每一次工具调用前都会校验票据。我把权限分成了三个维度数据范围只能查自己的数据还是可以查跨用户数据还是能查全量数据。操作范围只读查询还是可以发起状态变更还是可以触发资金流转类操作。时间范围是否可以访问历史数据是否可以发起异步任务还是只能在本次会话内生效。这套权限模型并不能解决所有问题但它至少让 Agent 的每次触达都有据可查。审计日志里记录了每一次调用的用户、工具、参数、结果摘要和决策理由出问题的时候能回溯到具体的中间环节而不是只留下一句“Agent 干的”。4. 实测数据同一批任务Agent-Reach 改进了多少4.1 对照测试的设计思路架构定型之后我压着团队做了一轮对照测试不能靠感觉说它好用得有数据。测试集拿的是我们线上客服团队的真实脱敏工单一共 320 条覆盖售前咨询、订单查询、退换货申请、物流催查、发票开具、批量数据处理六类任务。每类任务有若干条标准操作路径我们给每条路径都配了下游系统的模拟桩mock保证可以重复执行。对照方案是三组基线组 A裸模型 Prompt 里列出全部工具描述无路由、无校验、无压缩。方案组 B模型 Agent-Reach 两段式路由 工具注册表 反馈压缩器但没有参数校验和权限管控。完整方案组 CAgent-Reach 全功能包含参数校验、重试、有限状态机、权限票据。评价指标有三个任务完成率、单任务平均调用次数、人工介入率。4.2 数据结果和几个反常识发现整理后的结果如下方案任务完成率平均工具调用次数人工介入率A裸模型61.8%4.233.4%B含路由与压缩82.1%3.518.1%C全功能91.6%2.89.4%先说最直观的全功能方案的完成率比裸模型高出近三十个百分点人工介入率从三分之一降到了不到十分之一。这个差距完全符合我对触达层重要性的判断——模型推理能力大家都能用但触达层的工程化程度决定了最终系统的上限。再说两个反直觉的发现。第一平均调用次数不是越少越好。组 B 里有一类任务是“物流催查”模型经常只调用一个快递查询接口就草草收尾看起来省了步骤实际任务并没有真正完成。组 C 由于有限状态机卡了一步一校验反而会让模型多调用一次“确认运单是否签收”的查询。表面上是多了步骤但任务完成率更高。所以我在统计时额外加了“有效调用次数”也就是对最终结果有贡献的调用。这个指标下组 C 的均值只有 2.1 次组 B 是 2.9 次。第二反馈压缩器带来的提升比我想象中大。我把组 B 里压缩器去掉跑了一轮完成率从 82.1% 掉回 72.5%。这个模块没有任何模型推理开销纯工程实现但效果立竿见影。很多团队花大量精力调 Prompt反而忽略了模型读到的返回信息质量。记住模型是一个文本处理器你喂给它什么文本它就用什么文本思考。5. Agent-Reach 的下一步多智能体协作与系统融合5.1 一个 Agent 不够用时的触达问题Agent-Reach 目前解决的是一个主 Agent 触达多个外部工具的场景。但产品越做越深我开始遇到新的边界一个 Agent 包打天下的模式在大规模复杂任务面前撑不住。举个实际例子。我们的客服机器人早期只需要处理订单和物流。后来产品经理说要把“商品库存查询”“最近门店定位”“优惠券计算”也加进来。每个域都有自己的业务逻辑和专属工具集。如果全塞进一个主 Agent路由冲突是必然的——用户说“我家楼下门店有这款鞋吗”这个请求同时涉及库存、门店、优惠券三个域让一个 Agent 全权处理它会在工具选择上反复横跳。Agent-Reach 的应对方式是往主 Agent 之下再挂一层“域 Agent”。每个域 Agent 只负责一个垂直业务域比如一个专门管订单、一个专门管库存、一个专门管优惠券。主 Agent 不再直接触达具体工具而是负责识别请求属于哪个域再把请求转发给对应域 Agent。从触达的角度看主 Agent 触达的是“域”域 Agent 触达的是“工具”。这样每一层的路由目标数量都保持在个位数准确率和响应速度都有了保障。5.2 两步走的接入策略最后聊聊 Agent-Reach 怎么和现有系统融合以及我的个人教训。我强烈不建议把旧系统的接口直接暴露给 Agent。旧系统往往没有为机器调用设计接口含义模糊、错误码五花八门、字段还有历史包袱。我的做法是在旧系统外面包一层“防腐层”专门把老接口翻译成干净的、面向 Agent 的工具接口。这层翻译的工作量不算小但它把脏逻辑隔离在了外面后续旧系统升级换代时Agent 侧完全不受影响。另外灰度上线一定要做。我们第一轮只把 5% 的流量切给带 Agent-Reach 的机器人跑了整整一周盯日志、盯结果抽样。确认完成率稳定到 90% 以上、人工介入率降到 10% 以下之后才逐渐放量到 50%、100%。这一步不是为了保守而是为了给所有可能的坑留出暴露时间。你永远无法在测试集里模拟真实用户的所有问法线上日志才是最终的考试卷。我觉得 Agent-Reach 这个名字起得很贴切因为整个项目做下来我最大的感受就是AI 这只触手能伸多远完全取决于你为它搭建的轨道有多扎实。模型负责聪不聪明架构才决定它靠不靠谱。如果你也在做 Agent 的工程化落地希望这套设计和那些踩过的坑能让你少走几段弯路。