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中定义了一个LoveReportrecord并在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。它适合快速实现多轮对话但有一个问题服务重启后内存中的历史对话会丢失。因此项目还提供了一个基于文件系统的持久化实现FileBasedChatMemoryREADME 中说明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.javaREADME 中也把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 普通对话doChatdoChat是基础对话方法。它接收message用户输入 chatId会话 ID然后通过ChatClient调用模型并通过 Advisor 参数传入ChatMemory.CONVERSATION_ID从而支持多轮对话记忆。(GitHub)流程可以理解为用户输入 message ↓ 传入 chatId ↓ ChatClient 调用模型 ↓ MessageChatMemoryAdvisor 处理上下文 ↓ 返回模型回复13.2 结构化输出doChatWithReportdoChatWithReport用于生成结构化恋爱报告。它不是返回普通字符串而是返回LoveReport其中包含title suggestions源码中通过.entity(LoveReport.class)把模型输出转换成 Java 对象。(GitHub)这说明 Spring AI 可以把模型响应进一步映射成业务对象而不是只能处理文本。13.3 RAG 对话doChatWithRagdoChatWithRag用于检索增强对话。它会先调用queryRewriter.doQueryRewrite(message)对用户问题进行查询改写然后再通过QuestionAnswerAdvisor(loveAppVectorStore)接入本地向量知识库进行检索增强。(GitHub)流程可以理解为用户原始问题 ↓ Query Rewrite ↓ 改写后的问题 ↓ 向量库检索相关文档 ↓ 把检索结果交给模型 ↓ 模型生成回答13.4 工具调用doChatWithToolsdoChatWithTools用于支持工具调用。它通过.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()的作用。