切换主题
课程设计：把 Spring AI Alibaba 学成一条工程主线
这页是整套教程的讲师备课稿。它不急着讲源码细节，而是先回答：学员学完要会什么、每章为什么这样排、案例为什么从“智能客服邮件处理助手”开始。
学完你能做什么
读完整套教程后，你应该能做到四件事：
- 能把 Spring AI Alibaba 解释成一套 Agentic AI 工程框架，而不是一个模型 SDK。
- 能从
examples/chatbot跑通最小闭环，再顺着ReactAgent -> Graph Core -> LLM Node -> Tool Node读源码。 - 能把工具调用、记忆、结构化输出、Hooks、Graph、中断恢复、多 Agent 和路由放进同一个业务案例里。
- 能判断一个真实 Spring Boot 项目应该用
ChatClient、ReactAgent、自定义StateGraph还是多智能体编排。
适合谁读
| 读者 | 建议读法 |
|---|---|
| Spring Boot 程序员 | 从第 1 章开始，先跑通 Chatbot，再读课后源码索引。 |
| 已用过大模型 API 的后端开发 | 重点看第 2、3、4、7、8、11 章，建立 Agent 工程化思路。 |
| 准备维护公司 AI 项目的人 | 重点看第 6、8、10、11、13 章，关注治理、恢复、路由和源码定位。 |
| 想做多 Agent 应用的人 | 先读第 1 到 7 章，再读第 9、10、12 章，不要一上来跳多 Agent。 |
本教程用到的来源
| 来源 | 用途 |
|---|---|
| Spring AI Alibaba 官方文档 | 校对 Quick Start、Agent、Graph、结构化输出、Studio 等概念。 |
docs/CODEX_PROJECT_CONTEXT.md | 作为本地源码阅读地图，避免每次从零扫描。 |
examples/chatbot | 建立最小可运行闭环。 |
examples/documentation | 查官方示例代码，尤其是 Agent、Graph、结构化输出和文档教程样例。 |
spring-ai-alibaba-agent-framework | 验证 ReactAgent、FlowAgent、Hooks、Interceptors、工具节点等实现。 |
spring-ai-alibaba-graph-core | 验证 StateGraph、CompiledGraph、OverAllState、中断和状态流转。 |
spring-boot-starters | 验证工程化入口、Starter、Observation、Nacos、内置节点。 |
版本提醒：版本号、依赖坐标、Starter 名称和示例入口以官方文档和本地源码为准。教程里涉及版本时，不把某一次调研看到的版本写成永久事实。
整体学习路线
贯穿案例
整套教程都围绕同一个案例慢慢加能力：智能客服邮件处理助手。
| 阶段 | 新增能力 | 对应章节 |
|---|---|---|
| 能回答 | 最小 ReactAgent | 第 1、2 章 |
| 会查资料 | 工具调用 | 第 3 章 |
| 会记上下文 | threadId 和记忆 | 第 4 章 |
| 会给结构 | 结构化输出 | 第 5 章 |
| 会守规则 | Hook / Interceptor | 第 6 章 |
| 会跑流程 | Graph Core、中断恢复 | 第 7、8 章 |
| 会分工 | 多 Agent、LLM Routing | 第 9、10 章 |
| 能上线 | 工程化入口、复杂案例、源码定位 | 第 11 到 13 章 |
教学设计矩阵
| 单元 | 学员问题 | 教学目标 | 官方/源码依据 | 案例设计 | 检查标准 |
|---|---|---|---|---|---|
| 框架地图 | 这到底是不是模型 SDK？ | 先建立 Agentic AI 应用框架心智模型 | 官方 README、examples/chatbot、ReactAgent、StateGraph | 跑通 Chatbot，再讲 App、Agent、Graph、Tool、State | 能画出一次对话数据流 |
| 最小 Agent | ReactAgent 怎么装起来？ | 会写最小 Bean 和一次调用 | ReactAgent.java、Builder.java、官方示例 | Java 学习助教 Agent | 能解释 model/instruction/call |
| 工具调用 | 模型怎么“干活”？ | 区分模型判断和工具执行 | AgentToolNode.java、Spring AI ToolCallback | 查询工单工具 | 能说出权限和审计边界 |
| 记忆线程 | 多轮上下文放哪里？ | 理解 threadId 和 checkpoint | MemorySaver、CompileConfig、OverAllState | 客户售后连续追问 | 能设计记忆保留规则 |
| 结构化输出 | 怎么让结果进程序？ | 能输出可校验字段 | 官方结构化输出文档、示例代码 | 邮件意图抽取 | 能定义字段和校验口径 |
| Hook/Interceptor | 怎么加检查站？ | 区分流程拦截和调用切面 | Agent Framework Hooks、Interceptors | 退款前人工确认 | 能选择 Hook 或 Interceptor |
| Graph Core | 复杂流程怎么白盒化？ | 会用节点、边、状态讲流程 | StateGraph.java、CompiledGraph.java | 分类、检索、草拟、审核 | 能说明节点状态如何流转 |
| 中断恢复 | 工作流怎么暂停再继续？ | 理解人工介入和恢复 | interruptBefore/After、Saver | 草拟回复后人工确认 | 能说清中断不是异常 |
| 多 Agent / Routing | 多角色怎么分工？ | 会选择顺序、并行、路由、循环 | FlowAgent、LlmRoutingAgent | 售前/售后/技术支持分诊 | 能设计兜底路由 |
| 工程化收尾 | 怎么放进真实 Spring Boot？ | 会考虑配置、日志、异常、观测 | Starters、Studio、Observation | REST 接口封装 Agent | 能列出上线检查清单 |
练习路线
每章练习都覆盖三类能力：
| 类型 | 训练什么 | 例子 |
|---|---|---|
| 概念题 | 能不能讲明白 | 用自己的话解释 ReactAgent 和 Graph Core 的区别。 |
| 改造题 | 能不能动手改 | 给最小 Agent 增加工具、记忆或结构化输出。 |
| 排错题 | 能不能定位问题 | 工具没有被调用时，沿 AgentLlmNode -> AgentToolNode -> messages 排查。 |
教程审计口径
这套教程后续每次改写都按下面口径检查：
- 是否先让学员知道“学完能做什么”？
- 是否先跑通最小闭环，再讲源码？
- 每章是否有讲师案例，而不是只有概念解释？
- 关键结论是否能追到官方文档或源码路径？
- 练习题是否有参考答案？
- 是否避免暴露本机绝对路径到公开站点？
- 如果同步到 VitePress，是否执行
npm.cmd run docs:sync和npm.cmd run docs:build？
来源
- Spring AI Alibaba 官方文档：https://java2ai.com/
- Spring AI Alibaba 官方仓库：https://github.com/alibaba/spring-ai-alibaba
- 本地源码索引：
docs/CODEX_PROJECT_CONTEXT.md - 本教程原稿目录：
skills/docs/spring-ai-alibaba