# multi-agent-demo

**Repository Path**: yulang_admin_1/multi-agent-demo

## Basic Information

- **Project Name**: multi-agent-demo
- **Description**: Multi-agent 的使用demo案例，提供了相关的场景使用 和 学习案例代码
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-17
- **Last Updated**: 2026-04-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring AI Alibaba 多智能体协作平台

<div align="center">

![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.3.5-brightgreen.svg)
![Spring AI Alibaba](https://img.shields.io/badge/Spring%20AI%20Alibaba-1.1.2.0-orange.svg)
![Java](https://img.shields.io/badge/Java-21-blue.svg)
![License](https://img.shields.io/badge/License-MIT-yellow.svg)

**基于 Spring AI Alibaba 构建的企业级多智能体协作平台，支持 Skills、Routing、Supervisor、Parallel 四种核心模式**

</div>

---

## 📋 目录

- [项目简介](#-项目简介)
- [核心特性](#-核心特性)
- [技术栈](#-技术栈)
- [架构设计](#-架构设计)
- [快速开始](#-快速开始)
- [使用示例](#-使用示例)
- [项目结构](#-项目结构)
- [配置说明](#-配置说明)
- [API 接口](#-api-接口)
- [开发指南](#-开发指南)
- [常见问题](#-常见问题)
- [许可证](#-许可证)

---

## 🎯 项目简介

本项目是一个基于 **Spring AI Alibaba 1.1.2.0** 构建的多智能体协作平台，完整演示了现代 AI Agent 系统的四大核心模式：

1. **Skills + Memory（ReactAgent）**：渐进式技能披露 + 多轮对话记忆
2. **LlmRouting（路由分发）**：LLM 驱动的意图识别与智能路由
3. **Supervisor（主管协调）**：多步骤循环编排复杂任务
4. **Parallel（并行分析）**：多维度同时处理提升效率

通过统一的 REST API 和现代化的 Web 界面，用户可以自然地与 AI 交互，后端自动识别意图并选择最优的智能体模式进行处理。

---

## ✨ 核心特性

### 🔧 四大智能体模式

#### 1️⃣ Skills + Memory 模式（ReactAgent）
- **渐进式技能披露**：通过 `SkillsAgentHook` 实现技能的按需加载，减少 Token 消耗
- **多轮对话记忆**：使用 `MemorySaver` 保存对话历史，支持上下文理解
- **工具调用能力**：集成天气查询、产品 FAQ、订单追踪等实用工具
- **Hooks 生命周期管理**：完整的 Agent 执行生命周期钩子机制

#### 2️⃣ LlmRouting 路由模式
- **语义路由**：LLM 根据用户意图自动选择最合适的专家 Agent
- **动态分发**：支持写作、翻译、摘要等多种内容处理场景
- **单次路由决策**：高效简单的意图分发机制

#### 3️⃣ Supervisor 主管协调模式
- **多步骤编排**：主管 Agent 协调多个子 Agent 按顺序完成任务
- **循环调度**：子 Agent 执行后返回 Supervisor 继续决策
- **状态传递**：通过 `outputKey` 实现子 Agent 间的数据流转
- **复杂任务分解**：适合活动策划、项目管理等多阶段任务

#### 4️⃣ Parallel 并行分析模式
- **并发执行**：多个子 Agent 同时处理相同输入，显著提升效率
- **结果聚合**：自动合并各子 Agent 的输出结果
- **多维分析**：情感分析、关键词提取、摘要总结同步进行
- **独立处理**：各子 Agent 互不依赖，真正并行计算

### 🎨 现代化用户体验
- **暗色主题 UI**：基于 Tailwind CSS 的精美界面设计
- **实时状态反馈**：智能体执行路径可视化展示
- **快捷问题推荐**：内置典型场景示例，一键体验
- **响应式设计**：适配桌面端和移动端设备

### 🏗️ 企业级架构
- **分层设计**：Controller → Service → Agent 清晰职责划分
- **统一响应包装**：标准化 API 返回格式
- **参数校验**：使用 Jakarta Validation 确保数据安全
- **异常处理**：完善的错误捕获与友好提示
- **日志记录**：SLF4J + Logback 结构化日志输出

---

## 🛠️ 技术栈

| 类别 | 技术 | 版本 | 说明 |
|------|------|------|------|
| **核心框架** | Spring Boot | 3.3.5 | 应用基础框架 |
| **AI 框架** | Spring AI Alibaba | 1.1.2.0 | 多智能体框架 |
| **LLM 模型** | DashScope（通义千问） | qwen-plus | 阿里云大语言模型 |
| **开发语言** | Java | 21 | LTS 长期支持版本 |
| **构建工具** | Maven | 3.x | 项目依赖管理 |
| **工具库** | Lombok | - | 简化 Java 代码 |
| **环境变量** | dotenv-java | 3.2.0 | .env 文件加载 |
| **前端框架** | Vue.js | 3.x | 响应式 UI 框架 |
| **样式框架** | Tailwind CSS | - | 原子化 CSS 框架 |
| **图标库** | Lucide Icons | - | 现代化图标集 |

---

## 🚀 效果图
![img.png](img.png)

## 🏗️ 架构设计

### 系统架构图

```
┌─────────────────────────────────────────────────────┐
│                   前端界面 (Vue.js)                   │
│              index.html + Tailwind CSS               │
└──────────────────┬──────────────────────────────────┘
                   │ HTTP POST /api/chat
                   ▼
┌─────────────────────────────────────────────────────┐
│              ChatController (控制层)                  │
│         参数校验 + 统一响应包装 + 异常处理            │
└──────────────────┬──────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────┐
│              ChatService (服务层)                     │
│          意图识别 + 智能路由策略 + 结果封装           │
└──────────────────┬──────────────────────────────────┘
                   │
        ┌──────────┼──────────┬──────────┐
        ▼          ▼          ▼          ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│  Skills  │ │ Routing  │ │Supervisor│ │ Parallel │
│ ReactAgent│ │LlmRouting│ │  Agent   │ │  Agent   │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
     │              │             │           │
     ▼              ▼             ▼           ▼
┌─────────────────────────────────────────────────────┐
│              Spring AI Alibaba Agent Framework       │
│    ReactAgent / LlmRoutingAgent / SupervisorAgent   │
│              / ParallelAgent / SequentialAgent       │
└──────────────────┬──────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────┐
│            DashScope ChatModel (通义千问)             │
│              API Key: AI_DASHSCOPE_API_KEY           │
└─────────────────────────────────────────────────────┘
```

### 智能体路由流程

```
用户输入
   │
   ▼
┌─────────────────────────────────┐
│      关键词匹配路由策略          │
│  （生产环境建议使用 GatewayAgent）│
└────────────┬────────────────────┘
             │
    ┌────────┼────────┬────────┐
    ▼        ▼        ▼        ▼
  天气/    写/      策划/    分析/
  订单/   翻译/    计划/    情感/
  FAQ    摘要     预算     关键词
    │        │        │        │
    ▼        ▼        ▼        ▼
 Skills   Routing  Supervisor Parallel
  Mode     Mode     Mode      Mode
    │        │        │        │
    ▼        ▼        ▼        ▼
 React   LlmRout-  Super-   Parallel
 Agent   ingAgent  visor    Agent
                    Agent
```

---

## 🚀 快速开始

### 前置要求

- **JDK 21+**：[下载 OpenJDK 21](https://adoptium.net/)
- **Maven 3.6+**：[下载 Maven](https://maven.apache.org/download.cgi)
- **DashScope API Key**：[阿里云百炼控制台获取](https://bailian.console.aliyun.com/?apiKey=1&tab=api#/api)

### 安装步骤

#### 1. 克隆项目

```bash
git clone https://gitee.com/yulang_admin_1/multi-agent-demo.git
cd ai-alibab-demo
```

#### 2. 配置 API Key

编辑 `src/main/resources/.env` 文件，填入您的 DashScope API Key：

```env
AI_DASHSCOPE_API_KEY=sk-your-api-key-here
```

> ⚠️ **重要提示**：请勿将 `.env` 文件提交到版本控制系统，已添加到 `.gitignore`。

#### 3. 编译项目

```bash
mvn clean package -DskipTests
```

#### 4. 启动应用

```bash
mvn spring-boot:run
```

或者运行打包后的 JAR 文件：

```bash
java -jar target/ai-multi-agent.jar
```

#### 5. 访问应用

打开浏览器访问：**http://localhost:8080**

---

## 💡 使用示例

### 示例 1：Skills + Memory 模式

**用户提问**：
```
杭州今天天气怎么样？
```

**系统响应**：
```
执行路径：Skills + Memory (ReactAgent)
智能体：customer-service-agent

杭州今天天气晴朗，温度 25°C，湿度 60%，东南风 3 级。
建议穿着轻薄透气的衣物，适合户外活动。
```

**触发关键词**：天气、订单、物流、产品、FAQ

---

### 示例 2：LlmRouting 路由模式

**用户提问**：
```
写一篇关于春天的散文
```

**系统响应**：
```
执行路径：LlmRouting → 写作专家
智能体：content-routing-agent

《春之絮语》

春风轻拂，万物复苏。嫩绿的芽儿从枝头探出头来，
仿佛在向世界宣告生命的到来...
```

**触发关键词**：写、翻译、摘要、总结、文章、散文、诗

---

### 示例 3：Supervisor 主管协调模式

**用户提问**：
```
帮我策划一个电商促销活动，包括方案、预算和风险
```

**系统响应**：
```
执行路径：Supervisor → 活动策划 → 预算规划 → 风险评估
智能体：project-plan-agent

【第一步：活动策划】
活动主题：618年中大促
目标：提升GMV 50%，拉新用户10万+
形式：满减+秒杀+直播

【第二步：预算规划】
总预算：50万元
├ 直播推广：20万
├ 广告投放：15万
├ 优惠券补贴：10万
└ 预留应急：5万
预期ROI：1:3.5

【第三步：风险评估】
🔴 高风险：供应链压力（618期间库存可能不足）
🟡 中风险：竞争对手同步促销
🟢 低风险：技术系统稳定性
```

**触发关键词**：策划、计划、预算、风险、活动、促销、营销

---

### 示例 4：Parallel 并行分析模式

**用户提问**：
```
从情感、关键词、摘要三个维度分析这段评价：这个产品质量很好，推荐购买，物流也很快，但是客服态度一般般
```

**系统响应**：
```
执行路径：Parallel(情感分析 + 关键词提取 + 摘要总结)
智能体：multi-analysis-agent

=== 📊 情感分析结果 ===
情感倾向：正面（置信度：0.85）
分析说明：文本中包含积极评价词汇，整体表达满意态度。

=== 🔑 关键词提取 ===
1. 产品质量（权重：0.35）
2. 物流速度（权重：0.28）
3. 客服体验（权重：0.22）
4. 价格合理（权重：0.15）

=== 📝 摘要总结 ===
用户对产品整体体验满意，特别认可产品质量和物流速度，
但客服服务有改进空间。综合推荐指数较高。
```

**触发关键词**：分析、情感、关键词、维度、多角度

---

## 📁 项目结构

```
ai-alibab-demo/
├── src/main/
│   ├── java/com/example/aiagent/
│   │   ├── agent/                          # 智能体配置层
│   │   │   ├── CustomerServiceAgentConfig.java    # 模式一：Skills + Memory
│   │   │   ├── ContentRoutingAgentConfig.java     # 模式二：LlmRouting
│   │   │   ├── ProjectPlanAgentConfig.java        # 模式三：Supervisor
│   │   │   ├── MultiAnalysisAgentConfig.java      # 模式四：Parallel
│   │   │   └── GatewayRoutingConfig.java          # 网关路由配置
│   │   ├── common/                         # 通用组件
│   │   │   └── Result.java                 # 统一响应包装
│   │   ├── config/                         # 配置类
│   │   │   ├── ToolConfig.java             # 工具 Bean 配置
│   │   │   └── WebConfig.java              # Web 配置
│   │   ├── controller/                     # 控制器层
│   │   │   └── ChatController.java         # 聊天接口
│   │   ├── dto/                            # 数据传输对象
│   │   │   ├── ChatRequest.java            # 请求 DTO
│   │   │   └── ChatResponse.java           # 响应 DTO
│   │   ├── service/                        # 服务层
│   │   │   └── ChatService.java            # 聊天业务逻辑
│   │   ├── tools/                          # 工具类
│   │   │   ├── OrderQueryTool.java         # 订单查询工具
│   │   │   ├── ProductFaqTool.java         # 产品 FAQ 工具
│   │   │   ├── SentimentTool.java          # 情感分析工具
│   │   │   └── WeatherTool.java            # 天气查询工具
│   │   └── AiAgentApplication.java         # 启动类
│   └── resources/
│       ├── skills/                         # 技能定义目录
│       │   ├── order-tracking/SKILL.md     # 订单追踪技能
│       │   ├── product-faq/SKILL.md        # 产品 FAQ 技能
│       │   └── weather-query/SKILL.md      # 天气查询技能
│       ├── static/
│       │   └── index.html                  # 前端页面
│       ├── .env                            # 环境变量（需配置 API Key）
│       └── application.yml                 # 应用配置文件
├── target/                                 # 编译输出目录
├── pom.xml                                 # Maven 配置文件
├── .gitignore                              # Git 忽略配置
└── README.md                               # 项目文档
```

---

## ⚙️ 配置说明

### application.yml 核心配置

```yaml
server:
  port: 8080  # 服务端口

spring:
  ai:
    dashscope:
      api-key: ${AI_DASHSCOPE_API_KEY}  # 从环境变量读取
      chat:
        options:
          model: qwen-plus  # 使用的模型

app:
  gateway:
    system-prompt: |  # Gateway Agent 系统提示词
      你是一个智能路由网关...
```

### 环境变量配置

| 变量名 | 说明 | 示例值 | 必填 |
|--------|------|--------|------|
| `AI_DASHSCOPE_API_KEY` | 阿里云 DashScope API Key | `sk-xxxxx` | ✅ |

### 技能文件配置（SKILL.md）

每个技能包含元数据和详细说明：

```markdown
---
name: weather-query
description: 当用户询问天气情况时使用此技能
---

# 天气查询技能

## 功能说明
你可以查询任意城市的实时天气信息...

## 使用方式
调用 get_weather 工具，传入城市名称...
```

---

## 🔌 API 接口

### 统一聊天接口

**请求**：
```http
POST /api/chat
Content-Type: application/json

{
  "message": "杭州今天天气怎么样",
  "sessionId": "user-123-session-456"
}
```

**响应**：
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "mode": "skills",
    "agent": "customer-service-agent",
    "content": "杭州今天天气晴朗，温度25°C...",
    "executionPath": "Skills + Memory (ReactAgent)"
  }
}
```

**响应字段说明**：

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | Integer | 响应码（200=成功） |
| `message` | String | 响应消息 |
| `data.mode` | String | 智能体模式（skills/routing/supervisor/parallel） |
| `data.agent` | String | 处理的智能体名称 |
| `data.content` | String | AI 回复内容 |
| `data.executionPath` | String | 执行路径描述 |

---

## 📖 开发指南

### 添加新技能

1. 在 `src/main/resources/skills/` 下创建技能目录
2. 编写 `SKILL.md` 文件，定义技能元数据和使用说明
3. 如需配套工具，在 `tools/` 包下创建对应的 Tool 类
4. 在 `CustomerServiceAgentConfig` 中注册工具

**示例**：
```java
@Bean
public ToolCallback[] customerServiceToolCallbacks(
        WeatherTool weatherTool,
        ProductFaqTool productFaqTool,
        OrderQueryTool orderQueryTool) {
    return new ToolCallback[] {
        ToolCallbacks.from(weatherTool),
        ToolCallbacks.from(productFaqTool),
        ToolCallbacks.from(orderQueryTool)
    };
}
```

### 添加新的智能体模式

1. 在 `agent/` 包下创建配置类
2. 定义子 Agent Bean
3. 创建主 Agent（LlmRoutingAgent/SupervisorAgent/ParallelAgent）
4. 在 `ChatService` 中添加路由逻辑

**示例 - 创建新的 ParallelAgent**：
```java
@Configuration
public class CustomAnalysisAgentConfig {
    
    @Bean
    public ParallelAgent customAnalysisAgent(ChatModel chatModel) {
        return ParallelAgent.builder()
                .name("custom-analysis-agent")
                .description("自定义分析专家")
                .subAgents(List.of(
                    agent1(chatModel),
                    agent2(chatModel)
                ))
                .mergeOutputKey("merged_results")
                .build();
    }
}
```

### 自定义路由策略

修改 `ChatService.chat()` 方法中的路由逻辑：

```java
// 当前使用关键词匹配（演示用途）
if (containsAny(lowerMessage, "天气", "订单")) {
    mode = "skills";
    // ...
}

// 生产环境建议使用 GatewayAgent 进行语义路由
// GatewayAgent gatewayAgent = ...;
// String targetAgent = gatewayAgent.call(message);
```

---

## ❓ 常见问题

### Q1: 启动时提示 "AI_DASHSCOPE_API_KEY not found"

**解决方案**：
1. 确保 `src/main/resources/.env` 文件存在
2. 填写有效的 DashScope API Key
3. 重启应用

获取 API Key：[阿里云百炼控制台](https://bailian.console.aliyun.com/?apiKey=1&tab=api#/api)

---

### Q2: 调用接口返回 "网络连接异常"

**排查步骤**：
1. 确认 Spring Boot 应用已启动（检查控制台日志）
2. 确认服务运行在 8080 端口
3. 检查防火墙设置
4. 查看浏览器控制台的网络请求详情

---

### Q3: 如何切换其他通义千问模型？

修改 `application.yml`：
```yaml
spring:
  ai:
    dashscope:
      chat:
        options:
          model: qwen-max  # 或 qwen-turbo、qwen-plus
```

可用模型：`qwen-turbo`、`qwen-plus`、`qwen-max`

---

### Q4: MemorySaver 的记忆会持久化吗？

**不会**。`MemorySaver` 是内存级存储，应用重启后记忆丢失。

**生产环境建议**：
- 使用 Redis 实现分布式 CheckpointSaver
- 使用数据库（MySQL/PostgreSQL）持久化对话历史
- 参考 Spring AI Alibaba 官方文档实现自定义 Saver

---

### Q5: 如何调试智能体的执行过程？

1. 查看控制台日志，所有 Agent 执行都有详细日志输出
2. 前端界面会显示 `executionPath`，展示执行路径
3. 在 `ChatService` 中添加断点调试路由逻辑
4. 启用 DEBUG 级别日志：
   ```yaml
   logging:
     level:
       com.example.aiagent: DEBUG
   ```

---

### Q6: 支持流式输出吗？

当前版本使用同步调用（`chatModel.call()`），暂不支持流式输出。

**如需流式输出**：
```java
// 使用 stream() 方法
Flux<ChatResponse> response = chatModel.stream(prompt);
```

需要修改 `ChatController` 返回 `StreamingResponseBody` 或使用 WebSocket。

---

## 📊 性能优化建议

1. **技能缓存**：已加载的 SKILL.md 可缓存在内存中，避免重复读取
2. **连接池配置**：调整 DashScope HTTP 客户端连接池大小
3. **异步处理**：对于耗时操作，使用 `@Async` 异步执行
4. **限流保护**：添加 RateLimiter 防止 API 调用超限
5. **监控告警**：集成 Micrometer + Prometheus 监控 Agent 执行指标

---

## 🔐 安全建议

1. **API Key 管理**：
   - ✅ 使用环境变量或密钥管理服务（如阿里云 KMS）
   - ❌ 不要硬编码在代码中
   - ❌ 不要提交到版本控制系统

2. **输入校验**：
   - 对所有用户输入进行长度限制
   - 使用正则表达式过滤特殊字符
   - 防止 Prompt Injection 攻击

3. **访问控制**：
   - 生产环境添加身份认证（JWT/OAuth2）
   - 实施 API 速率限制
   - 记录审计日志

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支（`git checkout -b feature/AmazingFeature`）
3. 提交更改（`git commit -m 'Add some AmazingFeature'`）
4. 推送到分支（`git push origin feature/AmazingFeature`）
5. 开启 Pull Request
---

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

> ⚠️ **重要声明**：本项目代码仅供学习和参考使用。如需应用于生产环境，请根据实际业务需求进行充分的测试、优化和安全加固，包括但不限于：性能调优、安全审计、错误处理、监控告警、数据持久化等。作者不对因直接使用本代码到生产环境而产生的任何问题承担责任。

---

## 🙏 致谢

- [Spring AI Alibaba](https://github.com/alibaba/spring-ai-alibaba) - 强大的多智能体框架
- [阿里云 DashScope](https://dashscope.aliyun.com/) - 通义千问大语言模型
- [Spring Boot](https://spring.io/projects/spring-boot) - 应用基础框架
- [Vue.js](https://vuejs.org/) - 前端响应式框架
- [Tailwind CSS](https://tailwindcss.com/) - 原子化 CSS 框架

---

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- 📧 Email: 791076963@qq.com
- 📖 文档: [Spring AI Alibaba 官方文档](https://spring-ai-alibaba.io/)

---

<div align="center">

**⭐ 如果这个项目对您有帮助，请给个 Star！**

Made with ❤️ by AI Agent Demo Team

</div>