企业官网建设流程全解析

做AI应用这段时间，我越来越觉得“Agent”这个词有点被高估。市面上大多数号称智能体的产品，本质上只是一个能聊天的对话框。真正让人头疼的问题从来不是“能不能聊”，而是“聊完之后能不能办事”。Agent-Reach这个项目就是冲着这个痛点来的：它解决的是智能体的“触达”问题，也就是让Agent能够够得着内部系统、数据服务和用户渠道，从一个只会说话的助手，变成一个能落地的执行单元。这篇内容，我会以这个项目为主线，把设计思路、架构选型、实操过程和踩坑记录完整复盘一遍，如果你也在做类似的智能体应用，或者正准备给现有AI系统加一层“动手能力”，那这篇应该能省你不少时间。

1. Agent-Reach整体设计与思路拆解

1.1 先想清楚“Reach”到底指什么

项目定名Agent-Reach，核心概念就在“Reach”这个词上。开发初期我花了不少时间跟团队对齐一个关键问题：我们做的不是一个模型，也不是一个对话流，而是一层让智能体“触达”外部世界的中间层。这个“外部世界”不是泛泛而谈的互联网，而是更实在的几类资源：内部API、业务数据库、文档知识库，以及用户实际使用的渠道入口。

从前有一个演示Demo，领导看完说“这不就是个聊天机器人吗”，翻译过来的潜台词就是：它没有触达任何真实业务。所以Agent-Reach从第一天开始就是把“触达”作为头等需求来做。具体拆解下来有三层含义：

• 工具触达：Agent要能调用外部系统接口，比如查库存、提交工单、查物流状态；
• 知识触达：Agent要能检索企业内部文档、产品手册、历史工单等非结构化数据；
• 用户触达：Agent要能出现在用户所在的场景，比如网页、企业微信、客服工作台，而不是孤零零跑在一个后台里。

这三层缺一不可。工具触达解决“能不能办事”，知识触达解决“懂不懂业务”，用户触达解决“有没有人用”。Agent-Reach整个框架的演进路线，都是围绕这三层逐步铺开的。如果你只是给Agent加了一个调用函数的能力，但是没有配套的服务发现、权限控制和渠道接入，那在实际业务里还是跑不起来，因为没人会在一个控制台里跟你的Agent对话。

1.2 为什么选择“中枢+触达层”而不是“全栈Agent”

开发过程中我们反复比较过两种路径：一种是做全栈Agent，即从模型、编排到前端全部自己封装，天然具备触达能力；另一种是做一个独立的中枢，通过标准协议对接各种外部系统，让Agent本身保持轻量。Agent-Reach最终选择了后者，而且事实证明这个选择非常正确。

全栈Agent的一个典型问题是：模型迭代太快，今天用的模型明天可能就换了，全栈绑定意味着每一次模型升级都要重新适配一套东西。而“中枢+触达层”的思路是把对话决策和外部触达解耦，Agent内核只负责理解意图、编排任务，真正去调API、查数据库、推送消息的是触达层。这样做带来的好处相当实际：

• 模型更换成本低，只要Agent内核遵循统一的工具调用协议，换底座模型不影响触达逻辑；
• 触达能力可以被复用到不同的Agent上，不只是客服机器人能用，运营、运维、数据分析场景都共享同一套工具网关；
• 权限控制集中在触达层，安全审计和等级划分不需要在每个Agent里重复做。

当然这也有代价，就是中间多了一层系统，链路变长，排查问题时要多查一个环节。但从长期维护的角度看，这点成本是值得的。后面在架构部分我会细说怎么把这条链路做的足够稳。

2. 核心架构与关键技术选型解析

2.1 模块边界：把触达层拆成四个子服务

Agent-Reach的整体架构如果用一个词概括，就是“内聚内核，松散触达”。整个系统可以拆成四个子模块，每个模块的职责非常单一，相互之间通过消息协议通信，这样任何一个模块都可以单独替换或升级。

第一个是触达内核，也就是Agent的主引擎。它负责理解用户输入、维护对话状态、规划任务步骤，并且决定下一步需要调用哪个工具。内核是唯一允许直接接触大模型的地方，它不关心外部系统长什么样，只关心“我说要查询订单接口，触达层能不能给我找到这个接口”。

第二个是工具网关。它维护一个工具注册表，存放所有可供Agent调用的外部能力，每个工具的描述遵循统一的Schema规范。Agent提出需求后，工具网关做服务发现、参数校验、权限校验和实际调用，然后把返回结果标准化后再交回内核。

