Agent 与 RAG 平台集成

调研日期：2025-06-22

未实测，以源码/docs 为准

一句话定位

Agent 和 RAG 的结合不是简单的”拼在一起”——而是三种截然不同的集成模式（RAG-as-Tool / RAG-in-Loop / RAG-as-Agent），对应不同的工程复杂度和检索质量天花板。选错模式，要么能力受限，要么成本失控。

RAG 管线段标注

本篇关注 Retrieve 段的暴露与集成——RAG 平台如何以 API / MCP / SDK 形式被 Agent 调用，以及 Agent 如何在更高层面编排检索策略。

1. Agent + RAG 为什么要结合

单独 RAG 的局限

日常类比：RAG 系统像一个只听指令的图书管理员——你说”帮我找关于 RRF 的资料”，他就去书架上翻一遍，把找到的书全丢给你。他不会主动思考”你可能还需要看排名融合的论文”或”这个结果看起来不太相关，要不要换个关键词再找一次”。

具体来说，单独的 RAG 管线有三类无法自身解决的问题：

问题一：查询理解不足。用户问”为什么我的检索结果很差”，RAG 系统会直接拿这句话去检索，返回一堆讨论”检索质量”的文档。但用户的真实意图可能是”我的 RAG 系统召回率不够，怎么调参”——查询改写（Query Rewriting）是 RAG 管线自身做不到的，它需要 Agent 在检索前做意图理解和查询分解。

问题二：结果验证缺失。RAG 管线返回 top-K 结果后直接送入 LLM 生成答案，没有”结果够不够好”的判断。如果检索结果完全不相关，LLM 会基于错误上下文生成一个自信但错误的答案——这比”我不知道”更危险。Agent 可以在检索后加一步验证：”这些结果是否与问题相关？不够则重新检索。”

问题三：多步推理能力为零。复杂问题如”RAGFlow 的 DeepDoc 和 WeKnora 的 IMA 在表格解析上的区别”需要先分别检索两个系统的文档，再对比。传统 RAG 管线只能做单轮检索，无法拆解多步问题。这需要 Agent 做查询分解、并行检索、结果合成。

Agent 如何增强检索

Agent 为 RAG 带来的核心价值是决策循环——让检索不再是”一锤子买卖”，而是一个可以根据结果动态调整的迭代过程。

这些能力不是 RAG 管线自身能具备的——它们需要 LLM 在更高层面做推理和决策，而这正是 Agent 的本质。

详细模式分类见 Agentic RAG 模式 中六种 RAG 编排模式

2. 集成模式分类

Agent 和 RAG 的结合不是非此即彼，而是一个从”浅集成”到”深度融合”的光谱。按 Agent 对检索过程的控制权从低到高，可以分为三种模式。

模式一：RAG-as-Tool

定义：RAG 检索被包装成 Agent 的一个工具（Tool），Agent 可以选择调用或不调用，但调用后对检索过程没有控制——不能改写 query、不能指定检索策略、不能做二次检索。

flowchart LR
    U[用户] --> A[Agent]
    A -->|选择调用| RAG[RAG 工具]
    RAG -->|返回 chunks| A
    A -->|可能还调用| T1[Web 搜索]
    A -->|可能还调用| T2[代码执行]
    A --> U

日常类比：你是一个项目经理（Agent），手下的图书管理员（RAG Tool）只会按你说的关键词去书架上翻书。你问他”帮我找 RRF 的资料”，他翻完就回来了。如果你觉得结果不满意，你得重新给他一个不同的关键词再派他去翻一次。

优点：

• 实现最简单——只需把 RAG API 包装成一个 Tool 描述
• Agent 可以在多个工具间选择，灵活性高
• 检索成本可控——Agent 自主决定是否调用

缺点：

• 检索质量完全依赖 RAG 管线本身——如果 RAG 返回垃圾，Agent 也只能拿到垃圾
• 无法做查询改写和二次检索——除非 Agent 自己在 prompt 层面实现
• 对复杂查询能力弱——”对比 A 和 B”需要两次工具调用，Agent 需要自己编排

代表项目：

• AnythingLLM 的 @agent 命令（仅向量检索，无迭代）
• LangChain 的 create_retriever_tool
• Claude Code 通过 MCP 调用 WeKnora

模式二：RAG-in-Loop

定义：Agent 拥有对检索过程的迭代控制权——可以改写 query、指定检索参数、判断结果是否充分、决定是否重新检索。检索不再是”调用-返回”的单步操作，而是一个 Agent 主导的迭代循环。

