别让 RAG 只会背书：WebAgent 的企业系统互联设计

从“查资料”走向“带着证据办事”，让知识检索、任务编排、外部能力与权限控制形成一条可解释、可审计的业务链路。

写在前面

很多 RAG 产品的演示都很顺滑：上传文档，输入问题，模型很快给出一段像样的答案。但真实业务通常不会停在“资料里怎么说”。用户更常问的是：“客户已经付款，为什么权益还没开通？”“合同规定可以退款，但这笔订单现在处于什么状态？”“设备告警和手册中的故障条件是否一致？”“这个需求已经审批到哪一步，下一步由谁处理？”

这些问题同时涉及制度和知识、实时数据、外部系统以及受控操作。只会读文档的 RAG 可以解释规则，却无法确认业务此刻发生了什么；只会调用接口的 Agent 又可能缺少依据，在权限和业务边界不清楚时贸然行动。WebAgent 的价值，正是把两者连接起来：先找到可信证据，再在明确权限范围内查询或调用业务能力，最后把事实、执行结果和推断清楚地交给用户。

本文面向开发工程师、研发与架构人员以及产品经理。开发者可以从中看到 API、SSE、MCP、会话和工具调用的协作方式；研发与架构人员可以关注内容治理、模块边界、权限隔离和可观测性；产品经理则可以据此判断哪些能力适合自动执行、哪些步骤必须确认，以及怎样让用户看懂 Agent 正在做什么。

WebAgent 到底解决什么问题

这里的 WebAgent 不是特指浏览器自动化机器人，而是运行在 Web 应用或企业平台中的智能协作层。它通过 HTTP 或流式接口接收请求，结合会话上下文、知识库证据、已注册工具和业务权限，完成查询、解释、排障、生成报告以及受控操作。

它的目标并不是让模型获得无限能力，而是让模型在平台已经注册、身份已经授权、过程可以审计的范围内工作。RAG 提供证据，WebAgent 负责理解问题并编排步骤，MCP 连接外部能力，权限系统限制身份、数据范围和操作副作用，可观测性则留下这次运行为什么成功或失败的现场。

图 1：WebAgent 的整体架构。图像由 Images 模型生成，正文以架构原则和实际实现为准。

从整体上看，这套系统可以分为几个相互协作的平面。接入层负责 HTTP API、SSE 和身份上下文；编排层负责会话、任务规划、工具发现与结果整合；知识层负责多路检索、融合排序和证据组织；能力层通过 MCP 连接订单、客户、设备、运维、报表、办公等服务；数据与文件层负责文档、元数据、索引、缓存和会话；权限与安全贯穿工具发现和实际执行；日志、指标和链路追踪则用于解释一次 Agent Run 的完整过程。

最重要的不是组件数量，而是职责不能混在一起。知识检索不负责修改业务状态，工具返回的数据不能假装成制度依据，模型不能代替权限系统决定自己是谁，产品界面也不应该把工具调用、等待确认和失败恢复全部藏在一个“正在思考”的动画后面。

一次请求如何从问题走到结果

用户发起请求后，WebAgent 首先加载会话、身份、租户和数据范围。随后进行默认知识检索，为问题寻找制度、手册、接口说明或历史经验等证据。与此同时，系统只向模型暴露当前身份可见的精简能力目录，而不是把所有工具的完整 Schema 一次性塞进上下文。

模型根据问题和证据判断下一步是否需要访问外部系统。纯知识问题可以直接生成回答；需要实时状态时，WebAgent 再从已授权目录中发现少量候选工具，补齐参数并在执行前重新校验权限。工具返回结构化结果后，WebAgent 将它与文档证据放在一起，让模型区分“规则怎样规定”“系统现在怎样”“基于两者可以得出什么判断”。

图 2：一次 Agent Run 从身份加载、知识取证到工具执行和流式输出的链路。

工具循环必须有边界。系统应设置最大调用轮数、单次超时、总超时和取消机制，写操作还要具备幂等性和确认步骤。达到上限时应明确失败或请求人工介入，而不是让 Agent 在后台无休止地“再试一次”。

