1. 先从三个真实场景说起Agent 为什么需要 Reach去年下半年我密集做了一批 LLM Agent 项目发现一个很普遍的现象模型本身的能力早就不是瓶颈了真正的瓶颈是够不着。我举个例子某个客服场景的 Agent 已经能流畅地理解用户意图分辨出我要退货和我要换货的区别回答也很有礼貌但一让它真正去查订单、走退款流程它就跟我说抱歉我暂时无法操作。另一个做经营分析的 Agent能给出一份逻辑完整的报告框架却连数据库都连不上里面的数字全是它合理猜测出来的。还有一个做日程管理的 Agent规划能力很强排出来的日程表有板有眼但它始终没触发任何一方的日历接口也就是说它的计划从头到尾没有在现实世界里产生过任何作用。这三个场景指向同一个问题我给它起了个名字叫Agent-Reach直译过来就是代理的可达范围。它指的是一个 Agent 在具体任务语境里到底能实际触达、操作、改变多少资源。你模型再聪明、推理再强如果你的 Agent 摸不到订单表、连不上数据库、调不动日历服务它本质上还是一个会写作文的聊天机器人。Reach 不够Agent 的智能就是悬空的。这个词后来在我团队内部变成了一个正式的设计维度。我们评估一个 Agent 方案不再只看它响应得聪不聪明而是先问三个问题它能触达哪些外部系统它能在多大的数据范围内工作它执行了操作之后影响能不能被观测、被回滚这三个问题串起来就是一个 Agent 的 Reach 全貌。这篇文章我想把 Agent-Reach 这个概念完整拆开讲讲我在把能说会道的 Agent 变成能办成事的 Agent 过程中总结出来的四层 Reach 模型、一整套落地的架构设计以及大量踩坑之后才愿意写下来的经验。适合正在做 Agent 应用、或者正准备从 Demo 往生产环境推的工程师。如果你只是对 AI 应用感兴趣也完全可以读我会尽量把复杂的设计讲得像装修房子一样清楚。2. Reach 不是会调 API这么简单拆成四个层级很多人听到 Reach 的第一反应是不就是 Agent 能调多少个 API 吗我一开始也这么想但做深了才发现把 Reach 拆细一点很多矛盾会自己浮出来。我把 Agent-Reach 拆成四个层级工具可达性、数据可达性、行动可达性、控制可达性。每一层解决一个完全不同的问题缺了任何一层Agent 都会在真实任务里掉链子。2.1 工具可达性Agent 的手能伸多远工具可达性是大家最熟悉的一层指的是 Agent 能调用哪些函数、接口、插件。你要做一个能查天气的 Agent就得给它接上天气 API要做一个能操作数据库的 Agent就得给它提供 SQL 执行工具。这一层的核心问题是能力是否存在。但这里有个很容易被忽略的细节能力存在和 Agent知道怎么用是两回事。很多 Agent 项目的工具函数堆了一大堆但函数描述写得极烂——比如读取库存数据这种一句话描述模型根本不知道该传什么参数、返回什么结构、什么时候该调用。结果就是工具躺在注册表里Agent 却绕开它去猜答案。工具可达性不仅仅是把函数挂上去还要让模型对每个工具形成准确的调用理解。这一点后面会展开讲。2.2 数据可达性Agent 的眼睛能看到什么第二层是数据可达性。一个 Agent 哪怕有工具如果拿不到及时、完整、可信的数据照样干不成事。我见过很多 Agent 被问到最近的销售数据怎么样时选择从历史对话里拼凑信息或者直接编一个有模有样的数字。这不是模型故意撒谎而是它的数据上下文里根本没有真实数据的入口。数据可达性要解决的是Agent 在什么数据范围内工作、数据以什么方式注入、新鲜度如何保证。这里有一个常见误区认为把数据库连接给 Agent 就算数据可达了。其实不是数据可达性还包括该给的数据给了、不该给的数据没给。比如一个面向内部运营的 Agent你让它访问全公司的订单表结果它每次回答都要扫几百万行数据又慢又危险这时候你就需要给它做一个数据视野裁剪——它只能看到与自己任务域相关的视图。我用一个词来概括数据可达性的本质上下文里的数据边界。Agent 的任务表现百分之七十取决于它拿到什么数据而不是它能推理得多深。2.3 行动可达性Agent 能不能在现实世界留下痕迹第三层是行动可达性这是很多人做 Agent 时最容易卡住的一层。工具可达性和数据可达性都解决了Agent 可以看到很多信息但看到和 改变是两回事。行动可达性指的是Agent 能不能真正执行具有外部效果的操作比如写一条记录、发一封邮件、更新一个字段、触发一个流程。这一层的难点不是技术而是责任边界。让 Agent 给你生成一段邮件草稿很容易让它未经确认就把邮件发出去很多团队不敢做。我的建议是行动可达性一定要分权交易哪些操作是 Agent 可以自动执行的哪些需要人工确认。我见过最好的实践是把操作划分成三档只读操作、可逆操作、不可逆操作。只读操作自动放行可逆操作允许执行但记录审计日志不可逆操作必须过一道人工闸门。后面我会专门讲这个设计。2.4 控制可达性人在回路里的刹车最后一层是我认为最反直觉的控制可达性。它指的是当 Agent 执行到一半出问题的时候系统能不能让人介入、能不能安全停下来、能不能优雅地把任务移交出去。我做一个自动化 Agent 的时候给它配了一个手动接管机制Agent 在执行关键步骤之前会先输出一个计划让我确认执行过程中每一步产生的临时结果都会写到一个指定的暂存区如果某一步失败了或者我主动发一条特殊指令Agent 会立刻停止执行并返回当前状态。后来我把这个机制抽象成一个小函数放在整个 Agent 主循环外面事实证明这玩意儿比任何花哨的提示词工程都管用。你可以把前两层理解成 Agent 的手和眼第三层是 Agent 的执行力第四层则是刹车系统。一辆车马力再大刹车不灵你也不敢上路。我见过太多 Agent 项目能力和工具都堆得满满的唯独没设计好怎么让它停下来结果一上线就出乱子。这个四层模型是我每次设计 Agent 时的第一份图纸。接下来我会讲基于这个模型我实际落地的一套架构——它就是 Agent-Reach 这个名字背后真正的内容。3. Agent-Reach 的架构落地我把 Reach 层设计成了什么样既然 Reach 是一个系统性的问题靠给 Agent 多加几个工具函数是解决不了的。我落地的时候在 Agent 的外围加了一个独立的Reach 层它专门负责Agent 与外部世界之间的所有通道。你可以把这一层想象成一个中间人模型只和这层打交道这一层再去和数据库、API、文件系统、人工审批等打交道。Reach 层的核心组件是四个能力注册中心、能力路由、上下文桥接器、执行沙箱。3.1 能力注册中心用声明式描述替代代码堆砌能力注册中心是第一环它解决的上一节说的工具描述不准问题。我采用的是声明式能力描述即每个能力不再是一段模糊的函数简介而是一份完整的结构化定义包含名称、用途、输入输出参数、约束条件和典型调用示例。举个例子某个数据查询能力的长这样capability: inventory_query description: 按仓库和商品SKU查询实时库存快照返回在库数量和状态。 parameters: - name: warehouse_id type: string required: true description: 仓库编号例如SH01代表上海仓。 - name: sku_list type: array required: true description: 商品SKU列表最多50个。 - name: include_zero type: boolean required: false default: false description: 是否包含库存为零的商品。 output_schema: type: object properties: sku: string quantity: integer status: enum [in_stock, low_stock, out_of_stock] examples: - input: {warehouse_id: SH01, sku_list: [SKU001, SKU002]} output: [{sku: SKU001, quantity: 320, status: in_stock}] rate_limit: 30 calls/min为什么要用这种声明式的方式而不是直接给模型看代码因为模型的工具调用成功率和工具文档的结构化程度高度正相关。你给一张图、一段注释模型知道怎么用你给一堆行内注释分散的函数模型往往会在参数格式上反复出错。声明式描述还能让注册中心做到版本管理——每个能力有版本号模型调用的是旧版本还是新版本日志里一目了然。这里还有一个容易被忽视的点能力描述不应该只面向能做什么还要写清楚不能做什么。在这个例子里如果仓库编号传成不存在的值能力应该直接返回错误而不是返回空列表。把边界条件写清楚会让 Agent 的试错成本大幅下降。3.2 能力路由给 Agent 装一个精选菜单能力注册中心可能积累了几十个甚至上百个能力如果一股脑全塞给模型Reach 是变大了但模型的上下文很快会被工具定义塞满而且选择困难症会显著增加。我采用的方案是加一层能力路由每次请求进来先根据任务意图从注册中心里筛出一批候选能力再按相关度排序、裁剪最后只把最相关的若干个能力描述注入到模型的工具上下文里。这个过程其实很像我们点外卖。注册中心是完整菜单能力路由则根据你今天的口味给你一份推荐菜。别看这个逻辑简单它对效果的影响非常大。我做了一组对比实验同一个 Agent全部能力都注入时工具选择准确率只有 71%经过路由裁剪到 5 个相关能力后准确率提升到了 93%。背后的原理很朴素——候选集越小模型越不会乱选。3.3 上下文桥接器把数据送进模型看得见的地方上下文桥接器解决的是数据可达性落地的最后一个环节。真实系统里数据存在数据库、文件、第三方 API 里Agent 不可能自己去连它需要一个中间人把数据拉出来、加工成模型易于理解的格式再放进上下文。这个桥接器有两个关键设计。第一数据和提示词分离。我不会把数据库连接串、API Key、内部系统地址直接写进系统提示词里而是让桥接器在执行时按需注入。系统提示词里只有一句你的数据上下文由系统自动刷新具体的数据则通过特定的上下文块在运行时替换进去。这样做既安全又避免了每次请求都重复把静态提示词传一遍。第二数据要经过压缩和摘要。很多 Agent 失败不是因为拿不到数据而是拿到的数据太多模型根本处理不过来。我通常在桥接器里做一个摘要层把原始数据先汇总成当前状态简报。比如库存数据有几万行就变成上海仓共 320 个 SKU其中有 27 个库存低于阈值前 5 个是……。模型真正需要的是判断依据而不是原始明细。需要明细的时候它可以通过工具再拉取。3.4 执行沙箱让 Agent 的每一次操作都有撤回键执行沙箱是行动可达性的落地点。所有会产生外部副作用的操作都必须在沙箱里先预演一遍。预演的意思不是模拟而是把操作写到一个临时的暂存区不真正提交。只有等到 Agent 明确完成了整个任务闭环比如所有步骤都成功、结果校验通过沙箱才统一提交这批操作。这个设计参考了数据库事务的思想。Agent 执行一次任务很可能涉及多个操作先查询、再计算、再更新、再通知。如果其中第三步失败了前两步的副作用怎么办传统做法是让 Agent 尽力回滚但模型靠不住。最稳的办法就是延迟提交——整个过程都在暂存区里进行最后一次性提交。真出问题时整个任务直接作废不留半点副作用。我把执行沙箱和一个简单的状态机组合起来每个任务有进行中待确认已提交已中止四个状态。进行中表示操作在暂存区执行待确认表示沙箱已经准备好了最终结果在等人批准已提交表示操作正式生效已中止表示整个任务作废。这个状态机后来成了我们所有 Agent 任务的通用骨架团队内部叫它任务象限。4. 跑通一轮真实任务从用户指令到目标达成理论讲得再多不如走一遍真实流程。我用一个具体的例子说明上述架构是怎么协同工作的。假设要做一个内部运营用的 Agent任务是把 A 仓库的实时库存同步到本周销售周报并在低于安全库存的 SKU 上标注醒目提示。这个任务的特点是既需要读数据又需要写文件还涉及一点判断逻辑非常适合演示 Reach 层的各个环节。第一步用户发出指令。Reach 层先做意图理解识别出三个关键信息仓库是 A 仓库、目标是一份周报文件、动作是同步并标注。第二步能力路由启动从注册中心里筛出三个相关能力库存查询能力、周报读取能力、周报更新能力。这三个能力的描述被注入模型上下文。第三步上下文桥接器预取数据。注意这一步在模型做任何决策之前就已经开始了。桥接器后台把 A 仓库的库存快照和当前周报的结构信息先拉出来压缩成摘要放到上下文的指定区域。模型看到的不是可以查数据库而是A 仓库当前有 158 个 SKU其中 23 个低于安全库存周报文件当前版本为 v3结构包含 SKU、名称、当前库存、安全库存、状态五列。它不是去探索数据而是直接基于数据做判断。在实际代码里这一段的简化实现大概是这样的class ReachContext: def __init__(self, registry, router, bridge): self.registry registry self.router router self.bridge bridge def prepare(self, task): intents self.router.route(task, self.registry.list()) summaries self.bridge.prefetch(intents.required_data) return { intents: intents, data_summaries: summaries, active_capabilities: [c.schema for c in intents.selected] }第四步模型基于摘要生成执行计划而不是直接执行。计划是先用库存查询能力核对数据再用周报更新能力把摘要写入第二行以下的区域最后对比安全库存字段进行标注。Reach 层把计划解析成一组待执行步骤进入沙箱。第五步沙箱开始按计划执行。库存查询能力真正去数据库取数返回完整明细写入暂存区周报更新能力修改的是暂存区的副本原文件没有被改动。执行过程中如果某一步返回了异常比如周报文件被其他同事锁定沙箱立刻中止任务进入可恢复状态Agent 会主动说明周报文件当前被占用我已经暂停了本次操作等你释放文件后我可以继续。第六步所有步骤成功沙箱生成一个待确认事件推送给我。我看了之后确认操作才真正提交到正式文件。这一步是整个设计最有价值的地方Agent 在真实世界里完成了任务但不是以模型直接乱改文件的方式而是以沙箱里重组、确认后提交的可靠方式。这个过程中模型负责的是判断和计划Reach 层负责的是安全和落地。互相不越界。5. 踩坑记录让 Reach 稳定下来的关键细节架构搭完真正的工作才刚开始。我把落地过程中踩过的大坑整理成几条每条都是真金白银换来的经验。5.1 坑一工具描述写得太自然语言模型反而不会用我最早写能力描述时为了让模型读懂用了大量自然语言这个函数用于在库存系统中查询某个商品的数量传入参数是商品号输出的是数量信息。结果模型频繁传错参数、漏传必填项。后来我改成上面那种结构化描述 示例之后问题大幅缓解。我的体会是模型更擅长读更接近 JSON Schema 的东西而不是读人话。能给出输入是什么、输出是什么、示例是什么的工具描述调用成功率远高于那种自然语言写一大堆但结构散乱的描述。这大概是提示词工程里性价比最高的一类投入。5.2 坑二多步骤任务中途失败副作用处理靠模型自觉完全不可行有一次我做一个数据同步任务Agent 先删了目标表里的旧数据再把新数据写进去。结果新数据写入时因为字段格式问题失败了Agent 想了半天最后给出一个好的我已经尽力了就结束了。目标表里的旧数据就这么没了。从那以后延迟提交成了我所有执行沙箱的默认策略。Agent 在沙箱里怎么折腾都行只要没到提交点真实系统就毫发无损。而确认提交这个动作可以交给一个与模型无关的外部流程甚至可以是一个简单的规则所有步骤成功、校验通过、用户确认三件事都成立才提交。5.3 坑三凭证和密钥被模型复述出来有一次我用调试日志检查 Agent 的完整上下文发现数据库连接串被完整地渲染到了对话历史里。如果这个对话被导出或者被用户截图就等于凭证外泄了。教训是任何密钥、token、连接串都不应该以明文字段出现在模型上下文中。解决方案是做个独立的凭证注入层——模型需要查数据时Reach 层自己带上凭证去执行模型只看到结果永远看不到凭证本身。这其实跟最小权限是一个意思只不过最小权限的对象变成了模型上下文。5.4 坑四Reach 越大性能越差我把能力注册中心里面舒舒服服地加了一百多个能力之后发现 Agent 的响应变慢了很多而且经常做出莫名其妙的选择。后来加了能力路由每次只注入一小部分速度和准确率立刻回来。现在我的原则是能力全量注册、按情境裁剪、运行时动态加载。和无关能力不该进上下文相比少即是多。5.5 坑五不要小看日志与可观测性Agent 执行链路比传统程序的调用链复杂得多因为中间隔着模型的不确定性。每次 Reach 动作哪个能力被选中、参数是什么、结果是什么、用了多少 token、耗时多久都要有日志。我见过最痛苦的一次排查Agent 在两天内反复出错但因为日志里只记了最终结果中间每一步的决策过程全是黑盒根本无从定位。后来我把 Reach 层的所有动作都加上了结构化日志记录重建链路变得像看流水账一样清晰。没有可观测性的 Reach 层就是一台没有仪表盘的飞机。6. 边界感Reach 越大越要管住 Agent 的手最后谈一个我越做越觉得重要的话题边界感。Reach 这个词听起来是越大越好真正做下来你会发现一个优质的 Reach 设计不是无限扩大 Agent 的能力范围而是给它划定一个清晰、安全、可解释的边界。我把这个边界拆成三个维度权限边界、操作边界、上下文边界。权限边界是传统的角色权限模型但在 Agent 语境里要特别处理工具级权限。同一套接口不同用户角色的 Agent 能调用到的工具集合应该不一样而且这个集合是可以动态切换的。比如一个实习生用的 Agent只能读数据不能修改一个主管用的 Agent可以生成报告并发送但仍不能删除报表。操作边界的核心是操作分级和人工闸门。我前面提到的只读、可逆、不可逆三档划分具体落地时可以细化为操作类型示例执行策略只读操作查询库存、读取报表自动执行记录审计日志可逆操作写入暂存区、发送草稿沙箱内自动执行提交需确认支持回滚不可逆操作删除数据、批量发布必须人工二次确认且需要管理员权限上表的策略我实际跑了几个月效果很好。它最大的价值不是限制而是让所有人开发者和业务用户对 Agent 能干什么、不能干什么有共识。Agent 的行为越可预期人才越敢放手让它去干。最后是上下文边界。数据可达性不是能拿到多少数据而是在当前任务里应该拿多少数据。我通常会对数据做最小集裁剪不让 Agent 接触与当前任务无关的敏感信息。很多安全事故不是模型坏导致的而是设计时给了模型过大的数据视野。把上下文边界做好等于给 Agent 戴上了一副任务眼镜它只看得到该看的。现在回头看我做 Agent-Reach 这个项目最深的感触是把 Agent 接入现实世界难的不是技术是分寸感。每一次能力接入都意味着信任的扩展每一次自动执行都意味着责任的转移。我的建议是从一个小而清晰的任务域开始把四层 Reach 模型都走一遍把执行沙箱和人工闸门打磨到足够顺手再一步一步扩大 Agent 的触达范围。最后再分享一个我在配置时常用的习惯每次新加一个能力先在只读 人工确认模式下跑至少一天确信它的调用稳定、结果正确、日志清晰之后才考虑放开到自动执行。节奏慢一点后面会省掉大量救火的夜晚。希望这套 Agent-Reach 的思路能帮你少走一些我走过的弯路。