### 1、范式演进：从一次性检索到自主决策

#### 传统 RAG（Passive RAG）：

早期的 RAG 架构通常遵循“检索 -> 增强 -> 生成”的线性流程。系统在提交给大模型（LLM）之前执行一次固定搜索（通常基于向量检索）。在这种模式下，LLM 仅作为最终的文本合成器。如果初次检索结果质量不佳或信息缺失，系统缺乏纠偏机制，只能“将错就错”地输出结果。

#### Agent RAG（Active RAG）：

Agent RAG 将搜索能力抽象为“工具（Tool）”。LLM 不再是被动接收者，而是拥有决策权的调度中心：

* 自主决策： 由模型判断当前问题是否需要搜索。
* 参数优化： 自主生成和调整搜索关键词。
* 迭代校准： 如果检索结果不足以回答问题，Agent 可以发起多次、多维度的搜索，直到获取足够信息。

### 2、核心实现路径


> RepositoryTool 是 v3.10.1 引入的工具，旧版可以直接 copy 代码。


#### 阶段 A：将 Repository 封装为 LLM 可调用的工具

首先，我们可以将静态的知识库（Repository）转化为动态的查询工具，使其能够被 LLM 发现并调用。


```java
public class AgentRagDemo {
    public void case1(Repository repository, String query) throws Exception {
        // 1. 将知识库封装为标准的 RepositoryTool
        RepositoryTool repositoryTool = new RepositoryTool(repository);

        // 2. 配置 ChatModel 并挂载工具
        ChatModel agent = ChatModel.of("...")
                .defaultToolAdd(repositoryTool)
                .build();

        // 3. 执行 prompt，LLM 会根据需要自行决定是否调用工具
        agent.prompt(query).call();
    }
}
```

#### 阶段 B：升级为 ReActAgent 实现多轮推理校准

为了支持更复杂的任务（如需要多次检索或多步思考的场景），我们将基础接口升级为 ReActAgent（in `solon-ai-agent`），它遵循“思考-行动-观察”的循环模式。

```java
public class AgentRagDemo {
    public void case2(Repository repository, String query) throws Throwable {
        RepositoryTool repositoryTool = new RepositoryTool(repository);

        // 使用 ReAct 框架，增强模型的逻辑链条和多轮执行能力
        ReActAgent agent = ReActAgent.of(null)
                .defaultToolAdd(repositoryTool)
                .build();

        agent.prompt(query).call();
    }
}
```

#### 阶段 C：混合工具链扩展

针对特定领域（如代码开发或实时咨询），可以通过集成 `solon-ai-skill-web` 等扩展包，为 Agent 提供跨维度的情报获取能力。

```java
public class AgentRagDemo {
    public void case3(Repository repository, String query) throws Throwable {
        RepositoryTool repositoryTool = new RepositoryTool(repository);

        ReActAgent agent = ReActAgent.of(null)
                .defaultToolAdd(repositoryTool)
                // 引入外部生态工具，丰富 Agent 的“感官”
                .defaultToolAdd(CodeSearchTool.getInstance()) // 垂直领域代码搜索
                .defaultToolAdd(WebsearchTool.getInstance())  // 全网实时信息检索
                .defaultToolAdd(WebfetchTool.getInstance())   // 指定 URL 内容抓取
                .build();

        agent.prompt(query).call();
    }
}
```

### 3、总结

Agent RAG 的核心价值在于将检索行为从“预处理阶段”移入了“模型推理阶段”。通过这种方式，系统具备了更强的鲁棒性和解决复杂、模糊问题的能力。