企业官网建设流程全解析

如果你维护过一套接入了五六个外部工具的智能体系统，一定遇到过这样的场景：用户问了一个看起来很简单的问题，模型也理清了思路，可真正去调用工具的时候，要么参数格式不对被服务端拒了，要么第三方接口超时无响应，要么返回了一堆乱七八糟的内容把后续的推理全带偏。我做的这个叫 Agent-Reach 的项目，就是为了收拾这个烂摊子。

Agent-Reach 本身不是一个 Agent 框架，它是一层夹在智能体和外部工具之间的触达层，专门负责解决工具调用中的可达性、可靠性和反馈闭环问题。这篇文章把我从立项、设计、踩坑到实测的完整过程写出来。如果你也在做多工具智能体，里面不少思路应该能直接用上。

1. Agent-Reach想解决的真问题：智能体的手够不到东西

1.1 触达断层到底断在哪

我先说一个具体场景。我维护过一个内部知识问答加自动化执行的系统，用户会提出一类很典型的请求：查一下上个月华东区的销售数据，然后给张三发一封汇总邮件。这个请求拆开是两个动作，一个查数据，一个发邮件。听起来很直接，但在没有触达层的时候，实际发生的事情往往是这样：大模型把查数据的工具选对了，但传日期参数时传成了 2024-01-01，接口要求的却是 20240101，服务端直接报参数错误；或者邮件服务偶发 5 秒无响应，Agent 一直在那等，最后给用户一句 操作超时，请重试。这类问题有个共同特点：模型没选错，意图没理解错，纯粹是触达环节的各种意外把它打断了。

我把这一类问题统称为触达断层。断层可能出在四个地方：工具选择错误、参数转换错误、调用过程异常、结果反馈失真。平时大家更关注大模型的推理能力，很少有人认真对待这四个断层。但真实生产里，用户感知到的这个机器人靠不靠谱，恰恰是由这四个断层决定的。Agent-Reach 就是专门针对这四个断层设计的一层系统。

1.2 为什么现成的编排框架帮不上忙

我刚立项的时候，不少同事问为什么不直接用市面上的 Agent 编排框架。我的观点很明确：编排框架解决的是流程怎么组织的问题，而我面对的是每次调用如何可靠触达的问题，这两件事不是一回事。

编排框架把工具定义成函数，让模型决定调用哪个，看起来省心，但超时、重试、限流、降级、状态观测这些生产特性几乎没有内置。你当然可以在回调里写，但框架的回调机制往往分散在各个层，写到最后就变成一堆补丁。我实际用过一段时间，发现真正需要自己维护的还是那些东西：每个工具的超时阈值、错误码分类、重试策略、并发控制、结果摘要。与其在框架的缝隙里塞补丁，不如把这层单独拿出来做，做成一个所有 Agent 框架都能复用的中间件。

所以 Agent-Reach 的定位从一开始就不是替代编排框架，而是给任何编排框架增加一道可靠触达的保险。上层你可以用任何喜欢的方式组织 prompt，但底层所有工具调用必须经过 Agent-Reach，这一点我在架构上坚持得很死。

2. 整体设计：不抢大模型的活儿，只负责把任务送进门

2.1 触达层在系统里的位置

Agent-Reach 在整个系统里的位置很简单，就是在 Agent 和外部工具之间。完整链路是：用户输入到 Agent，Agent 负责理解意图和组织回复，中间所有工具调用全部交给 Agent-Reach，由它去连各种外部服务，拿回结果后再返回给 Agent 生成最终回答。

我在架构上有一条原则：Agent 不允许直接调用任何外部工具。所有工具调用必须经过 Agent-Reach 的统一入口，比如 POST /reach/execute，传入 task_id、用户 query、可选的候选工具列表。这个设计不是为了多一层网络开销，而是为了把超时、重试、限流、审计全部收敛在一个地方。如果你让 Agent 直接去调每个工具，每个工具都可能是个定时炸弹，出了问题你都不知道该看哪个日志。

触达层内部拆成四个模块：工具注册中心、意图路由、执行器、状态管理器，外加一个审计日志模块。注册中心管有哪些工具可用；意图路由管当前这个任务该选哪个工具；执行器管实际调用并且处理成功和失败；状态管理器管任务现在的进度和上下文。这几个模块都围绕同一个 task_id 协同工作。

2.2 工具注册中心与统一调用协议

每个工具注册的时候需要提供四样东西：id、路由描述、输入 Schema、adapter 函数。我给出一个注册示例：

