AI Agent 项目学习笔记（一）：项目总体介绍与智能体链路概览

1. 本期目标

ai_agent 是一个基于 Spring Boot 3 和 Spring AI 构建的垂直场景智能体示例项目，当前以"恋爱咨询 / 约会规划"为主要场景，覆盖多轮对话、RAG 检索增强、工具调用、结构化输出和会话记忆等能力。项目目标也不是只做一个简单聊天机器人，而是验证一条更完整的智能体实现链路。GitHubhttps://github.com/Tittifer/ai_agent

本期主要解决几个问题：

复制代码

1. 这个项目想解决什么问题？
2. 它和普通聊天机器人有什么区别？
3. 项目的核心能力有哪些？
4. 项目整体目录结构是什么？
5. 一条完整的智能体链路是如何工作的？
6. 后续博客应该围绕哪些模块继续深入？

2. 项目定位：不是普通聊天机器人

如果只是做一个普通聊天机器人，后端逻辑可能非常简单：

复制代码

用户输入问题
    ↓
调用大模型
    ↓
返回模型回答

这种系统可以完成基础问答，但能力边界比较明显：

复制代码

只能根据模型已有知识回答
无法稳定记住多轮上下文
无法读取本地知识库
无法主动搜索网页
无法抓取网页内容
无法生成 PDF 等真实文件
无法执行外部工具

而 ai_agent 项目的目标更进一步。

它希望构建的是一个具有 Agent 特征的智能体，也就是：

复制代码

用户提出需求
    ↓
智能体理解任务
    ↓
结合会话记忆理解上下文
    ↓
必要时检索本地知识库
    ↓
必要时调用外部工具
    ↓
整理结果并返回

所以，它不是单纯"问一句答一句"，而是一个围绕 Spring AI 生态搭建的智能体能力样例。

可以简单理解为：

复制代码

普通聊天机器人：
重点是"模型回答"。

AI Agent：
重点是"模型 + 记忆 + 知识库 + 工具 + 任务执行"。

3. 当前业务场景：恋爱咨询 / 约会规划

这个项目当前选择的垂直场景是"恋爱咨询 / 约会规划"。

在核心类 LoveApp 中，系统提示词要求模型扮演"深耕恋爱心理领域的专家"，并围绕单身、恋爱、已婚三种状态引导用户描述问题，再给出专属解决方案。(GitHub)

也就是说，项目不是做一个泛泛的聊天助手，而是先给智能体设定了一个明确角色：

复制代码

恋爱心理专家

它的典型使用场景可能是：

复制代码

用户：我最近和对象总是因为小事吵架，怎么办？
智能体：先询问沟通方式、矛盾起因、双方反应，再给出建议。

用户：我想策划一次约会，有什么建议？
智能体：可以结合用户需求、地点、预算，必要时调用搜索工具。

用户：帮我整理一份恋爱分析报告。
智能体：可以生成结构化报告，甚至进一步输出 PDF。

这个场景的好处是：业务边界相对明确，适合验证智能体能力。

如果一开始就做通用 Agent，范围会非常大，不利于学习项目结构。而垂直场景 Agent 更适合初学者理解：

复制代码

先明确角色
再明确能力
最后逐步扩展工具和知识库

4. 项目的核心能力

从 README 可以看到，项目当前覆盖了多个智能体关键能力：

复制代码

多轮对话
结构化输出
RAG 检索增强
查询重写
工具调用
日志观测
记忆持久化扩展
向量存储扩展

README 中明确列出了这些功能特性，例如基于 conversationId 的上下文连续对话、将模型返回结果映射为 Java 对象、基于本地 Markdown 文档构建知识库、检索前进行 Query Rewrite，以及支持搜索、抓取、下载、文件读写、终端执行和 PDF 生成等工具调用能力。(GitHub)

可以把这些能力分成五类理解。

5. 能力一：多轮对话

多轮对话解决的是：

复制代码

模型如何记住前面聊过什么？

普通接口每次请求都是独立的。如果没有记忆，模型并不知道用户上一轮说过什么。

例如：

复制代码

用户：我和女朋友最近总吵架。
AI：可以先冷静沟通。

