# aiagent

**Repository Path**: igorchen66/aiagent

## Basic Information

- **Project Name**: aiagent
- **Description**: springai demo
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2026-01-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Boot 3.5 + Spring AI 1.1.2 AI Agent 完整系统

这是一个功能完整的企业级 AI Agent 系统，集成了 Ollama、MySQL、Qdrant，实现了对话管理、RAG、工具调用、权限控制、审计日志和异步任务处理。

## 🎯 核心功能

### 1. 对话管理
- ✅ 多会话管理
- ✅ 对话历史存储（MySQL）
- ✅ 上下文记忆

### 2. RAG（检索增强生成）
- ✅ 向量存储（Qdrant）
- ✅ 文档检索
- ✅ 上下文增强

### 3. 工具调用（Function Calling）
- ✅ **基础工具**：天气查询、计算器、数据库查询
- ✅ **高级工具**：文件操作、API 调用、邮件发送、数据分析
- ✅ **工具链**：支持工具间依赖调用
- ✅ **权限控制**：基于角色的工具访问控制
- ✅ **审计日志**：完整的工具调用记录
- ✅ **异步执行**：长时间运行任务支持

## 📚 技术栈

- **框架**: Spring Boot 3.5.0
- **AI**: Spring AI 1.1.2 + Ollama
- **数据库**: MySQL 8.0+
- **向量库**: Qdrant
- **构建**: Gradle (Groovy)
- **Java**: 21

## 🛠️ 工具列表

| 工具名称 | 功能描述 | 权限要求 |
|---------|---------|---------|
| WeatherTool | 查询城市天气和温度 | GUEST+ |
| CalculatorTool | 数学运算（加减乘除、幂、模） | GUEST+ |
| DatabaseQueryTool | 查询对话历史统计 | USER+ |
| FileOperationsTool | 文件读写、列出、删除 | USER+ |
| ApiCallTool | 调用外部 REST API | USER+ |
| EmailTool | 发送电子邮件 | USER+ |
| DataAnalysisTool | 数据统计分析 | USER+ |

## 🚀 快速开始

### 1. 环境准备

```bash
# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.2
ollama pull nomic-embed-text

# 启动 Qdrant
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

# 创建 MySQL 数据库
CREATE DATABASE ai_agent CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### 2. 配置邮件（可选）

编辑 `application.yml`，取消注释邮件配置：

```yaml
spring:
  mail:
    host: smtp.gmail.com
    port: 587
    username: your-email@gmail.com
    password: your-app-password
```

### 3. 启动项目

```bash
./gradlew bootRun
```

## 📖 API 文档

### 会话管理

#### 创建会话
```bash
curl -X POST http://localhost:8080/api/ai/session
```

#### 简单对话
```bash
curl -X POST http://localhost:8080/api/ai/chat \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "your-session-id",
    "message": "你好"
  }'
```

#### 使用工具的对话
```bash
curl -X POST http://localhost:8080/api/ai/chat/tools \
  -H "Content-Type: application/json" \
  -H "X-Username: john" \
  -d '{
    "sessionId": "your-session-id",
    "message": "北京今天天气怎么样？然后帮我算一下 25 * 48"
  }'
```

### 工具链执行

```bash
curl -X POST http://localhost:8080/api/ai/toolchain/execute \
  -H "Content-Type: application/json" \
  -d '[
    {
      "toolName": "weatherTool",
      "input": {"city": "北京", "unit": "celsius"},
      "outputKey": "weather"
    },
    {
      "toolName": "calculatorTool",
      "input": {"a": 25, "b": 48, "operation": "multiply"},
      "outputKey": "result"
    }
  ]'
```

### 权限管理

#### 查看用户权限
```bash
curl -H "X-Username: john" \
  http://localhost:8080/api/ai/permission/tools
```

#### 授予权限
```bash
curl -X POST http://localhost:8080/api/ai/permission/grant \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john",
    "toolName": "emailTool"
  }'
```

#### 撤销权限
```bash
curl -X POST http://localhost:8080/api/ai/permission/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john",
    "toolName": "emailTool"
  }'
```

### 审计日志

#### 查看用户审计日志
```bash
curl http://localhost:8080/api/ai/audit/user/john
```

#### 工具使用统计
```bash
curl http://localhost:8080/api/ai/audit/statistics/tools
```

#### 用户使用统计
```bash
curl http://localhost:8080/api/ai/audit/statistics/users
```

### 异步任务

#### 提交异步任务
```bash
curl -X POST http://localhost:8080/api/ai/async/submit \
  -H "Content-Type: application/json" \
  -d '{
    "toolName": "dataAnalysisTool",
    "input": {
      "analysisType": "statistics",
      "data": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    }
  }'
```

#### 查询任务状态
```bash
curl http://localhost:8080/api/ai/async/status/{taskId}
```

#### 取消任务
```bash
curl -X DELETE http://localhost:8080/api/ai/async/cancel/{taskId}
```

## 💡 使用示例

### 示例 1: 文件操作
```bash
# 创建会话
SESSION_ID=$(curl -s -X POST http://localhost:8080/api/ai/session | jq -r '.sessionId')

# 对话
curl -X POST http://localhost:8080/api/ai/chat/tools \
  -H "Content-Type: application/json" \
  -H "X-Username: admin" \
  -d "{
    \"sessionId\": \"$SESSION_ID\",
    \"message\": \"帮我创建一个名为 test.txt 的文件，内容是 'Hello, AI Agent!'\"
  }"