在产品设计上，知识问答和任务执行也值得明确区分。Knowledge Ask 更接近只读问答，风险较低、延迟相对稳定；Agent Run 则是一项有状态的任务，可能读取实时数据、调用多个系统，甚至在用户确认后修改业务状态。即使底层复用同一套服务，接口契约、错误模型和界面反馈也应该让调用方知道自己发起的是哪一种请求。

SSE 在这里不只是逐字输出答案。一次 Agent Run 应当持续发送“正在加载上下文”“正在检索知识”“已发现候选工具”“等待用户确认”“工具执行成功或失败”“正在整合结果”“任务完成或取消”等事件。对用户而言，这能证明系统没有卡死；对开发者而言，它提供了可定位的状态；对产品经理而言，它是进度展示、失败恢复和人工确认流程的基础。

RAG 的核心不是向量，而是内容治理

RAG 的效果很大程度上由进入知识库的内容质量决定。文件不应该在上传后立即成为生产知识，而应先经过读取、格式转换、内容校验、重复检测、审核、切块、索引和版本更新。这样才能确保资料来源可靠、租户归属明确、历史版本可追踪，出现错误时也能回滚。

图 3：文档从上传到进入生产索引的完整生命周期。

PDF、Word、表格和演示文稿可以先转换为统一的标准文本格式，再进入去重与审核。耗时处理应由异步 Worker 完成，并具备任务租约、重试、检查点和失败补偿，避免转换或索引阻塞用户请求。审核通过后才生成检索索引；文档更新时应产生新的索引版本，让缓存失效、回滚和审计都有可靠依据。

检索阶段也不应只依赖单一路径。语义召回擅长理解近义表达和上下文，关键词或稀疏召回更适合订单号、错误码、型号和专业术语，多路结果经过融合排序后，还可以由独立重排服务进行第二阶段精排。当向量服务异常或没有结果时，系统应当允许降级到关键词检索，而不是悄悄生成一个没有根据的答案。

具体使用哪一家 Embedding 或重排模型，不应该成为产品方案的中心。更重要的是团队能否清楚回答：每个检索阶段解决什么问题，服务不可用时怎样降级，平台知识和租户知识如何隔离，缓存键是否包含账户、检索范围和索引版本，以及模型供应商变化时系统能否平滑替换。

RAG 的输出最好始终被称为“证据”，而不是“真相”。证据应带有来源、归属、时间、检索方法和相关性信息，可以为空，也可能相互冲突。最终回答必须说明哪些结论来自文档，哪些来自实时系统，哪些只是模型基于现有信息做出的推断。这个命名会自然推动团队讨论来源、冲突和置信度，而不是把 Top1 检索结果当成圣旨。

知识、工具与权限必须保持边界

WebAgent 同时具备知识和行动能力时，最容易出现的问题不是模型“不够聪明”，而是边界不清楚。知识层负责提供解释和证据，不能直接修改业务状态；工具层负责读取或执行外部能力，但它只能在平台注册和授权范围内运行；WebAgent 负责编排和整合，却不能自行扩大身份或数据范围。

图 4：RAG 提供证据，WebAgent 负责判断与编排，工具负责执行，权限系统贯穿整个过程。

MCP 可以把外部服务抽象为 Tools、Resources 和面向服务的说明内容。Tools 是可以执行的能力，例如查询订单、读取客户资料、查看设备状态、生成报表或触发现有业务流程；Resources 提供接口说明、字段定义、业务规则和运行手册；Service Skills 则帮助模型理解何时使用某个服务、怎样选择工具、参数有哪些限制以及哪些操作必须确认。

Skills 本质上是决策说明，不是动态下发的执行代码。上下文可以扩展，执行能力只能来自平台注册。否则所谓“动态能力”很容易演变成缺少审查的远程代码执行。