flowchart TD
    U[用户] --> A[Agent]
    A -->|1. 原始查询| RAG[RAG 检索]
    RAG -->|2. 返回 chunks| A
    A -->|3. 结果不够?| RW[查询改写]
    RW -->|4. 新查询| RAG
    RAG -->|5. 新 chunks| A
    A -->|6. 结果充分| GEN[生成答案]
    GEN --> U

日常类比：你是一个经验丰富的研究员（Agent），不是简单地把关键词丢给图书管理员，而是和他一起工作。第一轮检索后你觉得”这些书太泛了，我需要更具体的”，于是你精化关键词再找一次。或者你发现”这本书提到了另一个相关主题”，于是顺着线索找第二本书。你一直在”检索→评估→调整”的循环中，直到满意为止。

优点：

• 检索质量显著提升——Agent 可以根据第一轮结果调整策略
• 支持复杂查询——查询分解后逐步检索
• 支持自检式 RAG（Self-RAG / Corrective RAG）——结果不相关时自动纠偏

缺点：

• 成本不可预测——迭代次数不确定，每次迭代都消耗 LLM token
• 延迟可能很高——多轮检索 + 多次 LLM 调用
• 实现复杂度高——需要设计迭代终止条件、防止无限循环
• Agent 可能”忘了检索”——注意力被中间步骤分散

代表项目：

• Dify Agent 节点 + 知识检索节点组合
• LangGraph 的 Corrective RAG 模板
• RAGFlow 的 Chat Agent（查询改写 + 重新检索）

关键设计决策——迭代终止条件：

模式三：RAG-as-Agent

定义：RAG 管线本身就是一个 Agent——检索的每一步（查询理解、数据源选择、检索策略、结果验证、答案生成）都由 LLM 自主决策。没有固定的管线结构，只有 LLM 的推理循环。

flowchart TD
    U[用户] --> A[RAG Agent]
    A -->|自主决策| Q1[理解查询意图]
    Q1 -->|自主决策| Q2{需要检索?}
    Q2 -->|否| GEN[直接生成]
    Q2 -->|是| Q3[选择数据源和策略]
    Q3 --> Q4[执行检索]
    Q4 --> Q5{结果评估}
    Q5 -->|不够| Q3
    Q5 -->|够了| Q6[合成答案]
    Q6 --> Q7{答案可信?}
    Q7 -->|否| Q3
    Q7 -->|是| GEN
    GEN --> U

日常类比：你不再有一个图书管理员——你把自己变成了一个全栈研究员。你不仅决定找什么书，还决定先去哪个图书馆找、用什么检索策略、找到后如何交叉验证、最后怎么组织成报告。你不受任何固定流程的约束，完全靠自己的判断力驱动整个过程。

优点：

• 理论上检索质量最高——LLM 在每一步都可以做最优决策
• 极致灵活——能处理任何类型的查询，包括完全未预见的复杂问题
• 自我纠错能力强——可以在任何环节发现问题并重新调整

缺点：

• 成本极高——每一步都是 LLM 调用，一个复杂查询可能消耗数十次 LLM 推理
• 延迟极高——十几次 LLM 调用的累积延迟可能达到分钟级
• 可靠性差——LLM 可能做出错误的中间决策（选择了错误的数据源、错误的检索策略）
• 调试困难——推理链条长，出错时很难定位问题
• 工程复杂度极高——需要设计完整的 Agent 框架、记忆、工具系统

代表项目：

• Dify 的 ReAct Agent + Function Calling 组合
• LangGraph 的多步推理图（Multi-hop Agentic RAG）
• AutoGPT / BabyAGI 的知识库调用模式

三种模式的选择决策树

flowchart TD
    START[选择集成模式] --> Q1{查询复杂度?}
    Q1 -->|简单查询<br>单关键词/单意图| T1[RAG-as-Tool]
    Q1 -->|中等复杂<br>需要改写或对比| Q2{延迟/成本容忍度?}
    Q1 -->|极复杂<br>多步推理/多数据源| Q3{是否需要极致质量?}
    Q2 -->|低| T1
    Q2 -->|中| T2[RAG-in-Loop]
    Q3 -->|否| T2
    Q3 -->|是| T3[RAG-as-Agent]

3. 集成拓扑