{ "tool_id": "send_email", "description": "发送邮件给指定用户，常用于通知、告警、汇总报告", "input_schema": { "type": "object", "properties": { "to": {"type": "string", "description": "接收人邮箱"}, "subject": {"type": "string", "description": "邮件主题"}, "body": {"type": "string", "description": "邮件正文"}, "priority": {"type": "string", "enum": ["normal", "high"]} }, "required": ["to", "subject", "body"] }, "adapter": "src/adapters/send_email.py", "timeout_ms": 10000, "fallback": ["send_email_enterprise"] }

这个 Schema 不是给机器看的格式，它同时被三处使用：校验 Agent 传的参数、约束 LLM 生成槽位、生成调用文档。一个好的 Schema 要写清楚字段枚举和示例值，比如 priority 字段只允许 normal 和 high，否则 LLM 很容易自由发挥出一个 low 出来，然后接口就报参数错误。

所有工具的输出统一信封格式：{status, data, error, cost_ms}。status 只用 success 或 error，data 是实际结果，error 里带错误码和原始错误信息，cost_ms 记录这次调用耗时。这个信封的意义是让上层 Agent 只处理一种结构，不需要关心每个工具的原始返回长什么样。真正必要的转换逻辑全部放在 adapter 里，每个工具一个薄适配层，从通用请求格式转换成该工具实际需要的调用方式。老 SOAP 接口、新 REST 接口、甚至是直连数据库，都在 adapter 里收敛掉。

2.3 意图路由到工具映射的两种实现

我最开始用的是让 LLM 直接从工具列表里选一个，工具少的时候还行，工具一多就乱。后来改成两层策略：先 embedding 召回，再 LLM 精排。

第一步，工具注册的时候把 description 和参数示例一起向量化存下来。请求进来时，把用户 query 向量化，用 cosine 相似度召回 top K，K 一般取 5。第二步，把 top5 的工具描述、参数 Schema、用户 query 一起交给 LLM，让 LLM 输出最终的工具 id 和参数。这样做的好处很明显，LLM 不需要从一百个工具里大海捞针，只需要从五个候选里判断，准确率能提高不少。

还有一个更稳的办法是分组路由。当工具数量超过一百个，embedding 召回也不太可靠。我会先按领域分成大组，第一层只判断 query 属于哪个领域，第二层在组内做具体选择和参数填充。分组的边界要设计得尽量互斥，比如数据查询类和消息通知类，避免一个 query 在两个组里都有高分。如果出现这种情况，就需要检查分组边界是不是定义得太含糊了。

安全兜底也很关键。如果 top1 和 top2 的相似度差值小于 0.05，我不会自动选，而是把两个选项返回给用户确认。这种多问一句的代价，远小于选错工具之后重新处理的代价。工具选错了，不只是报错的问题，如果是写操作类工具，还可能造成脏数据。

3. 核心机制的细节：状态机、超时重试、降级会话

3.1 任务状态机：从pending到failed的完整流转

状态流转是 Agent-Reach 最核心的部分。一个任务的完整状态是 pending 到 routed 到 executing 到 succeeded，或者 failed_with_reason。executing 内部还有一个重试循环，最多三次。状态机的好处是，任务在任何时刻都有明确的位置，出问题可以回放，而且错误分支可以根据错误类型分开处理。

我举一个状态的例子：

{ "task_id": "task_20250110_001", "user_query": "查一下上个月华东区销售数据", "status": "executing", "selected_tool": "query_sales", "params": { "region": "华东区", "month": "202412" }, "attempt": 2, "error_history": ["timeout", "timeout"], "created_at": "2025-01-10T10:00:00Z", "updated_at": "2025-01-10T10:00:06Z" }

状态存在 Redis 里，key 是 task_id，TTL 设 24 小时。为什么不做成纯内存？因为 Agent-Reach 服务可能会有多个副本，状态必须共享，而且 Redis 天然支持 TTL，可以自动清理老任务。另一个原因是排查问题方便，哪怕任务早就结束了，24 小时内还能找到完整的流转历史。

错误分支要按类型区分，这一点很多人会忽略。timeout 可以重试，schema_error 重试多少次都没用，应该直接返回给上层重新生成参数。service_error 要看具体错误码，有的可以重试，有的不能。limit_exceeded 则应该进入排队而不是盲目重试，否则只会加重对方的限流。

3.2 超时和重试参数为什么这么定

超时参数不是拍脑袋定的。上线前我统计了一周内每个工具的延迟分布：内部 API 的 P95 大约 1.2 秒，P99 大约 2.9 秒；外部第三方 API 的 P95 大约 4.5 秒，P99 大约 8.1 秒。