第三个是知识网关。它管理向量数据库和文档索引，负责处理知识召回。为什么要单独拆一个知识网关而不是让Agent直接连数据库？因为RAG检索不是“简单查文档”，它涉及向量化、混合检索、重排等多种操作，拆出来做可以方便集中调优。

第四个是渠道适配器。它负责对接各种用户入口，把不同平台的输入统一变成内部消息格式。比如网页端、企业微信、钉钉、甚至邮件，都通过适配器接入，Agent内核这一侧不需要为每个渠道写一套逻辑。

模块边界清晰还有一个好处：不同团队可以各管各的模块。比如我们团队有人专门维护工具网关的权限策略，有人专门优化知识网关的召回精度，互不干扰，出问题也容易定位。

2.2 技术选型的几个关键决定

技术选型这部分我直接说结论和理由，省得大家在创业初期到处踩坑。

**通信协议选择了JSON-RPC 2.0而不是REST或GraphQL。**工具调用本身的语义是“请求—响应”，JSON-RPC 2.0足够简单，而且天然支持请求ID的关联追踪，这对排查Agent调用链特别有用。REST在描述动作时还是要靠HTTP动词来表达，GraphQL虽灵活但复杂度和学习成本偏高。工具描述则统一走OpenAPI规范的子集，因为工程团队对OpenAPI最熟悉，很多现有系统的接口文档已经就是OpenAPI格式，收集起来方便。

**工具注册中心用的etcd而不是直接塞在数据库里。**一开始我们就是把工具注册表存在MySQL里，但发现工具信息是“读多写少”且需要实时感知变化的数据，etcd的watch机制能让工具网关在工具变更时秒级感知，不需要轮询数据库。另外etcd天然带租约机制，工具提供方如果长时间心跳异常会自动下线，这个特性对保证Agent调用不过期接口很有用。

**消息队列选了RabbitMQ，没用Kafka。**说实话对这个场景Kafka有点重，Agent触达的调用量虽然单次可能很频繁，但总体规模还没有到需要分布式日志分区来处理的程度。RabbitMQ的延迟低，路由灵活，而且对“推模式”支持好，适合做触达任务的异步分发。你如果预估自己业务量很大，可以用Kafka，但前期从RabbitMQ起步会更从容一些。

**向量数据库选了Qdrant。**做知识触达的时候比较过Milvus、Weaviate和Qdrant，最终选Qdrant是因为它对过滤条件的支持做得很好，而且部署运维不折腾。我们需要按部门做文档权限过滤，Qdrant的payload索引在这类场景下效率很高，召回速度快且代码复杂度低。

3. 实操过程与核心环节实现

3.1 初始化Agent-Reach运行环境

上手跑Agent-Reach的第一步，是把基础环境搭起来。因为我们选择了docker-compose作为编排工具，整个过程并不复杂，但有几个细节值得注意。

首先是版本选择。我当时用的Docker Engine 24.0+，Docker Compose 2.20+，因为旧版Compose对健康检查的语法支持不完整。Agent-Reach本身的镜像托管在内部镜像仓库，你如果是从源码编译，需要先确认Go版本在1.22以上，项目里用了不少泛型语法，Go太低会直接编译报错。

配置文件按模块拆成了四个文件，分别是kernel.yaml、gateway.yaml、knowledge.yaml、channel.yaml，避免改一个模块的配置就要动整份文件。启动顺序上有讲究：先启动etcd，再启动工具网关和知识网关，最后启动触达内核和渠道适配器。因为Agent内核启动时会向etcd注册自己的身份信息，如果网关没就绪，注册会失败。

启动之后建议先跑一条健康检查命令，通过内核侧暴露的/debug/health接口确认链路是通的。这个接口会返回各模块的连接状态，任何模块异常都会在返回体里体现，相当于一个全局体检入口。

3.2 定义一个“可触达的工具”：从API到Schema

要让Agent能够触达库存系统，第一步是把库存接口“翻译”成工具注册表里的一个工具定义。这一步是整个触达链路的地基，定义不合理后续所有调用都会受影响。

拿一个典型的“查询库存”接口举例。我们的库存系统对外暴露了一个REST接口，大致是GET /v1/inventory/query，传入skuId和warehouseCode，返回可用库存数和锁定库存数。要给Agent用，我需要写一份工具注册文件，核心内容如下：

{ "name": "inventory.query", "description": "查询指定SKU在指定仓库的可用库存与锁定库存", "endpoint": { "protocol": "http", "method": "GET", "url": "http://inventory-svc/v1/inventory/query", "timeout": "3000" }, "requestSchema": { "type": "object", "properties": { "skuId": { "type": "string", "description": "商品SKU编码", "required": true }, "warehouseCode": { "type": "string", "description": "仓库编码，不传时默认查所有仓库", "required": false } } }, "auth": { "type": "internal_token", "tokenSource": "gateway" } }