flowchart LR
    subgraph agents["Coding Agents"]
        CC[Claude Code]
        CX[Codex]
        LC[LangChain Agent]
    end
    subgraph rag["RAG 平台"]
        WK[WeKnora API]
        DF[Dify API]
        RF[RAGFlow API]
        AG[AnythingLLM]
        FG[FastGPT]
    end
    subgraph bridge["集成桥"]
        MCP[MCP Protocol]
        REST[REST API]
        SDK[Python/Go SDK]
    end
    CC -->|MCP / 手动| MCP
    CX -->|BM25 内建 vs 外接| REST
    LC -->|Retriever 接口| SDK
    MCP --> WK
    REST --> WK
    REST --> DF
    REST --> RF
    SDK --> WK
    SDK --> DF
    SDK --> FG

4. 各 Agent 的 RAG 现状

4.1 Codex（OpenAI）

• 内建能力：仅 BM25 文件级搜索（基于项目文件）[已有]
• 无 embedding RAG：不做向量检索，不做语义分块
• 外接路径：通过 REST API 调用 WeKnora / Dify，将检索结果作为 context 注入 prompt
• 限制：Codex 的沙箱网络受限，外接 RAG 需要在 Agent 外层包装

4.2 Claude Code（Anthropic）

• 内建能力：grep / glob / Read 文件——本质是精确搜索，非语义检索
• 外接路径：MCP 协议天然支持——Claude Code 可通过 MCP Server 连接 RAG
• WeKnora MCP：mcp-server/ 目录已实现 MCP Server，理论上 Claude Code 可直接对接
• 优势：MCP 的 Tool Search 机制（延迟加载）天然适合 RAG 场景——工具描述可以动态加载，不会撑爆 system prompt

MCP 在 Claude Code 中的完整实现见 MCP 集成对比

4.3 LangChain / LangGraph Agent

• 内建能力：Retriever 接口标准化——任何实现了 BaseRetriever 的后端都能即插即用
• 外接路径：写 WeKnoraRetriever 继承 BaseRetriever，实现 _get_relevant_documents
• 最灵活：Agent 工具循环中 retriever 是标准工具，可多个 retriever 并存
• LangGraph 优势：可以用 StateGraph 精确控制 RAG-in-Loop 和 RAG-as-Agent 的迭代逻辑

5. 各项目的 Agent 能力对比

5.1 WeKnora：EventManager + Plugin（尚未 Agentic，但机会明确）

现状：WeKnora 本身是固定管线——EventManager 派发 QueryReceived 事件，BM25 / 向量 / 图谱三路并行检索，RRF 融合 + 复合 Rerank，一次出结果。没有 Agent 编排层，没有迭代检索能力。

类比：WeKnora 像一台自动售货机——你投入硬币（query），机器自动走完所有内部步骤，吐出商品（检索结果）。你无法在过程中干预”这罐可乐换成雪碧”或”再找找有没有更冰的”。

机会区域（为什么说”尚未 Agentic”是一个机会而非缺陷）：

1. WeKnora 的 Plugin 管线天然支持 Agentic 扩展——写一个 AgentPlugin 监听 RerankCompleted 事件，判断结果是否充分，不充分则触发新查询
2. mcp-server/ 目录已经把 WeKnora 暴露为 MCP 工具——任何 Agent 框架（Claude Code / LangChain）都可以把 WeKnora 当作一个 RAG Tool 调用
3. 三路检索 + RRF + 复合 Rerank 的固定管线在 80% 场景下已经足够——只在复杂查询时才需要 Agent 编排

关键洞察：WeKnora 定位是”检索引擎”而非”Agent 平台”。把检索做到极致，然后通过 MCP/API 让 Agent 框架来编排——这是比在 WeKnora 内部重造 Agent 轮子更务实的路径。

WeKnora 架构精读见 精读: WeKnora

5.2 Dify：ReAct + Function Calling + Workflow

现状：Dify 是五项目中 Agent 能力最完整的——同时支持 ReAct 和 Function Calling 两种模式，且可以在 Workflow 的任意节点嵌入 Agent。

ReAct 模式：Agent 在”思考→行动→观察”循环中自主决策调用哪些工具。知识库检索是工具之一。Agent 可以选择不检索（闲聊场景）、检索一次、或多次检索不同知识库。

Function Calling 模式：LLM 通过结构化 JSON 返回 tool_calls，系统自动执行工具。比 ReAct 更可靠（JSON 格式由模型保证），但只支持 Function Calling 兼容的模型。