我把超时设置为 P99 的 1.5 倍，再向上取整到常用值。内部 API 用 3 秒，外部 API 用 10 秒，批量任务用 30 秒。这么设的原因很简单：绝大多数正常请求不会因为超时被误杀，但异常情况下用户也不至于等太久。如果设成 P99 的三五倍，那 99% 的请求会等得非常久。如果设成 P95，那正常的慢请求也会被频繁打断，反而降低成功率。

重试采用指数退避，1 秒、2 秒、4 秒，最多三次。第一次超时多半是网络抖动，隔 1 秒再试，恢复概率已经很高。第三次还不行，说明下游真的有问题，继续重试只会浪费资源和延长用户等待。这里有个细节容易被忽略：重试之前要检查是否收到了部分响应。比如调用方已经拿到响应体了，即使状态码是 5xx，也不能盲目重试，因为对写操作来说，重试可能造成重复执行。

3.3 降级路径：失败不是终点，是备选

每个工具注册的时候都可以配置 fallback 链。主用工具挂了，自动切换备用工具。比如主用 query_sales 接口，fallback 可以是数仓的离线查询；主用第三方天气预报，fallback 可以是公开网页抓取。

触发条件我设成：主工具连续失败两次，或者单次超时后立即降级，不再等第三次重试。原因是超时本身就是比较强烈的故障信号，与其让用户多等一轮重试，不如直接换路径。让用户为系统的故障买单，体验会非常差。

fallback 也失败了怎么办？我会明确返回给上层这一句：该信息暂时无法获取，然后把完整的错误上下文写入审计日志。这台系统里有一条红线：绝对不允许 Agent 在没有真实数据的情况下编造结果。模型可以在推理层面做分析，但涉及具体数字、事实、状态的字段，必须有来源。宁可让用户知道系统现在拿不到，也不能让模型编一个看起来合理的假数据。这个原则我们在项目里反复强调，也在代码层面做了强制校验。

4. 实测下来的一组数据与三个坑

4.1 迭代前后的触达成功率对比

Agent-Reach 上线后跑了两周，数据对比下来还是比较明显的：

数据来自内部项目两周统计，样本量约 8000 次工具调用。可能有人会说任务复杂度不一样，不能直接对比，但整体趋势很能说明问题。成功率提升主要来自统一的超时重试和参数校验，响应时间下降是因为之前大量请求卡在长超时的黑洞里，用户感知的卡住，其实很多是异常等待。

参数校验的收益容易被低估。我统计过，没做 schema 校验前，很多失败不是服务端拒绝，而是参数不合法导致的无效调用。这类问题用户看不到具体细节，只会觉得这个机器人不听使唤。而且无效调用会消耗 LLM 的推理成本，等于花了钱没办事。

4.2 坑一：LLM生成的参数经常不符合工具schema

开发到第二周，我们遇到一个很窝火的问题：模型明明选对了工具，但参数经常错。日期格式不对、枚举值超范围、必填字段缺失，一周内 schema_error 占所有失败的三分之一以上。

排查之后发现，根因是让 LLM 自由生成 JSON 这个方式本身太乐观。LLM 擅长的是语义理解，不是严格遵守格式。它可能知道该传一个日期，但不会在意接口要求的是 20240101 还是 2024-01-01。后来我把工具调用方式从自由生成改成槽位填充：

• 预先把每个工具的参数 Schema 拆成槽位，日期、枚举、ID、数值各归各；
• LLM 只负责从 query 中抽取关键信息填入槽位，不做字段的自由组合；
• 抽完后再过一道规则校验和归一化，比如把 2024-01-01 转换成 20240101，把已发送映射到枚举 sent。

实测下来，schema_error 比例从 34% 降到了 6%。如果你不想引入额外库，至少要做一道工具被调用前的参数校验，失败时把错误信息连同参数一起返回给上层，而不是直接抛异常。这样上层 LLM 看到错误信息，还有机会重新整理参数。

4.3 坑二：工具返回内容把上下文污染了

第二个坑来自返回结果。我们接了一个文档检索工具，经常返回上千字的原始片段。Agent 拿到这些内容之后，反而开始答非所问，甚至在没有数据支持的情况下编造结论。

原因很简单：上下文窗口是有限的，大量无关信息会稀释真正关键的信息。这时候要做结果治理：

结构化数据，比如订单状态，按照参数 Schema 和用户意图，只保留与问题相关的字段，订单号、状态、更新时间，不要拖出整个订单 JSON。非结构化文本，比如文档片段，用一个摘要 prompt 让 LLM 生成不超过 50 个字的摘要，再返回给上层。原始结果仍然完整存到 Redis，审计的时候可以查。

