# demo-alibaba-agent

**Repository Path**: devxz/demo-alibaba-agent

## Basic Information

- **Project Name**: demo-alibaba-agent
- **Description**: 这是一个基于 Spring AI Alibaba 框架构建的多功能天气查询 Agent 示例项目。
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-03-03
- **Last Updated**: 2026-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring AI Alibaba 天气智能助手

这是一个基于 Spring AI Alibaba 框架构建的多功能天气查询 Agent 示例项目。

## 项目概述

本项目演示了如何使用 Spring AI Alibaba Agent Framework 构建一个智能代理，具有以下特性：

- 🤖 **智能对话**: 基于通义千问大模型的自然语言处理
- 🔧 **工具调用**: 支持自定义工具函数调用
- 💬 **对话记忆**: 支持多轮对话和上下文保持
- 🌤️ **天气查询**: 集成天气查询功能，支持幽默双关语回复
- 📊 **结构化输出**: 规范化的响应格式
- 🎨 **现代化界面**: 响应式 Web 界面，支持实时对话

## 技术栈

- **Java 17**: 项目基础运行环境
- **Spring Boot 3.5.0**: 应用框架
- **Spring AI Alibaba 1.1.2.0**: Agent 框架核心
- **DashScope**: 阿里云百炼大模型 API
- **WebFlux**: 响应式 Web 框架
- **Lombok**: 简化 Java 代码
- **Gradle**: 项目构建工具

## 项目结构

```
src/main/java/com/devxz/
├── Application.java                          # 应用启动类
└── agent/
    ├── controller/
    │   └── AgentController.java              # REST API 控制器
    ├── service/
    │   └── WeatherAgentService.java          # Agent服务层
    ├── tools/
    │   ├── WeatherForLocationTool.java       # 天气查询工具
    │   └── UserLocationTool.java             # 用户位置工具
    └── model/
        ├── QueryRequest.java                 # 查询请求模型
        └── ResponseFormat.java               # 响应格式模型

src/main/resources/static/
├── index.html                                # 前端主页
├── styles.css                                # 样式文件
└── app.js                                    # 前端逻辑
```

## 快速开始

### 1. 环境准备

确保安装以下环境：
- JDK 17+
- Gradle 7.0+

### 2. 获取 API密钥

