企业官网建设流程全解析

我在去年接手过一个客服售后自动化的项目，需求听起来很简单：让大模型自动查订单、算退款、转人工。结果前后折腾了三个月，最让我头疼的根本不是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 两段式路由 + 工具注册表 + 反馈压缩器，但没有参数校验和权限管控。
• 完整方案组 C：Agent-Reach 全功能，包含参数校验、重试、有限状态机、权限票据。

评价指标有三个：任务完成率、单任务平均调用次数、人工介入率。

4.2 数据结果和几个反常识发现

整理后的结果如下：

先说最直观的：全功能方案的完成率比裸模型高出近三十个百分点，人工介入率从三分之一降到了不到十分之一。这个差距完全符合我对触达层重要性的判断——模型推理能力大家都能用，但触达层的工程化程度决定了最终系统的上限。

再说两个反直觉的发现。第一，平均调用次数不是越少越好。组 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 的工程化落地，希望这套设计和那些踩过的坑，能让你少走几段弯路。