结果治理还有一个隐藏收益是 token 消耗下降。之前把 2000 字原文塞进上下文，现在只塞 50 字摘要，长期积累下来成本省不少。因为上下文污染导致的错误回答率，从 22% 降到了 5%。

4.4 坑三：并发峰值时第三方限流把任务全憋死

第三个坑跟规模有关。最开始只有十几个 Agent 在跑，后来并发上来，某个指标查询接口在上午 10 点业务高峰期频繁报 429 限流。看日志发现，错误全部集中在同一个时间段，几十个任务同时去请求同一个第三方接口。

这个问题不怪模型，是触达层缺少统一的流量控制。我加了两道措施：

一是令牌桶限流。触达层对每个工具维护一个令牌桶，每秒最多放 N 个请求，超出后排到队列，而不是直接打到下游。排队虽然会增加一点延迟，但总比集中失败好。

二是请求折叠。如果多个任务正在请求同一个工具而且参数相同，比如多个对话都在查同一个订单状态，只发一次真实请求，结果广播给所有任务。这个优化对那种多个 Agent 同时查同一份数据的场景特别有效。

这两道措施上线之后，高峰期第三方限流错误减少了 90%。限流处理是生产系统中非常容易忽略的一环，尤其是在并发快速上升的时候，它往往和模型本身的稳定性没有直接关系，但直接决定了用户能不能拿到结果。

5. 一些可以复用的工程细节与建议

5.1 接入新工具的标准流程

项目跑通后，我把接入新工具做成了一套固定流程：写 adapter，注册 Schema，写路由描述，配超时和降级，跑冒烟测试。每一步都有 checklist。

冒烟测试特别关键。每个工具我会准备五条典型调用和两条异常调用，上线前跑一遍，防止工具端接口悄悄变更导致生产环境翻车。之前有一次外部服务改了返回字段名，从 total 改成了 summary.total，如果不是冒烟测试及时发现，上线后大概率又是一堆线上问题。这项工作看起来不性感，但能省掉大量救火时间。

5.2 观测和审计比功能更重要

Agent-Reach 上线后，我最大的体会是：日志比模型 prompt 值钱。每一笔调用我都要记录 task_id、时间戳、路由候选、选择的工具、参数、错误类型、耗时、重试次数。用同一个 task_id 串联 Agent 层、Reach 层、外部服务层，排障的时候不用猜，直接顺着 task_id 看完整链路就行。

建议给每个工具配错误码字典。第三方服务返回的错误五花八门，在 adapter 里统一映射成几类：timeout、schema_error、service_error、limit_exceeded、policy_error。有了这个字典，重试、降级、告警才有规则可依据。你不能在代码里到处比较具体的错误字符串，那会变成维护噩梦。

降级行为也要有日志。系统什么时候降级、为什么降级、降级后是否成功，这些数据是后续优化工具质量和选择备选方案的重要依据。如果降级路径本身也不稳定，你需要在监控上单独给降级成功率设立一个看板，而不是混在整体成功率里。

5.3 未来可以扩展的方向

Agent-Reach 目前的版本还比较朴素，但核心方向已经验证过了。后面我想做两件事：

一是自适应超时。不再用固定超时，而是根据每个工具近期的 P95 延迟动态调整，避免外部服务整体变慢时还死守 10 秒不放手。超时设短了误杀，设长了用户等不起，动态调整是目前看起来比较靠谱的方向。

二是多模态触达。把语音、邮件、IM 机器人也都纳入触达层，统一管理认证方式和调用策略。现在的触达层主要覆盖 HTTP API 和数据库查询，但实际业务里用户的触达渠道远不止这些。邮件、企业微信、钉钉、电话语音，每一种渠道的可靠性要求都不一样，统一管理会省很多事。

如果要给后来者一个建议，那就是别急着把触达层做成万能中间件，从三五个工具、一个业务场景切入，把成功率做到 95% 以上再考虑抽象。抽象太早，你根本不知道哪些是核心逻辑、哪些是场景特例。

最后说点个人的体会。Agent-Reach 这个名字当时起得比较随意，做完了反而觉得挺贴切：Agent 负责想，Reach 负责够到。模型再聪明，够不到真实世界的工具和数据，一切都是空中楼阁。我在这套系统上花得最多的时间，并不是写那些花哨的路由逻辑，而是处理超时、限流、参数错误、结果污染这些不性感的细节。正是这些细节，决定了用户最终觉得这个 Agent 是可用的还是只是个演示品。项目代码我整理后会放出来，有兴趣的朋友可以关注仓库；如果你也在做多工具智能体，欢迎聊聊你踩过的类似坑。