权限至少要在两个位置发生。工具发现之前，系统只应返回当前身份能够使用的候选能力；实际调用之前，还要根据租户、角色、Scope、Data Scope 和工具副作用重新校验。账户、操作者和数据范围必须由可信传输上下文注入，模型生成的参数如果与这些信息冲突，调用应立即拒绝。

这条原则可以概括为：模型可以建议调用什么，却不能决定自己是谁、可以查看谁的数据，以及能够把业务状态改到什么程度。

从物联网扩展到互联网和企业应用

这套架构并不依赖某个行业。只要业务同时存在文档规则、实时数据和可调用接口，就可以采用相似模式。

以“付款成功但权益未开通”为例，WebAgent 先检索订单、支付、订阅和权益发放规则，再发现订单查询、支付查询、账号查询和权益查询工具。权限系统确认操作者可以访问对应客户和订单后，工具读取支付结果、回调记录、账号状态和权益发放记录。WebAgent 将规则证据与实时数据对齐，区分“通常原因”和“本次原因”。如果只需要解释，它可以直接给出结论和来源；如果需要补发权益、重放回调或创建工单，则应先展示影响范围并请求用户确认，执行后再记录审计信息。

同样的方法可以用于客户服务，让 Agent 结合产品规则、客户资料、历史工单和订单状态生成处理建议；可以用于 SaaS 平台，查询租户、账号、套餐、账单和资源配额；可以用于研发与运维，把运行手册、告警、日志、发布记录和监控数据放在同一条故障分析链路中；也可以用于内容运营、供应链、内部办公和物联网设备管理。

行业对象可能不同，但核心关系不变：文档告诉系统应该怎样判断，实时系统告诉系统现在发生了什么，WebAgent 负责把两者对齐，并在权限允许时推动下一步。

未来如果需要接入网页搜索、抓取或浏览器自动化，也应将其作为独立、受控的能力服务接入。工具应声明只读或写入属性，限制允许访问的域名、响应大小和执行时间，并对外部内容进行净化和审计。不要把一个无限制浏览器直接放进 Agent 进程，然后期待模型“自觉一点”。

为什么适合从模块化单体开始

WebAgent 的复杂性主要来自能力协作，而不一定来自分布式系统本身。项目早期采用模块化单体通常更务实：Agent、Documents、Retrieval、MCP、Identity、Artifacts 和 Observability 按职责划分模块，却仍由一个主要进程统一装配和管理生命周期。

这样做可以减少跨服务调用带来的延迟和故障点，让文档 Worker、MCP Client、SSE、会话状态和权限校验共享清晰的运行边界。模块之间通过应用服务和端口协作，未来某个模块真的出现独立扩缩容、安全隔离或资源消耗需求时，再拆成独立服务。

更适合优先独立部署的，通常是向量检索、缓存与关系数据库、文档转换、语义向量与重排服务、制品渲染以及远端 MCP 服务。它们要么拥有完全不同的资源特征，要么需要更强的安全隔离。

因此更可靠的演进顺序是：先按职责拆边界，再按压力和风险拆进程。微服务不是模块化的起点，而是某些模块在条件成熟后的部署选择。

从可用走向生产级

生产级 WebAgent 首先需要端到端可观测性。指标可以回答系统整体是否健康，Trace 则解释某一次请求为什么慢、为什么选错工具、为什么在权限阶段失败。一次 Agent Run 可以拆成会话加载、知识检索、工具目录检索、工具调用、模型生成和会话持久化等 Span，但完整 Prompt、敏感业务参数、用户隐私和密钥不应进入 Trace 属性。

工具目录还需要稳定的同步机制。启动时同步并定期轮询是一种简单可靠的基础方案，进一步可以使用变更通知或管理接口主动刷新，同时保留低频轮询兜底。事件机制负责及时性，轮询负责在通知丢失时恢复一致。

工具注册信息应明确副作用。查询类工具可以标记为只读；会修改业务状态的工具需要写入等级；删除、覆盖或不可逆操作应标记为破坏性；需要确认的工具必须在执行前停下来；可重试工具应定义幂等键和超时策略；高风险操作还需要更严格的审计级别。只在工具描述里写一句“请谨慎使用”，不是安全设计。