这份定义里最关键的不是endpoint，而是description和requestSchema。很多做Agent开发的初级同学会忽略工具描述的措辞，觉得“模型大概知道啥意思就行”，实际上大模型判断该不该调用这个工具，靠的主要就是这个description。如果描述写得太笼统，比如“查询库存”，模型在用户说“帮我看看还剩多少”的时候就可能犹豫；如果写成“查询指定SKU在指定仓库的可用库存”，模型就能很明确地把用户意图和工具对应起来。建议在描述里尽量带上参数条件和边界情况，让模型能准确判断适用场景。

注册完工具后，先用测试指令验证一下工具网关的调用链路。我习惯直接构造一个模拟的Agent意图请求，通过调试入口绕过内核，直接让网关调用库存接口。确认返回结果能标准化包装后再放给Agent使用，不然到时候出了问题很难分清是模型理解的问题还是触达层调用的问题。

3.3 打通知识触达：让Agent“读到”内部文档

知识触达这部分，我们的做法是企业级RAG的一种常见形态。基础流程是：文档解析、切片、向量化、入库，然后查询时做混合检索。

以接入一份产品手册为例。先做格式处理，产品手册是PDF格式，直接塞给向量化模型效果很差，因为PDF里有大量页眉页脚和排版噪音。我用了一个带有版面分析能力的解析工具，把文档拆成章、节、段落，去掉页眉页脚之后再做切片。切片长度设置很有讲究，我最终用的是“按段落切 + 当段落超过512个token时再按句切”的策略。切片太小，召回时上下文不完整，模型回答容易断章取义；切片太大，向量检索的精度会下降，而且喂给模型的token成本也上升。

这里我贴一段实际用的切片参数，经过几轮评测跑下来的效果相对稳定：

chunk: strategy: "hybrid" max_tokens: 512 overlap_tokens: 48 separator: ["\n\n", "\n", "。", "；"]

overlap设置成48个token是我调出来的经验值。太小的话前后语义衔接容易断层，太大则切片冗余度高，浪费存储和检索资源。

向量化模型当时选了bge-m3，中文场景的效果比很多通用Embedding模型要好，尤其是对专业术语的语义理解更准确。知识网关这边的检索默认是“向量召回+关键词召回”融合，再用Rerank模型把两路结果融合排序。关键词召回很关键，因为企业文档里经常有型号、编号这类精确词，纯向量召回可能找不到完全匹配的条目。

接入完成后，建议专门做一轮检索质量评测。拿10个典型业务问题去问Agent，看召回文档的相关性。我踩过的坑是，有时候问题本身包含了很明确的型号词，比如“A-300这个型号的参数是多少”，但向量检索因为分词的缘故反而召不准，加了关键词召回之后效果立竿见影。知识触达建好之后，Agent才算真正“读得懂”内部资料，而不是只靠通用知识硬答。

3.4 多渠道接入：一次编排，处处触达

渠道适配器是Agent-Reach最后一块拼图。我们的目标很明确：同样的Agent内核，要能同时服务于网页版客服、企业微信消息、内部系统嵌入的对话插件。

渠道适配器的实现思路是为每个渠道起一个独立的适配进程，内部进程间通信统一走WebSocket，这样不会因为某个渠道协议特殊而影响主链路。比如网页版走的是浏览器WebSocket直连，框架这一侧天然支持；企业微信则要处理消息回调和主动发消息两种模式，适配器做的事情是把微信的事件结构转成内部统一的MessageEnvelope，再交给触达内核处理。

这里给出一个消息统一格式的示例，各渠道适配器都要按这个格式输出：

{ "messageId": "chan_001_1682400001", "channel": "wecom", "userId": "zhangsan", "content": "帮我查一下订单3001现在什么状态", "attrs": { "sessionId": "wx_session_12345" } }

统一消息格式的价值在于，内核侧的Prompt上下文、会话管理、工具调用逻辑完全不需要知道消息来自哪个渠道，新增一个渠道只需要新写一个适配器，不需要改内核。后来我们还接了一个内部工单系统的插件渠道，只花了一个下午就搞定，这就是解耦带来的实际收益。

不过多渠道也会引入一个新的问题：重复消息。比如用户在网页和企业微信各发了一次，按照同一userId会拉起两个会话，可能造成重复处理。解决方案是在内核侧维护一个全局会话映射，以userId+channelId为唯一键，但允许跨渠道合并。这个细节刚开始没做，后来用户反馈“我们在PC上聊了半天的上下文，到手机端接着聊模型就忘了”，才发现必须支持会话的跨渠道延续。

