Super Agent

基于 Spring AI 构建的智能体（Agent）项目，集成 RAG 知识库检索、MCP 工具调用、ReAct 推理模式，实现自主规划与执行复杂任务。

技术栈

技术	说明
Java 21	运行环境
Spring Boot 3.5.14	应用框架
Spring AI 1.0.0	AI 能力集成
Spring AI Alibaba 1.0.0.4	阿里云通义千问大模型
DashScope (qwen-plus)	大语言模型
MCP (Model Context Protocol)	工具调用协议
SimpleVectorStore	内存向量数据库
Knife4j	API 接口文档

项目架构

src/main/java/tech/xinxinnote/superagent/
├── agent/                          # Agent 核心框架
│   ├── BaseAgent.java              # 基础代理：执行循环、状态管理
│   ├── ReActAgent.java             # ReAct 模式抽象：think → act
│   ├── ToolCallAgent.java          # 工具调用代理：工具选择与执行
│   ├── SuperAgent.java             # 超级智能体：面向咖啡店场景
│   └── enums/AgentState.java       # Agent 状态枚举
├── app/                            # 应用层
│   ├── CoffeeApp.java              # 咖啡店智能客服（RAG + MCP）
│   └── LoveApp.java                # 情感分析应用
├── rag/                            # RAG 检索增强
│   ├── CoffeeDocumentLoader.java   # Markdown 文档加载器
│   ├── CoffeeVectorStoreConfig.java# 向量数据库配置
│   ├── CustomRAGAdvisorFactory.java # 自定义 RAG Advisor 工厂
│   ├── MyKeywordEnricher.java      # 大模型关键词提取
│   └── QueryRewriter.java          # 查询重写器
├── tools/                          # 工具集
│   ├── FileOperationTool.java      # 文件读写
│   ├── PDFGenerationTool.java      # PDF 生成
│   ├── ResourceDownloadTool.java   # 资源下载
│   ├── TerminalOperationTool.java  # 终端命令执行
│   ├── TerminateTool.java          # 终止交互
│   ├── WebSearchTool.java          # Web 搜索
│   ├── WebScrapingTool.java        # 网页抓取
│   └── ToolRegistration.java       # 工具注册配置
├── advisor/                        # Advisor 拦截器
│   ├── MyLoggerAdvisor.java        # 请求/响应日志
│   ├── ReReadingAdvisor.java       # Re2 推理增强
│   └── MySQLMessageChatMemoryAdvisor.java # MySQL 会话记忆
├── controller/                     # API 控制器
│   └── AgentController.java        # Agent 对话接口
├── service/                        # 业务服务
│   └── AgentService.java           # Agent 流式对话服务
├── chatmemory/                     # 会话记忆
│   └── FileBasedChatMemory.java    # 基于文件的会话持久化
└── SuperAgentApplication.java      # 启动类

核心特性

1. ReAct Agent 框架

采用 ReAct（Reasoning + Acting） 模式，Agent 在每一步中先思考（think）再行动（act）：

• think()：调用大模型分析当前上下文，决定是否需要调用工具
• act()：执行选定的工具，将结果反馈到上下文中
• 循环执行直到任务完成（调用 terminate 工具）或达到最大步数

2. RAG 知识库检索

集成 Spring AI 的 RetrievalAugmentationAdvisor，实现知识库增强对话：

• 文档加载：从 resources/document/ 目录加载 Markdown 文档
• 关键词提取：使用大模型为文档片段提取关键词元数据
• 向量存储：基于 SimpleVectorStore 的内存向量数据库
• 查询重写：使用 RewriteQueryTransformer 优化用户查询
• 自定义检索：支持按关键词过滤、相似度阈值、TopK 等参数

3. MCP 工具调用

通过 MCP 协议集成外部工具，当前已接入：

• 高德地图 MCP Server：路线规划、地理编码、POI 搜索

4. 本地工具集

工具	功能
FileOperationTool	文件读写操作
PDFGenerationTool	PDF 文档生成（支持中文字体）
ResourceDownloadTool	网络资源下载
TerminalOperationTool	终端命令执行
WebSearchTool	Web 搜索（SearchAPI）
WebScrapingTool	网页内容抓取（Jsoup）
TerminateTool	终止 Agent 交互

5. 流式对话

支持 SSE（Server-Sent Events）流式输出，实时返回 Agent 的思考与执行过程。

快速开始

环境要求

• JDK 21+
• Maven 3.8+
• Node.js 18+（MCP Server 运行需要）

配置

1. 修改 src/main/resources/application.yml 中的 API Key：

spring:
  ai:
    dashscope:
      api-key: your-dashscope-api-key
search-api:
  api-key: your-search-api-key

2. 修改 src/main/resources/mcp-servers.json 中的高德地图 API Key（如需使用地图工具）：

{
  "mcpServers": {
    "amap-maps": {
      "env": {
        "AMAP_MAPS_API_KEY": your-amap-api-key
      }
    }
  }
}

运行

mvn spring-boot:run

启动后访问：

• 应用地址：http://localhost:8081
• 接口文档：http://localhost:8081/swagger-ui.html

API 接口

接口	方法	说明
/ai/coffee?message=xxx&chatId=xxx	GET	CoffeeApp 同步对话（RAG + MCP）
/ai/agent/chat?message=xxx	GET	SuperAgent 流式对话（SSE）

示例

SuperAgent 自主任务执行

用户：你们店在上海哪个位置？我在虹桥火车站，请帮我规划到你们店的路线图以及大概时间并将结果以 PDF 格式输出

Agent 执行步骤：
Step 1: think → 决定使用 RAG 检索门店信息
Step 2: act  → 调用高德地图 MCP 规划路线
Step 3: act  → 调用 PDFGenerationTool 生成路线指南 PDF
Step 4: act  → 调用 terminate 结束任务

CoffeeApp RAG 对话

用户：你们都有哪些品类的饮品？
Agent：（基于知识库检索）醒石咖啡提供以下品类饮品：意式咖啡、手冲咖啡、特调饮品...

License

MIT