# demo-langchain4j-agent

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

## Basic Information

- **Project Name**: demo-langchain4j-agent
- **Description**: 基于 Spring Boot 3.5.0 + LangChain4j 1.11.0 构建的智能票务助手，集成阿里云通义千问大模型，提供自然的对话式票务咨询和预订服务。
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-03
- **Last Updated**: 2026-03-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LangChain4j 票务 Agent 示例

基于 **Spring Boot 3.5.0** + **LangChain4j 1.11.0** 构建的智能票务助手，集成阿里云通义千问大模型，提供自然的对话式票务咨询和预订服务。

## ✨ 核心特性

- 🤖 **AI 智能对话** - 基于 LangChain4j Agent 框架，支持自然语言交互
- 💬 **流式响应** - 实时打字机效果，更快的响应体验
- 🧠 **对话记忆** - 基于 ChatMemoryProvider 的多轮对话上下文记忆
- 👥 **用户隔离** - 基于 SessionId 的多用户会话隔离
- 🎫 **票务管理** - 完整的票务查询、预订、取消功能
- 📊 **可观测性** - 集成 Micrometer 监控 LLM 调用指标
- 🌐 **友好界面** - 精美的 Web 前端界面

## 🛠️ 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| **Java** | 17 | 开发语言 |
| **Spring Boot** | 3.5.0 | 应用框架 |
| **LangChain4j** | 1.11.0-beta19 | AI Agent 框架 |
| **阿里云 DashScope** | 2.22.6 | 通义千问大模型 |
| **Gradle** | 8.5 | 构建工具 |
| **Lombok** | Latest | 代码简化 |
| **Micrometer** | Latest | 指标监控 |
| **Reactor** | Latest | 流式响应支持 |

## 📁 项目结构

```
demo-langchain4j-agent/
├── src/main/java/com/devxz/agent/
│   ├── Application.java                    # 应用入口
│   ├── ai/
│   │   └── TicketAssistant.java            # AI 服务接口 (@AiService)
│   ├── config/
│   │   └── ChatMemoryConfig.java           # 聊天记忆配置 (ChatMemoryProvider)
│   ├── controller/
│   │   ├── TicketAssistantController.java  # AI 对话 REST 接口
│   │   └── TicketController.java           # 票务管理 REST 接口
│   ├── domain/
│   │   ├── TicketInfo.java                 # 票务信息模型
│   │   └── TicketOrder.java                # 订单模型
│   ├── service/
│   │   └── TicketService.java              # 票务业务服务
│   └── tools/
│       ├── TicketQueryTools.java           # 票务查询工具 (@Tool)
│       └── TicketOrderTools.java           # 订单管理工具 (@Tool)
├── src/main/resources/
│   ├── static/
│   │   ├── index.html                      # 主界面（AI 对话 + 票务管理）
│   │   └── welcome.html                    # 欢迎页面
│   └── application.yaml                    # 应用配置
└── build.gradle                            # Gradle 构建配置
```

## 🚀 快速开始

### 1. 环境要求

- Java 17+
- Gradle 8.5+
- 阿里云 DashScope API Key

### 2. 获取 API Key