用户：那我应该怎么开口？
AI：你指什么事情？

如果没有上下文，第二轮回答就会断掉。

而在 ai_agent 中，项目支持基于 conversationId 的连续对话。也就是说，只要同一个用户或同一个会话使用相同的 conversationId，系统就可以把历史消息带入后续模型调用中。README 中也说明项目支持基于 conversationId 的上下文连续对话，并默认启用内存版 MessageWindowChatMemory。(GitHub)

可以理解为：

复制代码

conversationId = 一次会话的编号

同一个 conversationId：
    能共享上下文

不同 conversationId：
    上下文相互隔离

这是 Agent 的基础能力之一。

6. 能力二：结构化输出

普通大模型输出通常是一段自然语言文本，例如：

复制代码

我建议你先冷静下来，然后选择一个合适的时间沟通......

但在很多业务系统中，我们不只想要自然语言，还希望把模型输出转成程序可以处理的结构化对象。

例如：

复制代码

{
  "title": "小明的恋爱报告",
  "suggestions": [
    "先确认矛盾来源",
    "避免情绪化表达",
    "约定固定沟通时间"
  ]
}

LoveApp 中定义了一个 LoveReport record，并在 doChatWithReport 方法中通过 .entity(LoveReport.class) 将模型输出映射成 Java 对象。(GitHub)

这说明项目不仅关注"模型说了什么"，还关注：

复制代码

模型输出能不能被程序继续使用？

结构化输出在很多场景中都很重要，例如：

复制代码

生成报告
生成表单
生成分析结果
生成配置参数
生成任务计划

所以这一部分后面可以单独写一期。

7. 能力三：RAG 检索增强

RAG 的全称是 Retrieval-Augmented Generation，也就是检索增强生成。

它解决的问题是：

复制代码

模型不知道项目自己的知识怎么办？
模型回答容易凭空编造怎么办？
模型需要基于本地资料回答怎么办？

项目 README 中说明，当前默认使用本地 Markdown 文档作为知识源。核心流程包括：LoveAppDocumentLoader 加载本地文档，MarkdownDocumentReader 读取文档并补充元数据，MyKeywordEnricher 增强关键词元数据，QueryRewriter 对用户问题进行查询重写，LoveAppVectorStoreConfig 将文档写入 SimpleVectorStore，最后通过 QuestionAnswerAdvisor 在对话时执行检索增强。(GitHub)

可以简单理解为：

复制代码

本地知识文档
    ↓
切分和处理
    ↓
写入向量库
    ↓
用户提问
    ↓
检索相关文档片段
    ↓
把检索结果交给模型
    ↓
模型基于资料回答

对于恋爱咨询场景，本地知识库可能包括：

复制代码

沟通技巧
约会建议
亲密关系维护
冲突处理方法
婚姻关系建议

这样模型回答就不只是依赖自身参数中的知识，而可以结合项目提供的领域资料。

8. 能力四：工具调用

工具调用是 Agent 和普通聊天机器人的重要区别。

普通聊天机器人只能回答：

复制代码

我建议你搜索一下附近的餐厅。

但具备工具调用能力的 Agent 可以进一步做：

复制代码

我帮你搜索附近餐厅
    ↓
抓取网页内容
    ↓
整理约会地点
    ↓
下载相关资源
    ↓
生成 PDF 计划

项目 README 中说明，ai_agent 通过 ToolRegistration 统一注册工具，并转换为 ToolCallback[] 注入模型。当前已经实现的工具包括：网页搜索、网页内容抓取、资源下载、文件读写、终端命令执行、PDF 生成和任务终止。(GitHub)

也就是说，项目中的智能体不只是"会说"，还可以"调用工具做事"。

可以把工具调用理解为：

复制代码

模型判断自己需要外部能力
    ↓
选择合适工具
    ↓
生成工具调用参数
    ↓
后端执行工具
    ↓
工具结果返回模型
    ↓
模型整理最终回答

这就是 Agent 从"问答系统"走向"任务执行系统"的关键。

9. 能力五：会话记忆扩展

项目当前默认使用的是内存版 MessageWindowChatMemory。它适合快速实现多轮对话，但有一个问题：