Workflow + Agent 组合：这是 Dify 最强大的能力——在可视化 Workflow 的某个节点上”放手”让 Agent 自主决策，然后在下一个节点重新”接管”控制。例如：

1. 知识检索节点 → 返回结果
2. 条件判断节点 → “相关度 > 0.7？”
3. 是 → 直接生成答案
4. 否 → Agent 节点（自主决定是否追问 / 改写 / 换知识库再检索）

与 WeKnora 对比：Dify 的 RAG 深度不如 WeKnora（双路混合 vs 三路 + RRF + 复合 Rerank），但 Agent 编排能力远超 WeKnora。两者组合——Dify 做前端 Agent 编排，WeKnora 做底层检索引擎——取两者之长。

Dify 架构精读见 精读: Dify

5.3 RAGFlow：Chat-based Agent with Citation

现状：RAGFlow 的 Agent 能力相对简单——基于 Chat 的对话式 Agent，核心亮点是引用追踪（Citation）。Agent 编排采用 Graph 定义，节点类型较少（检索 / LLM / 条件 / 改写），但与 RAG 的集成最紧密。

引用追踪的价值：答案中每个断言都标注来源 chunk，用户可以点击跳转原文验证。这对企业场景（财务数据、法律条文）特别重要——可验证性比高召回率更有价值。

Agent Graph 编排：RAGFlow 的 Agent Graph 比 Dify 的 Workflow 更轻量，但更适合 RAG 专用的推理流程：

1. 检索节点 → 获取初始结果
2. LLM 节点 → 评估结果质量
3. 条件节点 → 不充分则走改写分支
4. 改写节点 → 重写 query
5. 回到检索节点

与 WeKnora 的互补：RAGFlow 的 DeepDoc 文档解析 + WeKnora 的三路检索是理想组合——前者保证输入质量，后者保证检索质量。参见 精读: RAGFlow 中的组合评估方向。

RAGFlow 架构精读见 精读: RAGFlow

5.4 AnythingLLM：@agent Commands

现状：AnythingLLM 的 Agent 能力是五项目中最简单的——通过 @agent 命令激活 Agent 模式，Agent 可以调用向量检索工具和少数内置工具。没有迭代检索、没有查询改写、没有结果验证。

设计哲学的合理性：AnythingLLM 定位是个人知识库——查询模式以简单语义检索为主，复杂查询的频率很低。在这种场景下，RAG-as-Tool（一次调用拿结果）已经够用，强行做 RAG-in-Loop 只会增加延迟和复杂度。

@agent 的具体行为：当用户在对话中输入 @agent 前缀时，系统切换到 Agent 模式——LLM 可以调用 document-search 工具检索知识库，也可以调用 web-scrape 工具抓取网页。但 Agent 不会做查询改写或二次检索——这是设计取舍，不是缺陷。

适用场景：个人笔记检索、小型团队文档问答、隐私敏感场景的本地部署。不适合需要高召回率的企业知识库。

AnythingLLM 架构精读见 精读: AnythingLLM

5.5 FastGPT：Workflow-based Agent

现状：FastGPT 的 Agent 能力通过可视化 Workflow 实现——工作流中的 datasetNode（知识库检索）可以和其他节点（LLM / 条件分支 / HTTP 请求）自由组合，实现 RAG-in-Loop 的效果。

Workflow 作为 Agent 的优势：可视化编排让 RAG-in-Loop 变得可预测——迭代次数、查询改写策略、结果验证逻辑都由工作流定义，而不是依赖 LLM 的自主决策。这比纯 Agent 编排更可控、成本更可预测。

多查询扩展：FastGPT 的知识库检索节点内置了多查询扩展——LLM 自动将用户查询改写为多个子查询，分别检索后合并。这是 RAG-in-Loop 的简化版本——虽然是自动的，但不支持 Agent 评估结果后自主决定是否需要重新检索。

QA 对拆分 + Agent 的组合：FastGPT 的 QA 对拆分策略让检索粒度更细——Agent 可以在 Q 字段上做精确匹配，在 A 字段上做语义检索。这是 FastGPT 在 Agent-RAG 集成上的独特优势。

FastGPT 架构精读见 精读: FastGPT

五项目 Agent 能力汇总

6. MCP（Model Context Protocol）集成

MCP 是什么

