从零开始做一个 AI Agent以 Java Web RAG 学习助手为例本文是一套面向技术博客专栏的完整教程。它不是只讲概念而是以当前项目为真实案例从一个最小后端 API 出发逐步扩展到课程资料知识库、RAG 问答、轻量级 Agent Harness、工具注册表、执行 Trace、答案校验、学习记忆和前端工作台。用户可以上传课程课件、实验指导书、代码文件和配置文件。系统会解析资料、切块、建立检索索引用户提交学习任务后Agent 会判断任务类型、规划步骤、调用工具、生成回答、校验引用并把执行过程展示给前端。项目中的相关注解dataclass(frozenTrue)dataclass(frozenTrue)是 Python 里的一个装饰器用来快速定义“数据对象”并且让这个对象创建后不能再被修改。拆开看fromdataclassesimportdataclassdataclass(frozenTrue)classRetrievedChunk:chunk_id:intdocument_id:intcontent:strscore:float等价于Python 自动帮你生成__init__、__repr__、__eq__等方法。你就可以这样创建对象chunkRetrievedChunk(chunk_id1,document_id10,contentLoginServlet 负责处理登录请求,score0.8,)不用自己手写classRetrievedChunk:def__init__(self,chunk_id,document_id,content,score):self.chunk_idchunk_id self.document_iddocument_id self.contentcontent self.scorescorefrozenTrue的意思是对象创建之后字段不能改。例如chunk.score0.9会报错dataclasses.FrozenInstanceError所以dataclass(frozenTrue)可以理解成定义一个轻量级数据结构并且让它不可变在你当前项目里dataclass(frozenTrue)classRetrievedChunk:chunk_id:intdocument_id:intcontent:strsource_title:str|Nonesource_path:str|Nonesource_page:int|Nonelanguage:str|Nonescore:float它表示“检索出来的资料片段”。加frozenTrue的好处是防止后续代码误改检索结果让数据对象更可靠表示这个对象只是一个结果载体不应该被业务逻辑继续修改一句话dataclass(frozenTrue) 自动生成数据类常用方法 创建后禁止修改字段。本系列总目录1. 项目总览从普通问答到课程学习 Agent2. 技术栈和工程结构FastAPI、Vue、SQLite、RAG、Agent Harness3. 后端基础设施配置、数据库、模型和 Schema4. 资料上传文件存储、文档记录和重建索引5. 文档解析PDF、Word、PPT、Markdown、代码文件如何进入系统6. 文本切块chunk、metadata、语义类型和 embedding 状态7. 检索系统关键词检索、向量检索、query rewrite 和 rerank8. LLM 与 Embedding Providerstub、OpenAI-compatible API 和本地模型接入9. Chat 问答入口兼容普通问答同时接入 Agent 主链路10. Agent Harness一次 Agent run 的生命周期11. Planner、Executor 与 Tool RegistryAgent 如何规划和调用工具12. Agent 校验、安全边界与资料不足处理13. Agent 记忆短期上下文、长期学习画像和推荐下一步14. 前端工作台资料管理、Agent 任务、Trace、历史和健康状态15. 测试、局限和演进从教学项目走向生产级 Agent SaaS16. 技术细节复现17. 附录一SQLite与SQLAlchemy18. 附录二接入大模型19. 附录三配置ollama本地大模型/deepseek线上大模型20. 附录四Agent Harness API详解21. 附录五Agent 工具注册表详解22. 附录六工程化 Agent思维23. 附录七安装embedding模型详解24. 附录八本项目为啥不用LangChain25. 附录九UI界面详解26. 附录十整体核心流程详解27. 附录十一项目中的相关注解28. 附录十二手把手带你运行项目