复制代码

服务重启后，内存中的历史对话会丢失。

因此项目还提供了一个基于文件系统的持久化实现：

复制代码

FileBasedChatMemory

README 中说明，FileBasedChatMemory 使用 Kryo 对消息对象进行序列化，按 conversationId 写入本地文件，并支持服务重启后恢复历史会话。(GitHub)

这说明项目已经考虑到了从"临时记忆"到"持久化记忆"的扩展。

可以简单理解为：

复制代码

内存版 ChatMemory：
速度快，实现简单，但服务重启后丢失。

文件版 ChatMemory：
可以持久保存，但不适合高并发和复杂查询。

数据库 / Redis 版 ChatMemory：
更适合正式业务系统。

后续如果要做正式平台，可以把记忆保存到：

复制代码

MySQL
PostgreSQL
Redis
MongoDB

这样才能支持更完整的用户会话管理。

10. 技术栈概览

项目的技术栈也比较适合学习 Spring AI 智能体开发。

README 中列出的主要技术包括：

复制代码

Java 21
Spring Boot 3.4.4
Spring Web
Spring AI 1.0.0
Spring AI Alibaba DashScope
Spring AI RAG / Vector Store / MCP Client
PostgreSQL + PgVector
LangChain4j DashScope
Hutool
Jsoup
iText PDF
Knife4j
Kryo

这些技术覆盖了智能体项目中的多个层面：Web 服务、模型调用、RAG、向量存储、网页解析、PDF 生成、接口文档和序列化。(GitHub)

可以按照作用分成几类：

复制代码

基础后端：
Java 21、Spring Boot、Spring Web

模型调用：
Spring AI、Spring AI Alibaba DashScope、LangChain4j DashScope

RAG 和向量库：
Spring AI RAG、SimpleVectorStore、PostgreSQL、PgVector

工具能力：
Jsoup、Hutool、iText PDF

工程辅助：
Knife4j、Kryo

这说明该项目很适合作为 Spring AI Agent 的综合练习项目。

11. 项目目录结构

项目主要代码位于：

复制代码

src/main/java/com/ai/aiagent

根据 README，目录结构大致是：

复制代码

src/main/java/com/ai/aiagent
├─ advisor      # 自定义 Advisor，如日志记录、Re-Reading 增强
├─ app          # 智能体主应用入口，封装聊天 / RAG / Tool Calling 能力
├─ chatmemory   # 自定义对话记忆实现
├─ constant     # 常量定义
├─ controller   # Web 接口（当前仅健康检查）
├─ rag          # RAG 相关配置、文档加载、查询增强、向量存储
└─ tool         # 可供模型调用的工具实现与注册

README 中也给出了这几个目录及其作用。(GitHub)

从目录结构看，项目的模块划分比较清晰：

复制代码

app：
负责智能体主流程

advisor：
负责模型调用增强

chatmemory：
负责对话记忆

rag：
负责检索增强

tool：
负责工具调用

controller：
负责 Web 接口

也就是说，这个项目不是把所有逻辑都写在一个 Service 里，而是按智能体能力进行了拆分。

12. 核心入口：LoveApp

项目中最核心的类是：

复制代码

LoveApp

它位于：

复制代码

src/main/java/com/ai/aiagent/app/LoveApp.java

README 中也把 LoveApp 称为智能体主链路的核心入口，并列出它提供的几个方法：普通对话 doChat、结构化报告 doChatWithReport、RAG 对话 doChatWithRag、工具调用 doChatWithTools。(GitHub)

从源码看，LoveApp 通过构造函数接收 ChatModel，然后使用 ChatClient.builder(dashscopeChatModel) 构建聊天客户端，并设置默认系统提示词和默认 Advisor。(GitHub)

可以理解为：

复制代码

ChatModel：
底层模型能力

ChatClient：
Spring AI 封装后的对话客户端

LoveApp：
面向业务场景封装的智能体应用

所以后面深入学习时，可以围绕 LoveApp 展开。

13. LoveApp 中的四条能力链路

LoveApp 里可以看到四种典型调用方式。

13.1 普通对话：doChat

doChat 是基础对话方法。