MCP 是 Anthropic 提出的标准化 Agent-工具通信协议。日常类比：MCP 之于 Agent，就像 USB 之于电脑——一个标准化的接口，让任何设备（工具）都能即插即用，不需要为每种设备写专门的驱动程序。

在 RAG 场景下，MCP 的核心价值是让 RAG 平台成为 Agent 的即插即用工具——Agent 不需要知道 RAG 平台的 API 格式、认证方式、参数结构，只需要通过 MCP 协议发现和调用工具。

MCP 协议核心概念

MCP 在 RAG 集成中的三种角色

角色一：RAG 平台暴露为 MCP Server

WeKnora 的 mcp-server/ 目录就是这种模式——WeKnora 把检索、文档管理、对话等能力暴露为 MCP 工具，Claude Code 等支持 MCP 的客户端可以直接发现和调用。

{
  "mcpServers": {
    "weknora": {
      "command": "node",
      "args": ["path/to/weknora-mcp-server/dist/index.js"],
      "env": {
        "WEKNORA_API_URL": "http://localhost:8080",
        "WEKNORA_API_KEY": "your-key"
      }
    }
  }
}

角色二：Agent 作为 MCP Client 调用多个 RAG 平台

一个 Agent 可以同时连接多个 MCP Server——WeKnora 做内部文档检索，Dify 做外部知识检索，RAGFlow 做深度文档解析。Agent 根据查询类型自主选择调用哪个平台。

角色三：RAG 平台通过 MCP 调用外部工具

RAG 平台本身也可以是 MCP Client——在生成阶段调用外部工具（Web 搜索、数据库查询、API 调用）来补充 RAG 检索不足的信息。Dify 的 HTTP Request 节点就是这种模式。

MCP vs REST API：为什么 MCP 更适合 RAG-Agent 集成

MCP 的 Tool Search 机制对 RAG 集成特别有价值：当 RAG 平台暴露大量工具（检索不同知识库、不同检索策略、文档管理等）时，MCP Client 不需要把所有工具描述塞进 system prompt——而是维护工具元数据索引，LLM 按需匹配加载相关工具。这解决了”工具过多撑爆 prompt”的问题。

MCP 在 Claude Code 和 Codex 中的完整对比见 MCP 集成对比

WeKnora MCP 能力（基于源码目录推断，未实测）

• 知识库检索（query -> chunks）
• 文档上传/管理
• Agent 对话（流式）
• 知识库列表查询
• 多知识库并行检索

7. 多 Agent 协作检索

为什么需要多 Agent

日常类比：你问一个全科医生”我肚子疼是怎么回事”，他可能给你一个大概方向。但如果你同时让消化科医生、泌尿科医生、神经科医生一起会诊，每个医生从自己专长出发给出判断，最后汇总——诊断准确率会高得多。

多 Agent 协作检索的思路一样：不同 Agent 专长于不同领域或不同数据源，复杂查询时多个 Agent 并行检索，最后合成结果。

三种协作模式

模式一：路由式（Router）

一个主 Agent（Router）接收用户查询，判断应该分配给哪个专业 Agent，然后汇总结果。

用户: "RAGFlow 和 WeKnora 在表格解析上的区别"
  → Router Agent: 判断需要同时查两个知识库
  → 派发给 Agent A: 查 RAGFlow 知识库（检索 DeepDoc 表格识别）
  → 派发给 Agent B: 查 WeKnora 知识库（检索 IMA 表格解析）
  → 汇总: 合成对比答案

模式二：辩论式（Debate）

多个 Agent 对同一问题独立检索和回答，然后互相”辩论”——A 的答案被 B 质疑，B 的答案被 C 补充，最终收敛到一个更准确的答案。

用户: "RRF 和分数加权哪个融合策略更好？"
  → Agent A: 检索后回答"RRF 更好，因为量纲归一化"
  → Agent B: 检索后回答"分数加权更简单可解释"
  → 辩论: A 质疑 B"简单但不鲁棒"，B 补充"在大多数场景下差异不大"
  → 收敛: "RRF 理论更优，分数加权实践更简单，差距在 5% 以内"

模式三：层级式（Hierarchical）

一个”管理者” Agent 负责查询分解和结果合成，多个”执行者” Agent 负责具体的检索任务。

用户: "帮我做一个 RAG 系统的技术选型报告"
  → Manager Agent: 分解为三个子任务
    → Worker 1: 检索"RAG 检索策略对比"
    → Worker 2: 检索"向量数据库选型"
    → Worker 3: 检索"Rerank 策略对比"
  → Manager Agent: 合成三份报告为最终技术选型文档