4. 常见问题与排查技巧实录

4.1 触达超时：Agent一动就“已读不回”

上线之后遇到的第一个严重问题是工具触达超时。现象是Agent经常在调用某个老系统接口时卡住，等了十几秒之后才回一句“抱歉，我还在查询”，特别影响体验。

排查时我们先看工具网关的日志，发现timeout设置是3秒，但服务端根本没有在3秒内返回。进一步追踪发现，这个老系统内部有一个同步调用链路，每次处理时间需要4到6秒，一个查询接口就慢成这样。

解决思路很直接：给慢接口加异步化改造，工具网关在超时后先返回“处理中”状态，内核侧挂起当前任务，等触达层通过回调把结果推给内核再恢复回复。这里的核心是把“一次性同步请求”变成“请求-响应双段交互”。如果你不想动老系统的代码，还有一个治标方案：把该接口的timeout放宽到10秒，同时在内核Prompt里加一条指令，遇到慢查询要主动告知用户“正在查询中，请稍候”，避免用户以为系统卡死。两种方案可以结合用，前者彻底解决，后者兜底改善体验。

4.2 上下文被工具返回结果撑爆

Agent触达工具之后，有时候会返回特别大的结果集。比如查询一个订单列表接口，一下子返回几百条记录，这些数据全都会被塞进模型的上下文，直接把上下文窗口打满，后续的回复质量急剧下降，甚至报token超限错误。

这个问题在开发初期很容易被忽略，因为测试时总是拿小数据集验证。等真实业务一跑，各种大返回就来了。我们的处理方式是三层：

• 首先在工具定义里尽量要求按需抓取，比如分页、限定字段、增加筛选条件，从源头减少返回体积；
• 其次在工具网关侧增加结果摘要模块，对于超过5000字符的返回内容，自动提取关键字段生成摘要后再放给模型，原始完整数据存入缓存，模型需要详细数据时再按需索取；
• 最后在内核侧设置上下文管理策略，超出预设阈值时把谈话过程中期的记忆自动压缩成摘要，释放上下文空间。

这个三层方案下来，基本没有再因为工具返回太大导致对话崩溃的情况。特别是“网关侧摘要”这个改动，效果比预期还好。它不仅仅减少了token消耗，还相当于帮模型提前做了一层信息过滤，让模型更容易聚焦到关键信息上。

4.3 工具调用参数“幻觉”严重

大模型在调用工具的时候，偶尔会自己“编造”参数。比如调用库存查询工具时，模型明明不知道仓库编码，却编了一个“WH-001”传进去，结果可想而知。刚开始我们以为是个例，直到统计工具调用失败率才发现，参数幻觉导致的失败占据了相当比例。

这个问题有几个层面的解决思路。最简单的思路是工具网关的参数校验，严格按照注册的JSON Schema校验参数，必填字段缺失直接返回“参数错误，请补充xxx”，并把这个错误信息作为一次工具结果反馈给模型，模型会根据报错信息重新补充追问。这套“校验-反馈-重试”机制非常有用。

更深一层的做法是在工具描述里明确标注每个参数的来源口径。例如warehouseCode的描述写成“仓库编码，用户未提供时不要猜测，主动询问用户”。大模型对描述里明确写出的行为约束，遵循率相当高。我现在的习惯是给每个工具都写清“禁止自行推断未提供的参数”，虽然描述长一点，但有效降低了不少幻觉发生频率。

4.4 一次完整的排查案例：工具调不通到底是哪一层的锅

这种情况下排查链路是最麻烦的。有一次用户反馈说Agent回答“可以查询库存”，但紧接着回复“系统繁忙”。问题很典型：模型正确识别了意图，也调了工具，但工具返回报错。

排查过程我是这样拉通整条链路的。Agent-Reach内置了请求追踪ID，从用户消息进入内核开始，一直到工具返回，都会携带同一个traceId。我先从用户消息日志里捞到traceId，然后顺着去工具网关日志里查，发现工具调用转发给库存系统时返回了HTTP 401。但库存系统那边信誓旦旦说他们接口是正常的，让我们去查网关的鉴权配置。

进到工具网关的配置里一查，果然发现问题：工具的auth字段配的是internal_token，网关侧从配置中心读取token，但配置中心里这个工具的token已经过期了。etcd里有这个entry，但网关没有watch到定时刷新的变化。原因更底层，是网关进程里那个定时刷新逻辑的并发锁写挂了，导致一次刷新失败后永久不重试。修掉这个bug之后，类似问题就再没出现过。