它接收：

复制代码

message：用户输入
chatId：会话 ID

然后通过 ChatClient 调用模型，并通过 Advisor 参数传入 ChatMemory.CONVERSATION_ID，从而支持多轮对话记忆。(GitHub)

流程可以理解为：

复制代码

用户输入 message
    ↓
传入 chatId
    ↓
ChatClient 调用模型
    ↓
MessageChatMemoryAdvisor 处理上下文
    ↓
返回模型回复

13.2 结构化输出：doChatWithReport

doChatWithReport 用于生成结构化恋爱报告。

它不是返回普通字符串，而是返回：

复制代码

LoveReport

其中包含：

复制代码

title
suggestions

源码中通过 .entity(LoveReport.class) 把模型输出转换成 Java 对象。(GitHub)

这说明 Spring AI 可以把模型响应进一步映射成业务对象，而不是只能处理文本。

13.3 RAG 对话：doChatWithRag

doChatWithRag 用于检索增强对话。

它会先调用：

复制代码

queryRewriter.doQueryRewrite(message)

对用户问题进行查询改写，然后再通过 QuestionAnswerAdvisor(loveAppVectorStore) 接入本地向量知识库进行检索增强。(GitHub)

流程可以理解为：

复制代码

用户原始问题
    ↓
Query Rewrite
    ↓
改写后的问题
    ↓
向量库检索相关文档
    ↓
把检索结果交给模型
    ↓
模型生成回答

13.4 工具调用：doChatWithTools

doChatWithTools 用于支持工具调用。

它通过：

复制代码

.toolCallbacks(allTools)

把所有工具注入到模型调用中。源码中 allTools 是一个 ToolCallback[]，由 Spring 注入。(GitHub)

流程可以理解为：

复制代码

用户提出复杂需求
    ↓
模型判断是否需要工具
    ↓
调用搜索 / 抓取 / 文件 / PDF 等工具
    ↓
工具结果返回模型
    ↓
模型组织最终结果

这条链路是 Agent 能力最明显的体现。

14. 一条完整智能体链路如何工作？

综合前面的内容，可以把项目中的智能体链路理解为：

复制代码

用户输入需求
    ↓
LoveApp 接收 message 和 chatId
    ↓
ChatClient 构建模型请求
    ↓
System Prompt 限定智能体角色
    ↓
ChatMemory 根据 conversationId 加载上下文
    ↓
Advisor 对请求或响应进行增强
    ↓
如果是 RAG 模式，则先进行查询改写和向量检索
    ↓
如果是 Tool Calling 模式，则模型可以调用外部工具
    ↓
模型生成最终结果
    ↓
返回文本或结构化对象

如果画成更直观的流程图，可以写成：

复制代码

User Message
    ↓
LoveApp
    ↓
ChatClient
    ↓
System Prompt
    ↓
Advisor Chain
    ├─ ChatMemory
    ├─ Logger
    ├─ QuestionAnswerAdvisor
    └─ ToolCallback
    ↓
ChatModel
    ↓
Response

这就是项目的核心思想。

它不是单纯地调用模型，而是围绕模型调用构建了一套增强链。

15. 和 ai-code 项目的区别

前面学习的 ai-code 项目重点是：

复制代码

用户输入需求
    ↓
AI 生成代码
    ↓
保存文件
    ↓
部署应用

而 ai_agent 项目重点是：

复制代码

用户输入需求
    ↓
智能体理解上下文
    ↓
检索知识
    ↓
调用工具
    ↓
完成任务

两者都使用 AI，但关注点不同。

可以对比理解：

复制代码

ai-code：
更像 AI 应用生成平台。
重点是代码生成、文件保存、部署下载、应用管理。

ai_agent：
更像 AI Agent 能力样例项目。
重点是 ChatClient、Advisor、ChatMemory、RAG、Tool Calling。

所以学习 ai_agent 项目时，不要只看接口数量，而要重点看它如何组织智能体能力。

16. 当前项目状态