多 Agent 的工程挑战

各框架的多 Agent 支持情况

多 Agent 框架对比见 Agent 框架全景

8. Tool 设计模式

好的 RAG Tool 长什么样

Agent 调用 RAG 工具和人类使用工具有相同的逻辑——一把锤子如果手柄太粗、锤头太重、没有磁性，工匠就不会用它。RAG Tool 的设计决定了 Agent 能否有效使用检索能力。

模式一：原子工具

每个工具只做一件事，参数简单，输出明确。

# 原子工具示例
tools = [
    {
        "name": "search_knowledge_base",
        "description": "在指定知识库中检索相关文档片段",
        "parameters": {
            "query": "检索查询文本",
            "kb_id": "知识库 ID",
            "top_k": "返回结果数量（默认 5）"
        },
        "returns": "相关文档片段列表，每个包含文本和元数据"
    }
]

优点：Agent 容易理解工具用途，调用决策简单 缺点：复杂查询需要多次调用

模式二：组合工具

一个工具内部组合多个操作，减少 Agent 的编排负担。

# 组合工具示例
tools = [
    {
        "name": "research_topic",
        "description": "深度研究指定主题：自动分解查询、多知识库检索、结果合成",
        "parameters": {
            "topic": "研究主题",
            "depth": "研究深度（quick/deep/exhaustive）",
            "kb_ids": "知识库 ID 列表"
        },
        "returns": "结构化研究报告，包含来源引用"
    }
]

优点：Agent 一次调用即可完成复杂操作 缺点：工具描述复杂，Agent 可能误用参数

模式三：策略选择工具

工具内部封装多种检索策略，Agent 通过参数选择。

# 策略选择工具示例
tools = [
    {
        "name": "retrieve",
        "description": "从知识库检索相关内容，支持多种检索策略",
        "parameters": {
            "query": "检索查询文本",
            "kb_id": "知识库 ID",
            "strategy": "检索策略：semantic（语义）/ keyword（关键词）/ hybrid（混合）/ graph（图谱推理）",
            "top_k": "返回结果数量"
        },
        "returns": "按策略检索的文档片段列表"
    }
]

优点：Agent 可以根据查询类型选择最优策略 缺点：Agent 需要理解不同策略的适用场景

Tool 描述的最佳实践

Tool 设计的反模式

反模式一：上帝工具（God Tool）

一个工具做所有事——检索、摘要、翻译、生成全塞在一个工具里。Agent 无法细粒度控制，调试困难。

反模式二：参数爆炸

一个工具有 20 个参数，Agent 需要理解每个参数的含义才能正确调用。大部分参数应该有合理默认值，只暴露关键参数。

反模式三：隐式副作用

工具描述说”检索文档”，但实际会修改知识库（如自动添加新文档）。Agent 不期望这种副作用，可能导致数据损坏。

9. 安全与权限

为什么 RAG-Agent 集成需要安全控制

日常类比：你请了一个研究助理（Agent）帮你查资料。如果他可以访问你所有的文件柜——包括薪酬档案、商业机密、客户隐私——风险显而易见。你需要给他一个受限的访问范围：只能看公开资料区，不能看机密区。

在 RAG-Agent 集成中，Agent 代表用户执行检索操作。如果没有权限控制，Agent 可能：

• 检索到用户无权访问的机密文档
• 修改或删除知识库内容
• 通过精心构造的查询做数据泄露（prompt injection）
• 无限制地消耗检索资源（DDoS 风险）

四层安全模型

第 1 层：知识库级访问控制
  └─ Agent 只能访问被授权的知识库
  └─ 不同租户/团队的知识库严格隔离

第 2 层：文档级访问控制
  └─ Agent 只能检索有权限的文档
  └─ 敏感文档（如薪酬数据）对 Agent 不可见

第 3 层：操作级访问控制
  └─ Agent 只能执行被允许的操作
  └─ 检索（读）vs 管理（写）权限分离
  └─ 沙箱内 Agent 不应修改知识库

第 4 层：查询级安全防护
  └─ 检测和防御 prompt injection
  └─ 过滤敏感信息（PII）出现在检索结果中
  └─ 限制单次查询的检索范围和频率

各项目的安全能力

WeKnora MCP 安全考量

WeKnora 的 mcp-server/ 在暴露给 Agent 时，需要考虑：