RAG 结果和工具结果最好统一为 Evidence。一个 Evidence 可以描述类型、来源、归属范围、观测时间、置信度和内容。这样回答层能够清楚区分制度条款、实时观测、执行结果与模型推断，产品界面也能把来源和时间展示给用户。

质量评估同样不能只看答案文采。检索评估要检查正确证据能否进入候选集；工具评估要检查工具选择和参数是否正确；权限评估要覆盖跨租户、越权和身份冲突；端到端任务评估还要覆盖空结果、超时、部分失败、用户拒绝确认和重试等情况。一个回答可能写得很好，但如果调用了错误租户的工具，整个任务仍然是不合格的。

产品界面不能只有聊天框

WebAgent 产品需要把一次任务表现为可理解的过程。用户应当知道当前正在执行哪一步、使用了哪些资料和业务系统、哪些内容是事实、哪些是推断、失败后是否可以重试，以及写操作会影响什么范围。

当任务需要确认时，界面应明确展示即将调用的能力、关键参数、可能产生的副作用和是否可撤销。执行完成后，结果最好可以保存为工单、报告或结构化记录，而不是只留在一段无法复用的聊天记录中。

因此，一个完整的 Agent 产品并不是“聊天框加流式输出”，而是一套任务状态、证据展示、权限确认、失败恢复和结果沉淀机制。

最后需要守住的原则

真正值得长期保留的不是某个模型或向量数据库名称，而是几组稳定边界：知识与行动分开，说明与能力分开，模型判断与系统授权分开，模块边界与部署边界分开，产品展示与底层执行状态保持一致。

文档应经过治理、审核和版本化后再进入生产索引；平台知识和租户知识在存储、检索和缓存中都要隔离；工具必须来自平台注册，先按身份过滤，再在执行前重新校验；读、写和破坏性操作采用不同策略；SSE 传递任务状态而不仅仅是 Token；指标观察系统整体，Trace 解释一次具体运行。

当这些边界站稳后，接入订单系统、CRM、身份认证、工单平台、业务数据库、设备服务、监控平台、报表服务、Web 搜索或制品生成能力，都只是继续往标准接口上连接能力，而不是每次重新装修整栋楼。

WebAgent 真正有用的时刻，不是它看起来像一个无所不能的人，而是它清楚知道什么时候应该查资料，什么时候可以调用工具，什么时候必须停下来问一句：“这一步会修改业务数据，确认要继续吗？”

References

• Model Context Protocol：官方文档 — MCP 的概念、架构、客户端与服务端基础说明。
• Model Context Protocol：当前规范 — 协议版本、能力协商、Tools、Resources 和传输层的规范依据。
• MCP Streamable HTTP Transport — 远端 MCP 服务采用 HTTP 传输时的会话和安全要求。
• Server-Sent Events（MDN） — 浏览器端 SSE、EventSource 和事件流的使用说明。
• HTTP Semantics：RFC 9110 — HTTP 方法、状态码、缓存和请求语义的标准依据。
• OpenAPI Specification — HTTP API 的语言无关接口描述规范，可用于工具接口契约和文档生成。
• OpenTelemetry Documentation — Trace、Metrics、Logs、上下文传播和遥测导出的官方文档。
• Redis Documentation — 会话、缓存、锁和其他运行时状态能力的官方文档。
• MySQL 8.4 Reference Manual — 关系数据、事务、索引和运维管理的官方参考。
• JSON Schema Documentation — 工具参数、结构化结果、事件和制品 Schema 的定义与校验。
• CommonMark Specification — Markdown 标准化内容的语法参考。
• OAuth 2.0：RFC 6749 — 授权框架、访问令牌和客户端授权流程的基础规范。
• JSON Web Token：RFC 7519 — JWT 声明与令牌格式的标准定义。
• OWASP API Security Top 10 — 对象级授权、功能级授权和第三方 API 消费等常见风险参考。