智能体 RAG 集成架构文档

概述

本文档描述了如何将 AgenticRagAgent 作为子智能体集成到 AutoPlanningAgent 中，实现智能的知识检索增强生成功能。

架构设计

分层架构

┌─────────────────────────────────────────────────────────┐
│          AutoPlanningAgent (主智能体)                     │
│  - 意图识别                                              │
│  - 任务规划                                              │
│  - 计划执行                                              │
│  - 执行反思                                              │
└──────────────────┬──────────────────────────────────────┘
                   │ 调用
        ┌──────────┼──────────┐
        │          │          │
    [工具调用] [RAG检索] [子Agent调用]
        │          │          │
        ▼          ▼          ▼
   ┌─────────┐ ┌────────┐ ┌──────────────────┐
   │ToolExec │ │RagExec │ │ AgenticRagAgent  │ ◄── 本次集成重点
   └─────────┘ └────────┘ └────────┬─────────┘
                                   │ 使用
                          ┌────────┴────────┐
                          │                 │
                    ┌─────▼──────┐  ┌──────▼───────┐
                    │AgenticRag  │  │AgenticRag    │
                    │Tool        │  │Executor      │
                    │(function   │  │(直接调用-    │
                    │ calling)   │  │ 降级方案)    │
                    └────────────┘  └──────────────┘
                          │
                          ▼
                    ┌──────────────┐
                    │ LangGraph    │
                    │ 工作流       │
                    │ (查询分析、  │
                    │  策略规划、  │
                    │  自适应检索、 │
                    │  结果评估)   │
                    └──────────────┘

关注点分离

层级	组件	职责	调用方式
编排层	AutoPlanningAgent	整体业务流程编排	LangGraph 状态图
规划层	PlanningNode	任务规划和分解	LLM 规划
执行层	PlanExecutionNode	执行具体任务步骤	条件分发
子Agent层	AgenticRagAgent	知识检索子任务	子Agent调用
工具层	AgenticRagTool	工具调用接口	Function Calling
执行器层	AgenticRagExecutor	实际执行逻辑	直接调用
图构建层	AgenticRagGraphBuilder	构建 RAG 工作流图	LangGraph

核心组件

1. AgenticRagTool

文件: AgenticRagTool.java

功能: 将 AgenticRagExecutor 包装为 LangChain4j Tool，支持 function calling

关键特性:

使用 @Tool 注解标记
通过 ThreadLocal 传递上下文（知识库、LLM配置、RAG配置）
返回 JSON 格式的结构化结果
支持错误处理和降级

使用方式:

java

// 设置上下文
AgenticRagTool.setContext(knowledgeBases, llmConfig, ragConfig);

// 调用工具
String result = agenticRagTool.searchKnowledgeBase("用户查询");

// 清除上下文
AgenticRagTool.clearContext();

2. AgenticRagAgent（优化后）

文件: AgenticRagAgent.java

改进点:

添加 AgenticRagTool 依赖
优先使用 Tool 机制（推荐）
AgenticRagExecutor 作为降级方案
新增 executeWithTool() 方法

执行流程:

java

step() {
    if (agenticRagTool != null) {
        // 优先使用 Tool 机制
        result = executeWithTool(query);
    } else {
        // 降级使用 Executor
        result = agenticRagExecutor.executeWithResult(...);
    }
}

3. PlanExecutionNode（已支持）

文件: PlanExecutionNode.java

关键方法: executeAgenticRag()

工作流程:

从任务参数或意图识别获取查询文本
查找 AgenticRagAgent 的 ID（从子Agent列表）
通过 executeSubAgentCall() 调用 AgenticRagAgent
返回执行结果

调用示例:

java

// 在 PlanningNode 规划的任务中
{
  "name": "知识库检索",
  "actionType": "agentic_rag",
  "parameters": {
    "query": "用户问题"  // 可选，默认使用用户输入
  }
}