# 读取文件
curl -X POST http://localhost:8080/api/ai/chat/tools \
  -H "Content-Type: application/json" \
  -H "X-Username: admin" \
  -d "{
    \"sessionId\": \"$SESSION_ID\",
    \"message\": \"读取 test.txt 文件的内容\"
  }"
```

### 示例 2: 数据分析
```bash
curl -X POST http://localhost:8080/api/ai/chat/tools \
  -H "Content-Type: application/json" \
  -H "X-Username: admin" \
  -d '{
    "sessionId": "your-session-id",
    "message": "帮我分析这组数据：[23, 45, 67, 89, 12, 34, 56, 78, 90, 11]，给出统计摘要"
  }'
```

### 示例 3: 工具链组合
```bash
# 1. 查询天气
# 2. 将温度转换为华氏度
# 3. 发送邮件通知
curl -X POST http://localhost:8080/api/ai/chat/tools \
  -H "Content-Type: application/json" \
  -H "X-Username: admin" \
  -d '{
    "sessionId": "your-session-id",
    "message": "查询北京的天气，然后发送邮件到 user@example.com 通知天气情况"
  }'
```

## 🔐 权限系统

### 角色权限

| 角色 | 默认工具权限 |
|------|------------|
| ADMIN | 所有工具 |
| USER | weatherTool, calculatorTool, databaseQueryTool, fileOperationsTool, dataAnalysisTool |
| GUEST | weatherTool, calculatorTool |

### 自定义权限

管理员可以为用户授予或撤销特定工具的权限：

```java
// 授予权限
permissionService.grantToolPermission("john", "emailTool");

// 撤销权限
permissionService.revokeToolPermission("john", "emailTool");
```

## 📊 审计功能

系统自动记录所有工具调用：

- 用户名
- 工具名称
- 输入参数
- 输出结果
- 执行状态
- 执行时间
- 会话 ID
- 时间戳

## ⚡ 异步任务

对于长时间运行的工具：

1. 提交任务 → 返回 taskId
2. 查询状态 → PENDING / RUNNING / COMPLETED / FAILED
3. 获取结果 → 任务完成后获取
4. 取消任务 → 运行中可取消
5. 清理任务 → 清理已完成的任务

## 🔧 扩展开发

### 添加新工具

#### 1. 创建工具类

```java
public class CustomTool implements Function<Request, Response> {
    @Override
    public Response apply(Request request) {
        // 实现工具逻辑
        return new Response(true, "result", null);
    }

    public record Request(String param) {}
    public record Response(boolean success, String result, String error) {}
}
```

#### 2. 注册工具

```java
@Bean
@Description("工具描述")
public CustomTool customTool() {
    return new CustomTool();
}
```

#### 3. 配置权限

```java
DEFAULT_TOOL_PERMISSIONS.put(
        User.Role.USER,
        Set.of("customTool", ...)
);
```

## 📈 监控和日志

### 日志级别配置

```yaml
logging:
  level:
    com.example.aiagent.tool: DEBUG
    com.example.aiagent.service: INFO
```

### 查看工具调用统计

```bash
# 工具使用排行
curl http://localhost:8080/api/ai/audit/statistics/tools

# 用户活跃度
curl http://localhost:8080/api/ai/audit/statistics/users
```

## 🗄️ 数据库表结构

```sql
-- 用户表
CREATE TABLE users (
                       id BIGINT PRIMARY KEY AUTO_INCREMENT,
                       username VARCHAR(255) UNIQUE NOT NULL,
                       password VARCHAR(255) NOT NULL,
                       email VARCHAR(255) NOT NULL,
                       role VARCHAR(20) NOT NULL,
                       enabled BOOLEAN NOT NULL,
                       created_at DATETIME NOT NULL,
                       updated_at DATETIME
);

-- 用户工具权限表
CREATE TABLE user_tools (
                            user_id BIGINT NOT NULL,
                            tool_name VARCHAR(255) NOT NULL,
                            FOREIGN KEY (user_id) REFERENCES users(id)
);

-- 工具审计日志表
CREATE TABLE tool_audit_logs (
                                 id BIGINT PRIMARY KEY AUTO_INCREMENT,
                                 username VARCHAR(255) NOT NULL,
                                 tool_name VARCHAR(255) NOT NULL,
                                 input_params TEXT,
                                 output TEXT,
                                 success BOOLEAN NOT NULL,
                                 error_message TEXT,
                                 execution_time_ms BIGINT NOT NULL,
                                 session_id VARCHAR(255),
                                 created_at DATETIME NOT NULL
);
```

## 🐛 故障排查

### Ollama 连接失败
```bash
ollama list
ollama serve
```

### 邮件发送失败
- 检查 SMTP 配置
- 确认使用应用专用密码（Gmail）
- 检查防火墙设置

### 工具权限错误
```bash
# 查看用户权限
curl -H "X-Username: john" \
  http://localhost:8080/api/ai/permission/tools
```

## 🎓 最佳实践

1. **工具命名**: 使用清晰的驼峰命名法
2. **错误处理**: 所有工具都应返回友好的错误信息
3. **日志记录**: 关键操作记录 INFO 级别日志
4. **权限最小化**: 默认给予最小权限
5. **异步优先**: 长时间任务使用异步执行
6. **审计完整**: 敏感操作必须记录审计

## 📝 待办事项

- [ ] 实现用户认证（Spring Security）
- [ ] 添加流式响应（SSE）
- [ ] 集成 Redis 缓存
- [ ] 添加 API 限流
- [ ] 实现多模态支持
- [ ] 添加 Prometheus 监控
- [ ] 实现工具版本控制

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

**完整的企业级 AI Agent 系统，开箱即用！** 🚀