访问 [阿里云 DashScope 控制台](https://dashscope.console.aliyun.com/apiKey) 创建 API 密钥

### 3. 配置应用

在 `src/main/resources/application.yaml` 中配置：

```yaml
langchain4j:
  community:
    dashscope:
      chat-model:
        api-key: ${ALI_QWEN_API_KEY:your-dashscope-api-key-here}  # 替换为你的 API Key
        model-name: qwen-plus
      streaming-chat-model:
        api-key: ${ALI_QWEN_API_KEY:your-dashscope-api-key-here}
        model-name: qwen-plus
```

**或使用环境变量：**

```bash
# Windows
set ALI_QWEN_API_KEY=sk-xxxxxxxxxxxxxx

# Linux/Mac
export ALI_QWEN_API_KEY=sk-xxxxxxxxxxxxxx
```

### 4. 构建并运行

```bash
# Windows
gradlew.bat build
gradlew.bat bootRun

# Linux/Mac
./gradlew build
./gradlew bootRun
```

应用启动后访问：http://localhost:8080

## 🌐 Web 界面

### 欢迎页面
访问：http://localhost:8080/welcome.html

### 主界面（推荐）
访问：http://localhost:8080/index.html

**功能模块：**
- 💬 **AI 对话** - 与票务助手自然语言交流（支持流式输出）
- 🎟️ **票务查询** - 可视化查看所有可购票务
- 📝 **在线订票** - 表单式订票操作
- 📋 **订单查询** - 输入订单号快速查询

## 📡 REST API

### AI 对话接口

```bash
# 普通对话（带会话记忆）
curl "http://localhost:8080/api/assistant/chat?message=你好，有什么票可以买？&sessionId=user123"

# 流式对话（推荐）
curl "http://localhost:8080/api/assistant/stream?message=帮我订两张 VIP 票&sessionId=user123"
```

**参数说明：**
- `message` - 用户消息
- `sessionId` - 会话 ID（可选，默认：default-user），用于标识不同用户，保持对话记忆

### 票务查询接口

```bash
# 查询所有票务
curl http://localhost:8080/api/tickets

# 按日期查询
curl "http://localhost:8080/api/tickets/by-date?date=2026-03-05"

# 查询票务详情
curl http://localhost:8080/api/tickets/T001
```

### 订单管理接口

```bash
# 创建订单
curl -X POST http://localhost:8080/api/tickets/orders \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "张三",
    "contactPhone": "13800138000",
    "ticketType": "VIP 票",
    "quantity": 2
  }'

# 查询订单
curl http://localhost:8080/api/tickets/orders/ORD1234567890

# 取消订单
curl -X POST "http://localhost:8080/api/tickets/orders/ORD1234567890/cancel?reason=行程变更"
```

## 🧠 核心功能

### 1. AI 智能对话（支持多轮记忆）

通过 `@AiService` 和 `@MemoryId` 实现带记忆的对话：

```java
@AiService
public interface TicketAssistant {
    @SystemMessage("你是一个专业的票务助手...")
    String chat(@UserMessage String userMessage, @MemoryId String memoryId);
    
    @SystemMessage("你是一个专业的票务助手...")
    Flux<String> streamingChat(@UserMessage String userMessage, @MemoryId String memoryId);
}
```

**特性：**
- ✅ 自动记忆用户对话历史
- ✅ 支持多轮对话上下文理解
- ✅ 基于 sessionId 的用户隔离
- ✅ 消息窗口记忆（最近 20 条）

### 2. Tool 工具调用

LangChain4j 自动扫描 `@Component` 类中标注 `@Tool` 的方法：

**票务查询工具 (`TicketQueryTools`)：**
- `queryAllAvailableTickets()` - 查询所有可用票务
- `queryTicketsByDate(String date)` - 按日期查询
- `getTicketDetails(String ticketId)` - 查询票务详情

**订单管理工具 (`TicketOrderTools`)：**
- `createTicketOrder(...)` - 创建订单
- `cancelTicketOrder(...)` - 取消订单
- `getOrderDetails(...)` - 查询订单详情
- `getOrderStatus(...)` - 查询订单状态

### 3. 聊天记忆配置

```java
@Configuration
public class ChatMemoryConfig {
    
    @Bean
    public ChatMemoryProvider chatMemoryProvider() {
        return memoryId -> 
            MessageWindowChatMemory.builder()
                .id(memoryId)
                .maxMessages(20)  // 保留最近 20 条消息
                .build();
    }
}
```

### 4. 流式响应

前端使用 ReadableStream 实现打字机效果：

```javascript
const reader = response.body.getReader();
const decoder = new TextDecoder('utf-8');

while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value, { stream: true });
    aiResponse += chunk;
    aiMessageDiv.textContent = aiResponse;
}
```

## 📊 可观测性

集成 Micrometer 监控 LLM 调用指标：

```bash
# 查看 token 使用情况
curl http://localhost:8080/actuator/metrics/gen_ai.client.token.usage

# Prometheus 格式指标
curl http://localhost:8080/actuator/prometheus
```

**监控端点：**
- `/actuator/health` - 健康检查
- `/actuator/info` - 应用信息
- `/actuator/metrics` - 指标数据
- `/actuator/prometheus` - Prometheus 格式指标

## 🔧 配置说明

详细配置请参考 `src/main/resources/application.yaml` 文件。

**可选配置项：**
- `temperature` - 模型温度（默认：0.7）
- `timeout` - 超时时间（默认：PT60S）
- `log-requests` - 记录请求日志（默认：true）
- `log-responses` - 记录响应日志（默认：true）

## 📦 依赖说明

```gradle
dependencies {
    // Spring Boot starters
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'

    // LangChain4j Spring Boot starter
    implementation 'dev.langchain4j:langchain4j-spring-boot-starter:1.11.0-beta19'
    
    // 阿里云 DashScope（通义千问）Spring Boot starter
    implementation 'dev.langchain4j:langchain4j-community-dashscope-spring-boot-starter:1.11.0-beta19'

    // LangChain4j Reactor support for streaming
    implementation 'dev.langchain4j:langchain4j-reactor:1.11.0-beta19'

    // Micrometer metrics for observability
    implementation 'io.micrometer:micrometer-registry-prometheus'

    // Lombok
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'

    // Jackson for JSON processing
    implementation 'com.fasterxml.jackson.core:jackson-databind'

    // Testing
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0'
}
```

## 🧪 测试

运行单元测试：

```bash
# Windows
gradlew.bat test

# Linux/Mac
./gradlew test
```

测试类：`TicketAgentApplicationTests`

## 🎯 使用示例

### 1. AI 对话订票流程

```
用户：你好，有什么票可以买？
AI：您好！目前有以下票务信息：
     1. VIP 票 - ¥880 - 北京工人体育馆
     2. 普通票 - ¥380 - 北京工人体育馆
     3. 学生票 - ¥180 - 上海大舞台

用户：我想预订上海大舞台的票
AI：好的，请问您需要几张票？请提供您的姓名和联系电话。

用户：2 张，我叫张三，电话 13800138000
AI：订单创建成功！订单编号：ORD1234567890
```

### 2. 使用 curl 测试

```bash
# 第一轮：查询票务
curl "http://localhost:8080/api/assistant/stream?message=你好，有什么票？&sessionId=test-user"

# 第二轮：订票（AI 会记住上下文）
curl "http://localhost:8080/api/assistant/stream?message=我要订上海大舞台的票&sessionId=test-user"
```

## ⚠️ 注意事项

1. **API Key 安全**
   - 不要将 API Key 提交到版本控制系统
   - 使用环境变量或本地配置文件管理
   - 生产环境使用密钥管理服务

2. **会话记忆**
   - 前端自动为每个用户生成唯一的 sessionId
   - sessionId 存储在 localStorage 中，刷新页面仍有效
   - 清除浏览器缓存会重置会话

3. **消息窗口**
   - 默认保留最近 20 条消息
   - 超出后会自动丢弃最早的消息
   - 可在 ChatMemoryConfig 中调整

4. **流式输出**
   - 需要浏览器支持 ReadableStream API
   - 现代浏览器均支持

## 📚 参考资料

- [LangChain4j 官方文档](https://docs.langchain4j.dev/)
- [LangChain4j Spring Boot 集成](https://docs.langchain4j.dev/tutorials/spring-boot-integration)
- [LangChain4j Tools](https://docs.langchain4j.dev/tutorials/tools)
- [LangChain4j Chat Memory](https://docs.langchain4j.dev/tutorials/chat-memory)
- [阿里云 DashScope 文档](https://help.aliyun.com/zh/dashscope/)
- [通义千问模型介绍](https://help.aliyun.com/zh/dashscope/developer-reference/model-introduction)

## 👨‍ 开发团队

**作者**: dev 小筑  
**版权**: © 2020-2026 dev 小筑  
**许可**: Apache 2.0

---

**最后更新**: 2026-03-04  
**版本**: 1.0.0