4. Planning Prompt（已更新）

文件: prompts/planning-prompt.md

新增动作类型: agentic_rag

RAG 选择指南:

rag_query: 简单检索，只返回原始结果
agentic_rag (推荐): 复杂查询，生成高质量回答，支持迭代优化

工作流程

完整流程图

用户输入
  ↓
AutoPlanningAgent.loadAgentConfig()
  - 加载 Agent 配置
  - 加载知识库列表
  - 加载子 Agent 列表（包含 AgenticRagAgent）
  ↓
IntentRecognitionNode
  - 识别用户意图
  - 判断是否需要 RAG (needRag: true/false)
  - 提取 RAG 关键词
  - 指定目标知识库
  ↓
PlanningNode
  - 基于意图生成任务计划
  - 如果 needRag == true:
    → 规划 agentic_rag 步骤（推荐）
    或 rag_query 步骤（简单场景）
  ↓
PlanExecutionNode
  - 执行任务计划中的每个步骤
  - 遇到 agentic_rag 步骤:
    ↓
    executeAgenticRag()
      1. 获取查询文本（参数 > 关键词 > 用户输入）
      2. 查找 AgenticRagAgent ID
      3. 调用 executeSubAgentCall(agentId, query)
         ↓
         AgenticRagAgent.step()
           1. 检查是否有 AgenticRagTool
           2. 如果有 Tool:
              - 设置上下文 (setContext)
              - 调用 Tool (searchKnowledgeBase)
              - 清除上下文 (clearContext)
           3. 如果没有 Tool:
              - 直接调用 AgenticRagExecutor
           ↓
           AgenticRagTool.searchKnowledgeBase(query)
             ↓
             AgenticRagExecutor.executeWithResult()
               ↓
               LangGraph 工作流执行:
                 - 查询分析 (QueryAnalysisNode)
                 - 检索规划 (RetrievalPlanningNode)
                 - 自适应检索 (AdaptiveRetrievalNode)
                 - 结果评估 (ResultEvaluationNode)
                 - 综合生成 (SynthesisNode)
               ↓
               返回 AgenticRagResult
                 - answer: 生成的回答
                 - confidence: 置信度
                 - citations: 引用列表
                 - 等...
      4. 返回结果给 PlanExecutionNode
  ↓
ReflectionNode
  - 评估执行结果
  - 决定是否需要重新规划
  ↓
生成最终响应
  ↓
返回给用户

使用示例

场景 1: 用户提问（自动触发）

用户输入: "什么是 Agentic RAG？"

执行流程:

IntentRecognitionNode 识别:
- userIntent: "知识查询"
- needRag: true
- ragKeywords: ["Agentic RAG", "定义", "特点"]

PlanningNode 规划:

markdown

## 执行步骤

### 步骤1: 知识库检索并生成回答
- **动作类型**: agentic_rag
- **目标资源**: 无
- **描述**: 从知识库检索 Agentic RAG 相关信息并生成回答
- **参数**: {"query": "什么是 Agentic RAG？"}
- **依赖步骤**: 无
- **可跳过**: 否

PlanExecutionNode 执行:
- 调用 executeAgenticRag()
- 找到 AgenticRagAgent 并调用
- AgenticRagAgent 使用 AgenticRagTool
- AgenticRagTool 调用 AgenticRagExecutor
- 返回高质量回答
结果: 用户收到准确、完整的回答，包含引用

场景 2: 复杂查询（多步骤）

用户输入: "对比 Vanilla RAG 和 Agentic RAG，并给出使用建议"

执行流程:

IntentRecognitionNode:
- userIntent: "对比分析"
- needRag: true

PlanningNode:

markdown

### 步骤1: 检索 Vanilla RAG 信息
- **动作类型**: agentic_rag
- **参数**: {"query": "Vanilla RAG 的特点和工作原理"}

