# Spring AI 智能体应用开发实验室

**Repository Path**: LLS312885991/spring-ai-lab

## Basic Information

- **Project Name**: Spring AI 智能体应用开发实验室
- **Description**:  基于 Spring AI Alibaba 生态的 AI 应用开发工作台，围绕 Agent 自主推理与 Graph 工作流编排，持续探索智能体应用落地方案。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-03
- **Last Updated**: 2026-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# spring-ai-lab — Spring AI Alibaba 实验室

基于 Spring AI Alibaba 生态的 AI 智能体应用开发实验室，围绕 **Agent 自主推理** 与 **Graph 工作流编排** 两大核心能力，持续探索和构建各类智能体应用落地方案。

[![JDK](https://img.shields.io/badge/JDK-17%20(GraalVM)-orange.svg)](https://www.graalvm.org/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.8-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![Spring AI](https://img.shields.io/badge/Spring%20AI-1.1.2-green.svg)](https://spring.io/projects/spring-ai)
[![Spring AI Alibaba](https://img.shields.io/badge/Spring%20AI%20Alibaba-1.1.2.2-blue.svg)](https://github.com/alibaba/spring-ai-alibaba)
[![DeepSeek](https://img.shields.io/badge/Model-deepseek--v4--flash-purple.svg)](https://www.deepseek.com/)
[![Maven](https://img.shields.io/badge/Maven-3.9.16-red.svg)](https://maven.apache.org/)

## 项目简介

本项目定位为 **Spring AI Alibaba 应用开发工作台**，基于 Agent Framework 与 Graph 工作流引擎，持续验证和构建各类 AI 智能体应用。当前已完成首个验证案例，后续将不断扩充实验项目。

### 两种核心开发模式

| 模式 | 核心组件 | 控制方式 | 适合场景 |
|------|---------|---------|---------|
| **ReactAgent** | `ReactAgent` + `@Tool` | LLM 自主推理与决策 | 开放性问题、多步推理、工具灵活组合 |
| **Graph 工作流** | `StateGraph` + `NodeAction` | 代码显式编排流程 | 流程确定、分支清晰、需要审计可控 |

### 实验项目

| # | 项目 | 模式 | 说明 | 状态 |
|---|------|------|------|------|
| 1 | 智能工单处理系统 | Agent + Graph | 工单分类、知识库检索、缺陷创建、Agent 自主排查、人工审核 | ✅ 已完成 |

> 后续计划方向：客服机器人、自动化运维、代码审查助手、数据分析 Agent 等。

## 快速开始

### 环境要求

- **JDK 17**（GraalVM）：`D:\jdks\graalvm-jdk-17.0.9+11.1`
- **Maven 3.9.16**：`D:\applications\apache-maven-3.9.16`
- **DeepSeek API Key**：已配置在 `application.yml` 中

### 启动

```bash
cd spring-ai-lab/lab-app
set JAVA_HOME=D:\jdks\graalvm-jdk-17.0.9+11.1
set PATH=D:\applications\apache-maven-3.9.16\bin;%JAVA_HOME%\bin;%PATH%
mvn spring-boot:run
```

启动后打开浏览器访问：

- **Agent 对话**：http://localhost:8080/chatui/index.html（Studio Chat UI，选择 `business-assistant`）
- **Graph 工单处理**：`POST http://localhost:8080/ticket`

### 多模块安装

修改子模块后需要先安装到本地仓库：

```bash
# 修改 lab-extensions 后
mvn install -pl lab-extensions -DskipTests

# 修改 lab-common 后
mvn install -pl lab-common -DskipTests
```

## 项目结构

```
spring-ai-lab/
├── pom.xml                              # 父 POM：BOM 管理（Spring AI + Alibaba 版本统一管控）
├── lab-common/                          # 公共模块（纯 POJO/DTO，零 AI 依赖）
├── lab-extensions/                      # 自定义 @Tool 工具模块
│   └── tool/
│       ├── CalculatorTools.java         # 数学表达式计算
│       ├── OrderTools.java              # 工单查询与统计
│       ├── InventoryTools.java          # 知识库搜索
│       └── DiagnosticTools.java         # 系统诊断（日志搜索 + 状态检查）
├── lab-app/                             # 主应用（Web + Agent + Graph + Studio 组装）
│   ├── agent/AgentConfig.java           # ReactAgent Bean 注册
│   ├── controller/
│   │   ├── DemoController.java          # /chat — Agent 对话端点
│   │   └── TicketController.java        # /ticket — Graph 工单处理端点
│   ├── workflow/demo/
│   │   ├── TicketClassification.java    # State 数据模型
│   │   └── TicketAgentGraph.java        # 8 节点工单 Graph + 4 种错误处理策略
│   └── resources/application.yml        # DeepSeek 模型配置
├── CLAUDE.md                            # 项目开发指南（详细 API 模式与注意事项）
├── 测试用例.md                           # Agent + Graph 全覆盖测试用例
├── Spring-AI-Alibaba-生态速览.md         # Spring AI Alibaba 生态体系深度解读
└── README.md                            # 本文件
```

## 当前示例：智能工单处理系统

首个验证案例，完整演示 Agent 与 Graph 两种模式在同一个业务场景下的实现。

### 一、Agent 模式 — 工具调用与多步推理

通过 `ReactAgent` 注册 4 个 `@Tool` 工具，Agent 自主决定何时调用哪个工具：

```java
// AgentConfig.java
ReactAgent agent = ReactAgent.builder()
    .name("business-assistant")
    .chatClient(chatClient)
    .tools(toolCallbacks)  // CalculatorTools + OrderTools + InventoryTools + DiagnosticTools
    .build();
```

| 工具 | 方法 | 说明 |
|------|------|------|
| `CalculatorTools` | `calculate(expr)` | 数学表达式计算 |
| `OrderTools` | `getTicketInfo(id)` / `getTicketCountByCategory(cat)` | 工单查询 |
| `InventoryTools` | `searchKnowledgeBase(kw)` / `listCategories()` | 知识库检索 |
| `DiagnosticTools` | `searchLogs(mod)` / `checkSystemStatus(mod)` / `listComponents()` | 系统诊断 |

Agent 支持多工具协作：一次对话可依次调用多个工具，观察中间结果后继续推理，直到给出最终答案。

### 二、Graph 工作流模式 — 8 节点工单处理流程

```
START → read_ticket → classify_intent ──┬── technical → search_knowledge ──┐
                                         ├── bug → create_bug_ticket ──────┤
                                         ├── complex → troubleshoot ───────┤
                                         └── 其他 → ──────────────────────→ draft_solution
                                                                               │
                                                                ┌──────────────┼──────────────┐
                                                           needsHumanReview              不需要审核
                                                                │                              │
                                                                ▼                              ▼
                                                         human_review                     send_reply
                                                         (interruptBefore)                    │
                                                                │                              │
                                                                └────────→ send_reply ←────────┘ → END
```

**6 条分类路由**：`technical`（搜知识库）、`bug`（创建缺陷单）、`complex`（Agent 自主排查）、`billing`/`account`/`feature`/`general`（直接起草方案）

**优先级审核**：`high` / `critical` 自动触发人工审核节点（`interruptBefore`），`low` / `medium` 跳过

**节点内嵌 Agent**：`TroubleshootAgentNode` 演示 Graph 节点内部署 ReactAgent — 外层 Graph 管流程编排，节点内 Agent 做多步推理（查日志 → 查状态 → 综合分析）

### 三、四种错误处理策略

| 策略 | 适用节点 | 实现方式 |
|------|---------|---------|
| ① 瞬时错误 | ClassifyIntent / DraftSolution | ChatClient 层自动重试 |
| ② LLM 可恢复 | ClassifyIntent | 格式异常 → 存 error → 自身循环重试 |
| ③ 用户可修复 | HumanReview | `CompileConfig.interruptBefore` 挂起等待 |
| ④ 意外错误 | SendReply | 不 catch，异常自然冒泡 |

## API 端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/chat` | POST | Agent 对话（`{"message": "..."}` → Agent 自主推理回复） |
| `/ticket` | POST | Graph 工单处理（`{"content": "..."}` → 全流程节点执行结果） |
| `/ticket/pending` | GET | 查看待审核工单列表（自动扫描 checkpoints/ 目录） |
| `/ticket/review/{threadId}` | GET | 提交审核结果（`?action=approve` 或 `?action=reject&comment=意见`） |
| `/chatui/index.html` | GET | Studio Chat UI 调试界面 |

## 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| JDK | 17 (GraalVM) | 运行环境 |
| Spring Boot | 3.5.8 | 应用框架 |
| Spring AI | 1.1.2 | 统一 AI 抽象层（ChatClient / Tool Calling） |
| Spring AI Alibaba Agent Framework | 1.1.2.2 | ReactAgent 多步推理 |
| Spring AI Alibaba Graph Core | 1.1.2.2 | StateGraph 工作流引擎 |
| Spring AI Alibaba Studio | 1.1.2.2 | 嵌入式 Chat 调试 UI |
| DeepSeek | deepseek-v4-flash | 大语言模型（OpenAI 兼容 API） |
| Maven | 3.9.16 | 项目构建 |

## 模块依赖关系

```
lab-common (纯 POJO，零依赖)
    ↓
lab-extensions (@Tool 工具，依赖 Spring AI + lab-common)
    ↓
lab-app (Agent + Graph + Studio，依赖 lab-common + lab-extensions)
```

## 参考资源

- **Graph 工作流编排指南**：https://java2ai.com/docs/frameworks/graph-core/quick-start
- **Agent 开发教程**：https://java2ai.com/docs/frameworks/agent-framework/tutorials/agents
- **Spring AI Alibaba 生态速览**：[Spring-AI-Alibaba-生态速览.md](./Spring-AI-Alibaba-生态速览.md)
- **测试用例**：[测试用例.md](./测试用例.md)
- **Spring AI Alibaba GitHub**：https://github.com/alibaba/spring-ai-alibaba

## 注意事项

1. 修改 `lab-extensions` 后需 `mvn install -pl lab-extensions -DskipTests`，否则 `lab-app` 的 `spring-boot:run` 使用的是本地仓库中的旧版本
2. `@Configuration` 类名和 `@Bean` 方法名不能相同（会注册两个同名 Bean 导致冲突）
3. 已排除 `spring-ai-alibaba-autoconfigure-dashscope`，因为使用 DeepSeek 不需要 DashScope 自动配置
4. `@Tool(description = "...")` 不支持跨行拼接描述字符串，必须单行书写
5. `OverAllState.invoke()` 返回 `Optional<OverAllState>`，取值用 `state.value("key")` 返回 `Optional<Object>`