做 Agent 这一年多我最大的感触是模型越来越聪明但桥越来越难搭。Agent-Reach 这个项目就是被这座“桥”逼出来的。去年年底我接手一个任务模型在纸面上规划得头头是道——先查库存、再下订单、然后通知物流每一步都合理。可真让它去执行当场抓瞎库存查不到订单下不了物流接口连密钥都找不到。问题不在模型的推理能力在于“够不着”。大模型再能思考也只是个大脑没有手、没有眼碰不到你系统里的任何数据、任何接口。Agent-Reach 要做的就是给这个大脑装上手和眼让它能稳定地触达外部世界、调用真实工具、完成多步骤的真实任务。这个项目从零搭到 V3我踩了不少坑也想明白了很多事。我不打算把它写成一份标准文档而是把搭建过程中的架构取舍、工具定义细节、上下文管理、安全边界和实测数据原原本本摊开来讲。不管你是刚接触 AI Agent 的开发者还是已经在做复杂 Agent 编排的老手这篇文章里总有一些可以直接拿去用的经验。1. 先搞清楚Agent 要“触达”的对象和边界是什么1.1 大脑和手之间的鸿沟在哪里先讲一个我常用来说明问题的类比。你可以把大模型想象成一个刚入职的高材生思维敏捷、逻辑清晰、记忆力超群。但这个人有两个致命短板第一他没有手脚没法自己打开电脑、点按钮、填表单第二他没带通讯录不知道你公司里谁负责哪块业务。你跟他开会他能把方案说得天花乱坠可散会之后什么都做不了。Agent 的“触达能力”就是给这个高材生装上手、脚和通讯录。具体来说它覆盖三类能力第一类是调用外部工具比如查数据库、调 API、发邮件第二类是读写外部状态比如文件系统的读写、Redis 里的缓存、数据库里的记录第三类是获取实时信息比如网页内容、监控指标、用户的最新输入。凡是要“跟模型本身之外的世界打交道”的能力都算触达范畴。这个划分决定了一个 Agent 能走多远。你模型再聪明如果触达层是断的那它做任何事都只能靠“猜”——猜一下库存有多少、猜一下订单状态是什么。猜出来的结果你也不敢信。所以 AI Agent 的上限很大程度上不是由模型智能决定的而是由触达层的广度和稳定度决定的。这句话是我做了半年之后才真正理解的之前我也天真地以为换个更强的模型就万事大吉。举个具体的例子你就明白了。同样是“帮我查一下订单 O-1024 到哪了”这句话一个只靠模型脑补的系统会这么回答它可能根据它见过的物流知识猜测订单可能在运输途中然后给你一个听起来很合理但完全无法验证的答复。而接入了 Agent-Reach 的系统会先调用订单查询接口再调用物流轨迹接口最后拿着真实的物流节点告诉你“订单已到达本市分拣中心预计明天派送。”两者的差别就是“编故事”和“查事实”的差别。1.2 Agent-Reach 的职责边界项目启动之前我花了很长时间定义 Agent-Reach 到底管什么、不管什么。这一步在我心里比写第一行代码还要重要。边界不清的话后面一定会陷入“什么功能都想往里塞”的泥潭最后做成一个四不像。我的划分是这样Agent-Reach 只管触达层。它的职责就三条。第一条把模型的调用请求翻译成真实可执行的工具调用包括参数校验、格式转换、别名映射第二条把工具执行的结果翻译成模型容易理解的反馈包括成功、部分成功、失败三种状态的统一包装第三条在请求和反馈这两条通路之间做好状态管理、权限控制和安全审计。它不管模型的推理策略那是规划层的事也不管业务逻辑本身那是你后端服务的事。有人问我能不能在 Agent-Reach 里塞一个代码生成模块让 Agent 自己写代码自己执行。我的回答是这是另一个独立的问题不是 Agent-Reach 的本职。守住边界你的项目才不会膨胀成一个什么都做、什么都做不好的大杂烩。这个边界的价值我在一次需求评审里感受特别深。产品经理提了一个需求让 Agent 在回答用户问题时自动生成数据报表并发送到用户邮箱。拆解下来这其实横跨了三层生成报表是业务逻辑属于后端发送邮件是工具调用属于 Agent-Reach 的触达层而“判断用户是否需要报表、生成什么报表”是规划层的事。因为边界清楚我们很快就把这个需求拆成了三个独立模块分别实现谁也没有被谁牵制。2. Agent-Reach 的核心架构规划、触达、执行三层怎么协作2.1 三层结构的设计思路Agent-Reach 的整体结构我拆成三层规划层Planner、触达层Reacher、执行层Executor。名字是拍脑袋起的但职责划分是在一次次翻车里磨出来的。规划层是模型直接打交道的部分。它接收用户的请求输出一个任务序列或者直接输出对工具调用的描述。这一层主要依赖大模型本身的推理和指令跟随能力你不需要写太多代码关键是给模型一份清晰、完整的工具清单让它明确知道“自己能干什么、不能干什么”。触达层是 Agent-Reach 真正的心脏相当于一个路由中枢。它干四件事校验模型输出的工具调用是否合法、把模型给出的参数映射成实际的 API 请求参数、决定执行优先级和并发策略、把执行结果转换成统一的反馈结构。模型说“查一下 SKU-2024-0087 的库存”触达层负责把它翻译成对库存服务的一次实际 HTTP 调用再把返回的 JSON 变成一句话反馈。执行层是真正碰外部系统的地方。它运行在独立的沙箱进程里有独立的超时控制、重试机制和资源配额。为什么一定要独立进程因为我踩过坑Agent 调的某个第三方 API 偶发卡顿直接把我的 Agent 主进程拖死了心跳全断。后来我把执行层拆出去所有外部网络请求只发生在执行层主进程永远保持稳定卡顿最多导致单次工具调用失败不会牵一发动全身。2.2 工具注册表能力清单的正确打开方式工具注册表是触达层的核心数据结构。我把它设计成一张配置表外加一个索引每个工具注册的信息包括工具名称、功能描述、参数 Schema、入口地址、访问凭据、超时时间、执行模式同步还是异步、最大并发数。注册表里最容易被低估的是描述字段的长度控制。工具描述写太短模型不知道什么时候该调用写太长又白白占用上下文窗口。我的经验是控制在 50 到 120 个中文字符之间把三件事讲清楚就够了这个工具是干什么的、什么场景下用、什么场景下不要用。下面是简化后的注册项示例{ tool_name: query_stock, description: 查询指定 SKU 的实时库存。当用户询问有没有货还剩多少时使用。不要用此工具查询价格。, parameters: { type: object, properties: { sku_id: { type: string, description: 商品唯一编码如 SKU-2024-0087 }, warehouse: { type: string, enum: [华东, 华南, 华北], description: 仓库区域默认华东 } }, required: [sku_id] }, endpoint: http://inventory.internal:8080/api/stock, timeout_ms: 3000, concurrency_limit: 5 }这套结构跑了一段时间之后我发现一个特别容易忽视的点参数 Schema 不能只给类型要锁死枚举和取值范围。模型在参数生成上非常擅长“自由发挥”你不给枚举它就能给你造出一个“西部仓库”来。后面我会专门讲这块这里先记住一个原则宁可把约束写得严苛也别给模型留太多想象空间。2.3 执行结果的结构化回传模型调用完工具之后它读的不是 API 原始返回的 JSON而是你加工后的反馈文本。这个环节极其重要但很多人忽略。原始返回里通常塞满了对模型判断毫无帮助的字段HTTP 状态码、request_id、内部错误码、各种嵌套结构。模型读完这些噪音反而不知道该依据什么来决策。Agent-Reach 执行层的最后一个环节我称之为“结果整形”。所有的执行结果统一归成三种状态SUCCESS成功、PARTIAL部分成功、FAIL失败每种状态都必须附带一个能帮助模型决定下一步的说明。举个例子。查询库存成功时我不把整个 JSON 丢给模型而是加工成一句话“库存查询成功SKU-2024-0087 华东仓 12 件华南仓 0 件。”如果华南仓缺货我还会补一句“该 SKU 在华南仓已断货可考虑调拨或推荐替代品”。这比让模型自己从字段堆里找结论稳得多。实测下来加工过的反馈能把模型后续决策的准确率提升至少两成——这个数字来自我们对 500 次真实调用的对比统计。3. 工具定义是成败关键写接口描述比写代码更需要耐心3.1 描述词的“颗粒度”陷阱这是整个 Agent-Reach 项目里我最想展开讲的部分。很多人把工具定义当成写 API 文档措辞随意结果模型频繁误调用然后一脸无辜地说“是模型不够聪明”。其实责任一半在模型的稳定性另一半在工具定义写得不清不楚。我犯过的典型错误是把工具描述写得太宏。比如给发通知的工具写“向用户发送消息”看着没毛病但模型在需要查询的时候也可能顺手调它——因为描述根本没区分什么场景该用、什么场景不该用。后来我改成“当用户明确要求发送提醒、验证码或营销消息时使用仅用于‘发送’动作查询消息状态请调 query_message。”加上正向场景和负向排除之后误调率肉眼可见地降了下来。颗粒度控制还有另一个极端就是纠结于实现细节。比如描述里写“本工具基于 HTTP POST 方法Content-Type 为 application/json鉴权方式采用 Bearer Token”。这些对模型没有实际帮助它不需要知道传输层的事只需要知道“这个工具干什么、什么时候用它”。实现细节应该放在执行层的代码里放错位置就是上下文浪费。3.2 参数约束要锁到枚举级别参数约束的问题值得单独拿出来讲。模型处理自由文本参数时容易犯两类错一是把自然语言里的同义词直接传进去用户说“南方仓库”它就传“南方仓库”而你的系统里只认“华南仓”二是格式错误用户说“12月1日”它就传“2024/12/1”而接口要的是 ISO 格式“2024-12-01”。我的解决办法是在参数 Schema 上做两层约束。第一层是静态约束也就是枚举和正则表达式。模型生成的参数必须匹配不匹配就拒绝执行并把错误信息返回给模型让它自己修正。这一层能挡住大部分格式问题。第二层是动态归一化在执行层里维护一张别名映射表把常见说法映射到标准值。比如“南方仓库”“南部仓”“南仓”统统映射到“华南”。这样即使模型过了第一层第二层还能兜住表达差异。这套两层机制上线之后参数类错误占所有工具调用错误的比例从接近四成降到了百分之五以内。这个数字我至今还留着记录因为它证明了与其指望模型更准不如把护栏修得更密。3.3 错误返回必须“指导下一步”工具调用失败不是异常是常态。网络抖动、服务过载、参数边界哪个都是说起来就来的事。但如果失败信息的写法不对Agent 就会陷入死循环——用一模一样的方式反复重试同一个失败的工具token 烧得飞快问题一个没解决。我总结的失败反馈模板包含三个要素发生了什么、可能的原因、建议的下一步。举个实际例子“库存查询失败HTTP 502 网关错误。可能原因上游库存服务暂时不可用。建议等待数秒后重试或改用备用工具 query_stock_secondary。”关键差别在于最后那句“建议的下一步”。模型有了明确的出口就不会一根筋地重试。同时我在执行层加了失败计数同一个工具连续失败三次Agent-Reach 会主动打断当前重试序列并切换策略必要时候直接向用户报告“这个工具当前不可用”。这招帮我省下了大量冤枉的 token 消耗。4. 多步任务的编排与上下文管理让 Agent 记住自己干到哪了4.1 任务快照机制的设计Agent 做真实业务很少一步到位。查库存、下订单、通知物流这是三步每一步都可能涉及不同的工具、不同的参数依赖。这里最大的难点是状态管理第二步要用第一步的结果模型靠什么记住最朴素的想法是“全塞上下文里让模型自己记”。理论上可行但步骤一多上下文越来越长模型会逐渐遗忘关键信息尤其是中间产物。我在 Agent-Reach 里引入了“任务快照”机制每完成一步触达层就把这一步的关键输出提取出来压缩成结构化快照单独存起来不堆在对话上下文里。模型手里只保留快照的摘要需要时再按需读取。这个机制有点像写代码时的习惯把中间变量单独存一下而不是把所有计算过程挤在一行里。快照的粒度我调了很多次最后稳定在每条不超过 150 个 token只保留四要素字段名、值、时间戳、来源步骤。太长会占上下文太短又丢信息150 是个平衡点。4.2 重试与循环的终止条件我见过最惨的一次事故Agent 因为上游工具返回格式意外变化在一个循环里转了四十多分钟最后失败了。事后一查账单烧掉的 token 足够跑几百次完整任务。那次之后我把重试和循环的终止条件立成了硬性规范写进 Agent-Reach 的配置里不可被模型自行绕过。所有循环必须同时受三个条件约束最大轮数默认 5 轮最大连续失败次数默认 3 次最大 token 消耗默认 40 万。任何一条先到Agent-Reach 就强制终止循环把当前状态打包成一份“未完成任务报告”返回给上层。报告里包含已完成步骤、失败原因和断点位置这样人工介入时能快速接手不用从头再来。还有一个容易踩的坑是异步工具调用的轮询。耗时任务比如生成月度报表需要异步提交加轮询的方式。轮询频率如果拍脑袋设成每秒一次光是轮询请求就能压垮下游服务。我用指数退避策略1 秒、2 秒、4 秒上限 30 秒一次。既保证及时拿到结果又不给系统施压。4.3 上下文窗口的主动清理多步任务的另一个隐患是上下文污染。每调用一次工具就有输入和输出累积起来很快就逼近上下文上限。不管的话模型会出现两种症状要么遗忘早期目标把当前步骤做偏了要么拿无关的历史信息当决策依据答非所问。我的策略是主动压缩而不是被动截断。每完成一个子任务就把该子任务对应的一整条工具调用链条从上下文里摘掉替换成一条快照摘要。粗看像是“丢掉历史”实际上是把历史转为结构化摘要信息密度反而更高。实测下来单次会话的有效上下文长度能延长两到三倍而关键信息的保持率没有明显下降。对长任务来说这几乎决定了一个 Agent 能不能活着跑完整个流程。5. 触达权限与安全边界能力越强越要锁链5.1 工具集的最小必要配给让 Agent 触达外部世界本质上是把一部分操作权交了出去。能力越强风险的面就越大。我在安全上定的第一条原则是默认绝不暴露全量工具集。很多 Agent 项目为了省事把所有工具一股脑暴露给模型。但在实际运营中模型在工具选择上偶尔会做出匪夷所思的决定。我遇到过一次用户只是问“今天天气怎么样”模型却顺手调用了“发送营销邮件”的工具。要不是权限校验拦在前面那封邮件就真发出去了。Agent-Reach 的权限模型是这样每个会话绑定一个工具子集子集由创建会话的人或上层系统指定。子集之外的任何工具就算模型在参数里写进去了触达层也会直接拒绝并把拒绝原因作为反馈传回模型。拒绝信息是这个动作不在当前会话的权限范围内。模型看到后会调整方案而不是继续硬闯。5.2 高危操作的二次确认有些工具的副作用太大必须特殊对待。删除数据、发送对外邮件、修改线上配置都属于这一类。我在注册表里给这类工具打了一个标记requires_confirmation。带标记的工具被调用时Agent-Reach 不会直接执行而是进入一个确认态由上层决定放不放行。确认态的放行方式有两种。一种是把控制权交给人工弹出一个待确认任务另一种是要求模型先给出明确的执行理由再由规则引擎判定理由是否充分。第二种适合那些完全可以自动化的场景但规则引擎的判定条件一定要写得保守拿不准就默认拒绝。安全这种事宁严勿宽。5.3 审计日志与配额限流审计日志是我从事故里学到的必修课。每次工具调用我记录八个字段时间戳、会话 ID、工具名、参数摘要、执行结果、耗时、调用者模型类型、决策链摘要。最后一项最关键它是把模型当时的关键推理步骤截取出来存下。出问题时能完整回放整个决策过程而不是对着烧钱记录瞎猜。这套日志上线第三周就帮我定位了一次严重事故参数错位导致线上库存被误减。如果没有决策链摘要我根本分不清是模型判断错了还是代码映射错了排查时间至少要翻倍。配额限流同样不能省。每个会话每分钟最大工具调用数、每个工具的最大并发数、每个模型实例的 QPS 上限都要提前设好。我见过的情况是Agent 在一个并发循环里同时发出几十个相同请求直接把下游服务打挂了。限流配置看着烦琐但它保证的是整个系统不会因为 Agent 的“过度热情”而崩溃。6. 实测结果与避坑记录三个版本的迭代教训6.1 V0 到 V3 的改动路线Agent-Reach 从想法到稳定版经历了三次大改。V0 是最原始的原型所有工具调用写在一个巨型函数里模型生成的参数直接原样传进去。上线当天就崩了模型输出一个不存在的工具名系统直接抛异常而代码里根本没有兜底逻辑。这个教训让我认识到模型输出是不可控的所有环节都必须按“模型会乱来”来设计。V1 引入了工具注册表把“模型要调什么”和“代码里有什么”解耦。这版能跑了但工具描述写得随意误调率高达三成多轮对话经常走到岔路上去。V2 开始认真打磨描述和参数约束加了枚举、正则、别名映射误调率降到一成以下这时候才真正具备实用价值。V3 补上了任务快照、终止条件、权限隔离和审计日志Agent-Reach 才达到我心目中“可以放心交出去”的标准。6.2 不同模型的实测对比同一套工具集、同一批测试场景我对比了三种典型模型接入 Agent-Reach 的表现。测试集是 20 个真实业务任务覆盖查询、写入、多步编排、异常恢复四类场景。模型类型工具调用成功率平均每任务 token 消耗误调率多步任务完成率场景 A强逻辑推理型86%2.1 万13%71%场景 B强指令跟随型93%1.7 万5%84%场景 C轻量开源模型74%2.6 万21%58%这份数据告诉我两件事。第一工具定义质量和参数约束的影响完全可以和模型本身的差距相比肩。与其换个更贵的模型不如先把工具定义做扎实。第二轻量模型在多步编排上明显吃力。如果业务场景是复杂任务编排选型时别只看单步准确率要多测几步连环调用。6.3 工具排序与 Few-shot 的小技巧最后分享两个不起眼但很管用的调优点。第一个是工具列表的顺序。很多模型对工具列表的开头几项和结尾几项更敏感中间位置的容易被忽视。我把高频工具固定在列表前几位然后定期根据调用统计动态调整顺序。这个操作看起来只是挪了挪位置但实测把高频工具的调用正确率提升了约八个百分点。第二个是 few-shot 示例。遇到工具选择容易混淆的场景我在系统提示词里附上一两个完整的决策示例展示“这种情况下应该选哪个工具、为什么”的推理过程。示例必须选有区分度的最好就是你实际观察到模型容易选错的那种场景。这种隐式教学比在描述里反复强调“不要乱用”有效得多。我个人在 Agent-Reach 上线后最大的体会是做 Agent 触达层真正难的不是写代码是克制。克制住把全部工具塞给模型的冲动克制住让一个 Agent 一步做完所有事的贪心也克制住“出了问题就让模型再想想”的偷懒。每一条边界都是拿事故换来的每次收敛都是拿账单烧出来的。如果你的项目恰好也卡在“模型很聪明但够不着”这一步希望这些记录能帮你把桥搭得更稳一点。