1. 只读检索模式：默认只暴露 search_knowledge_base 工具，不暴露文档上传/删除/修改工具
2. 知识库白名单：Agent 只能检索配置中指定的知识库 ID
3. 结果过滤：检索结果在返回 Agent 前过滤敏感字段（如文档内部 ID、其他用户信息）
4. 频率限制：单次会话内检索调用次数上限（防止 Agent 陷入无限循环时消耗过多资源）

CubeSandbox 集成安全边界见 Sandbox 研究

10. 实际集成代码示例

10.1 LangChain Retriever 包装 WeKnora

from langchain.schema import BaseRetriever, Document
import requests

class WeKnoraRetriever(BaseRetriever):
    """将 WeKnora 检索 API 包装为 LangChain Retriever"""
    api_url: str
    kb_id: str
    top_k: int = 5

    def _get_relevant_documents(self, query: str):
        resp = requests.post(
            f"{self.api_url}/api/v1/retrieve",
            json={"query": query, "kb_id": self.kb_id, "top_k": self.top_k}
        )
        chunks = resp.json()["chunks"]
        return [Document(page_content=c["text"], metadata=c) for c in chunks]

10.2 RAG-in-Loop 实现（LangGraph）

from langgraph.graph import StateGraph, END
from typing import TypedDict, List

class RAGState(TypedDict):
    query: str
    rewritten_query: str
    documents: List[dict]
    relevance_score: float
    iteration: int
    max_iterations: int

def retrieve(state: RAGState) -> RAGState:
    """调用 WeKnora 检索"""
    query = state.get("rewritten_query", state["query"])
    docs = weknora_retriever.invoke(query)
    state["documents"] = docs
    state["iteration"] = state.get("iteration", 0) + 1
    return state

def evaluate(state: RAGState) -> RAGState:
    """LLM 评估检索结果质量"""
    score = llm.evaluate_relevance(state["query"], state["documents"])
    state["relevance_score"] = score
    return state

def rewrite_query(state: RAGState) -> RAGState:
    """改写查询以提升检索质量"""
    new_query = llm.rewrite_query(state["query"], state["documents"])
    state["rewritten_query"] = new_query
    return state

def should_continue(state: RAGState) -> str:
    """判断是否继续迭代"""
    if state["relevance_score"] > 0.7:
        return "generate"
    if state["iteration"] >= state["max_iterations"]:
        return "generate"
    return "rewrite"

# 构建迭代检索图
graph = StateGraph(RAGState)
graph.add_node("retrieve", retrieve)
graph.add_node("evaluate", evaluate)
graph.add_node("rewrite", rewrite_query)

graph.add_edge("retrieve", "evaluate")
graph.add_conditional_edges("evaluate", should_continue, {
    "rewrite": "rewrite",
    "generate": END
})
graph.add_edge("rewrite", "retrieve")

app = graph.compile()

10.3 MCP 配置（Claude Code / CatDesk）

{
  "mcpServers": {
    "weknora": {
      "command": "node",
      "args": ["path/to/weknora-mcp-server/dist/index.js"],
      "env": {
        "WEKNORA_API_URL": "http://localhost:8080",
        "WEKNORA_API_KEY": "your-key"
      }
    }
  }
}

10.4 Dify Workflow 中嵌入 Agent 的 DSL 片段

{
  "id": "agent_fallback",
  "type": "agent",
  "data": {
    "title": "智能检索补充",
    "model": {"provider": "openai", "name": "gpt-4"},
    "strategy": "react",
    "tools": ["knowledge_search", "web_search"],
    "prompt": "如果知识库检索结果不充分，你可以改写查询重新检索，或搜索互联网补充信息。最多迭代3次。",
    "max_iterations": 3
  }
}

10.5 多 Agent 协作检索伪代码

class MultiAgentRAG:
    """多 Agent 协作检索系统"""

    def __init__(self):
        self.router = Agent(role="router")
        self.specialists = {
            "tech_docs": Agent(role="tech_doc_specialist",
                             retriever=WeKnoraRetriever(kb_id="tech")),
            "product_docs": Agent(role="product_specialist",
                                 retriever=DifyRetriever(kb_id="product")),
            "legal_docs": Agent(role="legal_specialist",
                               retriever=RAGFlowRetriever(kb_id="legal")),
        }
        self.synthesizer = Agent(role="synthesizer")

    def query(self, question: str) -> str:
        # 1. Router 判断需要哪些专业 Agent
        assignments = self.router.decide(question, self.specialists.keys())

        # 2. 并行检索
        results = {}
        for domain in assignments:
            results[domain] = self.specialists[domain].retrieve(question)

        # 3. Synthesizer 合成答案
        answer = self.synthesizer.synthesize(question, results)
        return answer