README 中说明，这个项目当前更偏向"智能体能力验证 / 工程实践样例"，而不是完整业务平台。当前已经具备智能体主链路、RAG 知识增强、工具调用执行和文件式记忆扩展，但 Web 层接口较少，公开控制器主要是健康检查。后续可以继续补充对话接口、报告生成接口、RAG 检索接口、工具执行审计接口和会话管理接口。(GitHub)

这一点很重要。

也就是说，学习这个项目时不能用"完整产品"的标准去看它，而要把它看成：

复制代码

Spring AI Agent 能力练习项目

它的价值在于帮助我们理解：

复制代码

Spring AI 如何组织模型调用
Advisor 如何增强对话
ChatMemory 如何管理上下文
RAG 如何接入本地知识库
Tool Calling 如何让模型执行外部工具

17. 后续博客学习路线

基于项目结构，后续可以按照下面顺序继续学习：

复制代码

第二期：Spring AI 与 ChatClient 主链路解析
第三期：Advisor 机制与对话增强设计
第四期：多轮对话与 ChatMemory 机制
第五期：FileBasedChatMemory 文件式持久化记忆
第六期：RAG 检索增强整体流程
第七期：Query Rewrite 与关键词增强机制
第八期：向量存储 SimpleVectorStore 与 PgVector 扩展
第九期：Tool Calling 工具调用机制总览
第十期：网页搜索、网页抓取与资源下载工具
第十一期：文件操作、终端执行与 PDF 生成工具
第十二期：项目现状、测试用例与后续扩展方向

这个顺序比较符合项目的学习逻辑：

复制代码

先看主链路
再看对话增强
再看记忆
再看 RAG
再看工具调用
最后看扩展方向

18. 这个项目值得学习什么？

我认为这个项目最值得学习的不是某一个具体业务场景，而是它展示了一个 Agent 项目的基本骨架。

可以概括为五点：

复制代码

第一，用 ChatClient 统一组织模型调用。
第二，用 System Prompt 固定智能体角色。
第三，用 ChatMemory 支持多轮对话。
第四，用 RAG 接入本地知识库。
第五，用 Tool Calling 让模型具备外部执行能力。

这五点基本覆盖了一个入门级 Agent 系统的核心组成。

如果后续想做自己的 Agent 项目，比如：

复制代码

论文阅读 Agent
代码分析 Agent
网络安全分析 Agent
CTI 威胁情报 Agent
电力系统运维 Agent
个人知识库 Agent

都可以参考这个项目的基本结构。

19. 我的理解

我认为 ai_agent 项目可以理解为一个"智能体能力拼装示例"。

它不是为了展示复杂业务系统，而是为了回答一个更基础的问题：

复制代码

在 Spring Boot 项目里，如何把大模型、记忆、知识库和工具调用组织成一个 Agent？

项目中的 LoveApp 就是这个问题的核心答案。

它通过 ChatClient 连接模型，通过 System Prompt 定义角色，通过 MessageChatMemoryAdvisor 支持多轮对话，通过 QuestionAnswerAdvisor 接入 RAG，通过 ToolCallback[] 注入工具能力。

所以，这个项目最适合作为学习 Spring AI Agent 开发的起点。

20. 本期小结

本期主要对 ai_agent 项目做了整体介绍。

项目基于 Spring Boot 3 和 Spring AI 构建，当前以"恋爱咨询 / 约会规划"为垂直业务场景。它不是一个简单聊天机器人，而是一个用于验证智能体能力的工程实践项目。项目的核心能力包括多轮对话、结构化输出、RAG 检索增强、查询重写、工具调用、日志观测和会话记忆扩展。其核心入口是 LoveApp，该类封装了普通对话、结构化报告、RAG 对话和工具调用四条主要链路。

这一期可以用一句话总结：

复制代码

AI Agent 项目的核心价值，是展示如何在 Spring AI 中把模型调用、会话记忆、RAG 检索和工具调用组合成一个可扩展的智能体链路。

下一期可以继续分析：

AI Agent 项目学习笔记（二）：Spring AI 与 ChatClient 主链路解析

下一期重点分析 LoveApp 是如何通过 ChatClient 构建智能体主流程的，包括 ChatModel、ChatClient.builder()、defaultSystem()、defaultAdvisors()、prompt()、user()、call() 和 chatResponse() 的作用。