访问 [阿里云百炼控制台](https://bailian.console.aliyun.com/?apiKey=1&tab=api#/api) 获取 DashScope API密钥。

### 3. 配置环境变量

**Windows PowerShell:**
```powershell
$env:ALIBABA_API_KEY="your-dashscope-api-key"
```

**Linux/Mac:**
```bash
export ALIBABA_API_KEY=your-dashscope-api-key
```

或者在 `application.yml` 中直接配置：
```yaml
spring:
  ai:
    dashscope:
      api-key: your-dashscope-api-key
```

### 4. 构建和运行

```bash
# 构建项目
./gradlew build

# 运行应用
./gradlew bootRun
```

或者直接运行：
```bash
java -jar build/libs/demo-alibaba-agent-0.0.1-SNAPSHOT.jar
```

应用将在 `http://localhost:8080` 启动。

## 前端界面

启动后直接访问 **http://localhost:8080** 即可使用图形化界面。

### 界面特色
- **现代化设计**: 响应式布局，支持 PC 和移动设备
- **实时对话**: 流畅的聊天体验，支持多轮对话
- **状态监控**: 实时显示系统状态和活跃会话数
- **用户友好**: 直观的操作界面和清晰的反馈提示

### 主要功能

#### 1. 智能对话
- 支持自然语言天气查询
- 支持日常聊天和通用问答
- 多轮对话上下文保持
- 实时加载状态显示
- 错误处理和友好提示

#### 2. 用户管理
- 自定义用户 ID 设置
- 会话历史独立管理
- 一键清空对话历史

#### 3. 系统监控
- 实时系统状态显示
- 活跃会话数量统计
- 自动状态刷新

### 使用指南

1. **访问界面**: 启动应用后访问 http://localhost:8080
2. **设置用户**: 在右下角输入框设置用户 ID（默认：user001）
3. **开始对话**: 在输入框中输入任何问题
4. **查看状态**: 底部状态面板显示系统信息
5. **管理会话**: 使用"清空对话"按钮重置当前会话

### 使用示例

```
用户：今天北京天气怎么样？
助手：北京今天真是个好天气呢！晴空万里，温度适宜...

用户：你好
助手：你好！很高兴见到你！有什么我可以帮助你的吗？

用户：我在哪里？
助手：您当前位于北京

用户：那里的天气如何？
助手：北京当前天气：晴朗，温度 15°C，湿度 45%...

用户：给我一些建议
助手：当然！我可以为您提供各种建议，比如学习方法、工作效率提升等...
```

## API 接口说明

### 1. 天气查询接口

**POST** `/api/agent/query`

请求体：
```json
{
  "query": "今天北京天气怎么样？",
  "userId": "user123"
}
```

响应示例：
```json
{
  "success": true,
  "data": "北京今天真是个好天气呢！晴空万里，温度适宜，正是出门的好时机！",
  "message": "查询成功"
}
```

### 2. 清除会话历史

**DELETE** `/api/agent/conversation/{userId}`

响应示例：
```json
{
  "success": true,
  "message": "会话历史已清除"
}
```

### 3. 系统状态查询

**GET** `/api/agent/status`

响应示例：
```json
{
  "success": true,
  "data": {
    "activeConversations": 5,
    "status": "running",
    "timestamp": 1709456789012
  },
  "message": "系统状态正常"
}
```

## 核心组件介绍

### AgentController
REST API 控制器，提供以下端点：
- `/api/agent/query` - 天气查询
- `/api/agent/conversation/{userId}` - 会话管理
- `/api/agent/status` - 系统状态监控

### WeatherAgentService
核心的 Agent服务类，负责：
- 初始化大语言模型（DashScope Chat Model）
- 注册工具函数（WeatherForLocationTool, UserLocationTool）
- 管理会话状态（使用 MemorySaver 实现内存存储）
- 处理用户查询（异步响应式实现）
- 系统提示词定义 Agent 的角色和行为

**系统提示词核心能力：**
1. 天气查询：可查询各地天气信息
2. 位置识别：根据用户 ID 获取位置
3. 日常对话：回答生活、学习、工作等问题

### 工具函数

#### WeatherForLocationTool
天气查询工具，支持根据城市名获取天气信息。
- 实现 `BiFunction<String, ToolContext, String>` 接口
- 提供模拟天气数据（北京、上海、广州、深圳、杭州等）
- 返回带有双关语和趣味性表达的自然语言回复
- 包含趣味性天气描述和城市特色表达

#### UserLocationTool
用户位置工具，根据用户 ID 获取位置信息。
- 实现 `BiFunction<String, ToolContext, String>` 接口
- 根据用户 ID 的 hash 值映射到不同城市
- 确保相同用户 ID 始终返回相同位置（确定性行为）

### 数据模型

#### QueryRequest
天气查询请求 DTO，包含：
- `query`: 用户查询内容
- `userId`: 用户 ID

#### ResponseFormat
响应格式模型，定义 Agent 返回的数据结构：
- `punnyResponse`: 双关语响应
- `weatherConditions`: 天气条件信息

## 配置说明

### application.yml 主要配置项

```yaml
spring:
  application:
    name: demo-alibaba-agent
  ai:
    dashscope:
      api-key: ${ALIBABA_API_KEY:your-dashscope-api-key}

server:
  port: 8080
  servlet:
    context-path: /

logging:
  level:
    com.devxz: DEBUG
    com.alibaba.cloud.ai: INFO
    org.springframework.ai: INFO

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
  endpoint:
    health:
      show-details: always
```

### 模型参数配置

在 `WeatherAgentService` 中可以调整：
- `temperature`: 0.7 (创造性程度，0-1 之间)
- `maxToken`: 1500 (最大 token 数)
- `model`: qwen-plus (默认模型)

### 工具调用限制

使用 `ModelCallLimitHook` 限制工具调用次数：
- `runLimit`: 5 (最多调用 5 次工具)
- `exitBehavior`: ERROR (超出限制时抛出异常)

## 开发指南

### 添加新的工具函数

1. 创建新的工具类实现 `BiFunction<String, ToolContext, String>`
2. 使用 `@Component` 注解标记为 Spring 组件
3. 在 `WeatherAgentService` 中注入并注册工具
4. 更新系统提示词说明新功能

示例：
```java
@Component
public class MyCustomTool implements BiFunction<String, ToolContext, String> {
    @Override
    public String apply(@ToolParam(description = "参数描述") String param, ToolContext toolContext) {
        // 实现工具逻辑
        return "结果";
    }
}
```

### 自定义响应格式

修改 `ResponseFormat` 类来适应不同的业务需求：
```java
@Data
public class ResponseFormat {
    private String customField1;
    private String customField2;
}
```

### 扩展 Agent 能力

可以通过以下方式扩展：
- 添加更多的工具函数
- 调整系统提示词优化行为
- 集成真实的外部 API（如真实天气 API）
- 实现持久化存储（替换 MemorySaver）
- 添加更多的模型参数配置

## 监控和运维

### Actuator 端点

项目集成了 Spring Boot Actuator，提供以下监控端点：

- **健康检查**: `GET /actuator/health`
- **应用信息**: `GET /actuator/info`
- **指标监控**: `GET /actuator/metrics`

### 日志配置

日志级别可在 `application.yml` 中配置：
- 应用日志：DEBUG
- Spring AI Alibaba: INFO
- Spring AI: INFO

## 常见问题

### Q: API密钥配置不生效？
A: 确保环境变量已正确设置，或直接在 `application.yml` 配置文件中配置。重启应用后生效。

### Q: 查询响应很慢？
A: 
- 检查网络连接是否正常
- 确认 API密钥是否有效
- 可以调整模型参数降低复杂度
- 查看日志了解详细情况

### Q: 如何集成真实天气 API？
A: 修改 `WeatherForLocationTool` 中的 `getMockWeatherData` 方法，替换为真实的 API 调用逻辑。例如：
```java
private String getMockWeatherData(String city) {
    // 调用真实天气 API
    String weatherData = callRealWeatherAPI(city);
    return weatherData;
}
```

### Q: Agent 返回工具调用 JSON 格式而非自然语言？
A: 这是已知问题，解决方案包括：
- 强化系统提示词约束，明确禁止返回工具调用 JSON 格式
- 添加 `maxIterations` 限制防止无限循环
- 要求工具调用结果必须转换为自然语言回复

### Q: 用户位置分配不均匀？
A: 系统使用确定性的位置分配策略，相同用户 ID 始终返回相同位置，确保位置分配的确定性和一致性。

### Q: 如何清空特定用户的会话历史？
A: 调用 DELETE 接口 `/api/agent/conversation/{userId}` 即可清空指定用户的会话历史。

## 许可证

MIT License

## 联系方式

如有问题，请联系项目维护者。

---

**Powered by Spring AI Alibaba | 通义千问大模型**