### 步骤2: 检索 Agentic RAG 信息
- **动作类型**: agentic_rag
- **参数**: {"query": "Agentic RAG 的特点和优势"}

### 步骤3: 对比分析和建议生成
- **动作类型**: llm_generate
- **参数**: {"prompt": "基于检索结果进行对比分析..."}
- **依赖步骤**: 1,2

执行: 多次调用 AgenticRagAgent，最后用 LLM 综合

场景 3: 简单检索（不生成回答）

如果只需要检索结果而不需要生成回答，使用 rag_query:

markdown

### 步骤1: 获取相关文档
- **动作类型**: rag_query
- **参数**: {"query": "用户手册第三章"}

配置要求

1. 数据库配置

在 Agent 配置表中添加 AgenticRagAgent 作为子 Agent:

sql

-- 假设 AutoPlanningAgent 的 ID 是 1
-- AgenticRagAgent 的 ID 是 10

INSERT INTO ai_agent_sub_agent (parent_agent_id, sub_agent_id, name, description)
VALUES (1, 10, 'AgenticRagAgent', 'Agentic RAG 智能检索增强生成智能体');

2. 知识库配置

确保 Agent 配置中包含知识库列表:

json

{
  "knowledgeBases": [
    {
      "id": 1,
      "name": "技术文档",
      "retrievalSettings": {
        "maxResults": 5,
        "minScore": 0.7,
        "enableRerank": true
      }
    }
  ]
}

优势与特点

1. 架构优势

关注点分离: Tool、Agent、Executor 各司其职
松耦合: 通过接口和抽象层解耦
可扩展: 易于添加新的 Tool 或 Agent
可测试: 每层可独立测试

2. 功能优势

智能决策: AutoPlanningAgent 自动决定是否调用 RAG
自主规划: AgenticRagAgent 内部智能选择检索策略
迭代优化: 支持多轮检索和查询优化
高质量: 多维度评估确保结果质量

3. 性能优势

按需调用: 只在需要时调用 RAG
并行执行: 支持多知识库并行检索
缓存优化: 可在各层添加缓存
降级保护: Tool 失败时自动降级到 Executor

最佳实践

1. 何时使用 agentic_rag

✅ 推荐使用场景:

需要基于知识库生成回答
复杂的多方面查询
需要高准确性和完整性
需要引用和溯源

❌ 不推荐场景:

只需要原始检索结果（用 rag_query）
简单的事实查询（用 llm_generate）
不涉及知识库的问题

2. 配置建议

java

// AgenticRagAgent 配置
{
  "knowledgeBases": [...],  // 知识库列表
  "llmConfig": {
    "modelName": "gpt-4",    // 使用高质量模型
    "temperature": 0.1       // 低温度确保准确性
  },
  "ragConfig": {
    "maxIterations": 3,      // 最大迭代次数
    "qualityThreshold": 0.7  // 质量阈值
  }
}

3. 错误处理

java

try {
    result = executeAgenticRag(...);
} catch (Exception e) {
    // 1. 记录错误
    log.error("Agentic RAG 执行失败", e);

    // 2. 标记任务状态
    updateTaskStatus(currentIndex, STATUS_FAILED, e.getMessage());

    // 3. 判断是否可跳过
    if (task.isSkippable()) {
        continue; // 跳过当前任务
    } else {
        throw e;  // 中断执行
    }
}

监控与调试

关键日志

[INFO] Agentic RAG Tool 被调用
[INFO] 查询: 什么是...
[INFO] 知识库数量: 3
[DEBUG] 使用 AgenticRagTool (function calling 机制)
[INFO] Agentic RAG 执行开始
[INFO] 查询分析完成 - 意图: information_seeking
[INFO] 检索策略: multi_query
[INFO] 检索完成 - 结果数: 12
[INFO] 相关性评分: 0.85, 覆盖度评分: 0.78
[INFO] Agentic RAG 执行完成 - 置信度: 0.82, 迭代次数: 2
[INFO] Agentic RAG Agent 处理完成