11. 对犀牛鸟竞赛的启示

高价值贡献方向

1. WeKnora MCP Server 完善 — mcp-server/ 是高价值贡献方向，让更多 Agent 框架能即插即用。当前实现可能只覆盖基础检索，可以扩展为完整的 RAG Tool 集合（多知识库并行检索、检索策略选择、结果格式化等）

2. LangChain / LlamaIndex Retriever 包装 — 写 WeKnoraRetriever 和 WeKnoraVectorStore 适配器，降低集成门槛，增加项目生态。这是”小投入大回报”的贡献方向

3. Agentic RAG 评估基准 — 对比”Agent + WeKnora RAG-as-Tool” vs “Agent + Dify RAG-in-Loop” vs “Agent 无 RAG”的效果差异，用量化数据证明集成模式的价值

4. WeKnora AgentPlugin — 在 EventManager 中引入 AgentPlugin，监听 RerankCompleted 事件，判断结果是否充分，不充分则触发查询改写和重新检索。这是 WeKnora 从”固定管线”向”Agentic 检索”演进的关键一步

5. 安全层实现 — 为 WeKnora MCP Server 实现只读模式、知识库白名单、结果过滤等安全控制，让企业场景可以放心接入

贡献路径详见 竞赛指南: WeKnora 贡献 Agentic RAG 编排模式详见 Agentic RAG 模式

12. 与 Memory 的关系

Agent 同时需要 RAG（查外部文档）和 Memory（记对话历史）。两者在 Agent 架构中的位置：

flowchart LR
    U[用户] --> A[Agent]
    A -->|"这个问题需要查资料"| RAG[RAG 平台<br>WeKnora]
    A -->|"用户之前说过..."| MEM[Memory<br>DB-Agent-Memory]
    A -->|"我记得上次查到..."| BOTH[重叠区:<br>缓存检索结果]
    RAG --> A
    MEM --> A

重叠区的处理原则：

• Agent 从 Memory 中读到”项目 X 用 Redis”（经验），同时从 RAG 中查到”项目 X 迁移到 Memcached”（文档更新）——以 RAG 数据为准（更权威），但 Memory 的时效性好（更及时）
• 最佳实践：两者互补而非替代。Agent 同时具备两种能力时回答质量最高

Memory vs RAG 决策树见 B 线 - Memory 与 RAG 边界

13. 集成模式选择速查表

14. 未来趋势

趋势一：RAG 平台 Agent 原生化

当前大多数 RAG 平台的 Agent 能力是”外挂”的——在固定管线之外加一个 Agent 层。未来趋势是 Agent 原生融入 RAG 管线——每个环节（查询理解、检索、融合、Rerank、生成）都可以由 Agent 自主决策，而不是固定流程。

WeKnora 的 EventManager + Plugin 架构天然支持这种演进——只需将现有 Plugin 从”固定响应”升级为”Agent 决策”，就能实现从固定管线到 Agentic 管线的渐进式迁移。

趋势二：MCP 成为 RAG 暴露的事实标准

MCP 协议正在成为 Agent-工具通信的事实标准。未来 RAG 平台如果不提供 MCP Server，将难以被主流 Agent 框架集成。WeKnora 的 mcp-server/ 已经走在这条路上，完善 MCP 工具集是高价值贡献方向。

趋势三：多模态 RAG-Agent 集成

当前 RAG-Agent 集成主要处理文本检索。随着多模态模型（GPT-4o / Claude 3.5 Sonnet）的普及，Agent 需要检索图片、表格、公式等多模态内容。RAGFlow 的 DeepDoc 已经在文档解析层面支持多模态，但 Agent 层面的多模态检索编排（如何同时检索文本和图片、如何合并结果）仍是开放问题。

趋势四：安全与隐私成为一等公民

随着 RAG-Agent 集成进入企业场景，安全控制从”可选”变成”必须”。未来的 RAG 平台需要内置细粒度的访问控制、prompt injection 防护、PII 过滤、审计日志。WeKnora 目前缺少这些能力，这是竞赛贡献的机会区域。

交叉引用

证据等级