这个案例给我们的启示是：Agent链路的问题排查，最怕的是没有统一的追踪机制。Agent-Reach从一开始就强制所有模块在日志里带上traceId，这个决策在排查时太救命了。各位如果自研触达层，建议第一时间把全链路追踪做进去，哪怕是先用简单的日志id串起来，也要做，不要等出了问题再回头补。

5. 从原型到落地的关键经验

5.1 先选1-2个高频工具跑通，再横向扩展

Agent-Reach这个项目最初踩的一个“广撒网”的坑，是想在初期把能用到的工具全接进来。业务团队列了20多个接口，我们也真的花了两周时间逐个写文档、配权限、做测试。结果上线后真正高频用到的，其实只有库存查询、订单状态查询和物流轨迹三个。剩下的接口吃灰不说，维护注册信息和权限策略还占用了不少精力。

后来我们调整了策略：每次迭代只接1-2个被用户明确催过的工具，确保这几个工具经过线上真实流量的检验，再逐步扩展。这么做的收益非常明显。第一是排障范围小，出问题很快能定位；第二是模型对高频工具的理解会更准确，因为工具描述会随着用户提问改进和迭代；第三是权限安全风险更可控，新工具接入有充分的观察期。

5.2 权限控制和审计日志不能等

Agent触达能力越强，权限风险就越大。一个能查库存的Agent和一个能直接修改订单状态的Agent，安全等级完全不同。Agent-Reach在权限设计上做了一版“三级权限”：只读查询、按条件修改、全量操作。每一级对应不同的工具集合，而且不是按用户类型静态划分，而是按“用户身份+会话场景+工具敏感度”综合判断。

审计日志这块我强烈建议大家别省。每个工具调用都要记录：谁在什么时间用哪个会话触发了哪个工具、传了什么参数、返回结果是什么。这些日志平时没人看，但一旦出现越权或者业务纠纷，它就是唯一的证据。Agent-Reach在工具网关侧会记录完整的调用申请和审批流水，并且日志不可篡改，安全团队对这个设计相当满意。

5.3 模型升级后一定要回归测试工具链路

这算是一个持续保持警惕的注意点。大模型版本升级之后，即使对话能力看起来变强了，工具调用行为也可能发生微妙变化。有一次从较小的模型底座升级到更新的版本，凭空多出来一些之前没有的问题：比如对某个工具的触发条件变得过于积极，用户只是随口说了一句“这个库存数据是不是不准”，模型就去调了一次库存接口。问题不算严重，但类型确实变了。

所以现在我们的习惯是：任何模型升级都必须跑一遍全量工具链路的回归测试，包括意图匹配、参数填充、拒识边界。Agent-Reach的测试集里专门维护了一批“不该调用工具”的用例，比如用户闲聊、问天气、说谢谢，这些用例断言模型不能触发工具。模型升级后如果这类用例失败，就要检查是不是Prompt姿势需要跟着模型调整。

5.4 Agent-Reach后续还可以这样扩展

Agent-Reach目前做到的程度，其实只是把触达能力的基本盘打好了。从我个人的规划看，后续还有几个值得探索的方向。

第一个是多Agent协作的触达。现在的架构是一个Agent打包处理所有任务，但如果一个需求横跨多个领域，比如“查库存同时生成了一个补货申请单”，单个Agent可能会觉得负载过重。用Agent-Reach的触达层做底座，天然支持多Agent实例并行协作，每个Agent负责一个领域，通过共享工具网关协调资源。

第二个是策略引擎的引入。把一些高风险的审批流程前置到触达层，在Agent提出请求时先做一次规则校验，不满足条件的请求直接拒绝，而不必每次都依赖模型的自律。这种“硬编码规则兜底+模型柔性决策”的组合，在金融、医疗等严肃场景里几乎必不可少。

第三个是知识网关的联邦化。现在企业内部往往有多个知识系统，Agent-Reach的知识网关可以扩展成一个联邦检索层，对接多个独立的文档系统，还能统一做权限过滤和结果合并。这个方向我们已经在试点了，后续有成果可以再单独写一遍分享。

做Agent落地的这段经历，我最大的体会是：模型的聪明程度决定了你的Agent能走多高，而触达层的工程化能力决定了它能走多远。Agent-Reach这个名字最终被我们保留下来，也是因为每次看到它，都在提醒自己一个朴素的事实——不能触达业务的智能体，再聪明也只是个玩具。你现在就算只是在内部跑一个简单的客服助手，也建议想清楚它需要“够得着”什么，再动手写第一行代码。把这个想透了，后面基本都是水到渠成的事。