性能指标

监控以下指标:

执行时间: Agentic RAG 完整流程耗时
迭代次数: 平均迭代次数
置信度: 平均置信度分数
缓存命中率: 如果启用缓存
失败率: 执行失败的比例

故障排查

常见问题

Q1: AgenticRagAgent 未找到

错误: 未找到 Agentic RAG Agent，请确保已配置 AgenticRagAgent 作为子Agent

解决方案:

检查数据库中是否配置了子 Agent 关系
确认 AgenticRagAgent 已正确注册（@AgentRegistration）
检查 Agent 名称是否包含 "Agentic" 和 "RAG"

Q2: 知识库未配置

警告: 未配置知识库，无法执行检索

解决方案:

在 Agent 配置中添加 knowledgeBases 列表
确保知识库 ID 有效
检查知识库检索设置

Q3: Tool 初始化失败

警告: AgenticRagTool 初始化失败，将尝试使用 Executor

解决方案:

这是正常的降级行为，系统会自动使用 Executor
如果需要使用 Tool 机制，检查 Spring Bean 配置

未来扩展

1. 支持流式输出

java

@Tool
public Stream<String> searchKnowledgeBaseStream(String query) {
    // 返回流式结果
}

2. 支持批量查询

java

@Tool
public List<String> searchKnowledgeBaseBatch(List<String> queries) {
    // 批量处理多个查询
}

3. 支持自定义策略

java

@Tool
public String searchWithStrategy(
    String query,
    String strategy  // "simple", "multi_query", "step_back"
) {
    // 使用指定策略
}

参考资料

AutoPlanningAgent 文档
Agentic RAG 工作流：后端源码 muotai-ai/muotai-ai-biz/src/main/java/com/pig4cloud/pigx/ai/rag/agentic/AgenticRagGraphBuilder.java
LangChain4j Tool 文档
LangGraph4j 文档

创建日期: 2025-01-23 作者: Xing Fan 版本: 1.0.0

智能体 RAG 集成架构文档 ​

概述 ​

架构设计 ​

分层架构 ​

关注点分离 ​

核心组件 ​

1. AgenticRagTool ​

2. AgenticRagAgent（优化后） ​

3. PlanExecutionNode（已支持） ​

4. Planning Prompt（已更新） ​

工作流程 ​

完整流程图 ​

使用示例 ​

场景 1: 用户提问（自动触发） ​

场景 2: 复杂查询（多步骤） ​

场景 3: 简单检索（不生成回答） ​

配置要求 ​

1. 数据库配置 ​

2. 知识库配置 ​

优势与特点 ​

1. 架构优势 ​

2. 功能优势 ​

3. 性能优势 ​

最佳实践 ​

1. 何时使用 agentic_rag ​

2. 配置建议 ​

3. 错误处理 ​

监控与调试 ​

关键日志 ​

性能指标 ​

故障排查 ​

常见问题 ​

未来扩展 ​

1. 支持流式输出 ​

2. 支持批量查询 ​

3. 支持自定义策略 ​

参考资料 ​

智能体 RAG 集成架构文档

概述

架构设计

分层架构

关注点分离

核心组件

1. AgenticRagTool

2. AgenticRagAgent（优化后）

3. PlanExecutionNode（已支持）

4. Planning Prompt（已更新）

工作流程

完整流程图

使用示例

场景 1: 用户提问（自动触发）

场景 2: 复杂查询（多步骤）

场景 3: 简单检索（不生成回答）

配置要求

1. 数据库配置

2. 知识库配置

优势与特点

1. 架构优势

2. 功能优势

3. 性能优势

最佳实践

1. 何时使用 agentic_rag

2. 配置建议

3. 错误处理

监控与调试

关键日志

性能指标

故障排查

常见问题

未来扩展

1. 支持流式输出

2. 支持批量查询

3. 支持自定义策略

参考资料