第 1 章：先跑起来，先把地图装进脑子里

这一章不要求你打开 IDE。你先把 Spring AI Alibaba 当成一套“智能应用流水线”来理解：用户一句话进来，框架把它交给模型判断，必要时调用工具，过程中保存状态，最后把结果交回 Spring Boot 应用。

本章边界

本章只回答三个问题：它是什么、最小示例怎么跑、整体流程怎么转起来。工具安全、记忆持久化、多智能体编排和生产治理先放到后面章节。

1. 生活类比：别先拆发动机，先学会看仪表盘

第一次学车时，教练不会让你先拆发动机。他会先告诉你方向盘、油门、刹车、仪表盘分别干什么。你先能把车开出停车位，再慢慢理解发动机、变速箱和传动系统。

Spring AI Alibaba 也一样。先别急着背一堆类名，你只需要先记住五个角色：

角色	像什么	负责什么
Spring Boot App	驾驶舱	接收请求、装配 Bean、暴露接口
ChatModel / ChatClient	发动机	和大模型供应商对话
ReactAgent	自动驾驶助理	组织提示词、模型、工具、记忆
Graph Core	路线规划器	决定节点顺序、条件分支和状态流转
Tool / Memory / Studio	工具箱和仪表盘	做外部动作、保存上下文、观察运行过程

一句话定位：

Spring AI Alibaba 不是单纯的模型 SDK，而是把模型、工具、状态和工程入口组织起来的 Agentic AI 应用框架。

2. 先跑一个最小 Chatbot

本章推荐先跑官方 Chatbot 示例。它不是最“短”的示例，但它最适合建立全局感觉：有模型、有 Agent、有工具、有记忆，还有一个能点开的 Studio UI。

你需要准备：

• JDK 17+
• 一个可用的大模型 API Key

如果使用 DashScope，可以先在终端里放一个环境变量：

$env:AI_DASHSCOPE_API_KEY="你的 API Key"

然后在 Spring AI Alibaba 仓库根目录运行：

.\mvnw.cmd -f examples/chatbot/pom.xml spring-boot:run

启动成功后，浏览器打开：

http://localhost:8080/chatui/index.html

先不要急着研究每个 Bean。你只要确认两件事：

1. 页面能打开，说明 Spring Boot 应用和 Studio UI 已经起来了。
2. 能发起一次对话，说明模型、Agent 和基础调用链已经接通了。

3. 心智模型：一次对话到底发生了什么

你可以把一次对话想成餐厅点餐：

1. 用户点菜：用户输入问题。
2. 服务员接单：Spring Boot 接收请求。
3. 厨师判断：模型决定直接回答，还是需要查工具。
4. 后厨出手：工具节点真正执行工具。
5. 账本记录：状态和记忆保存这次过程。
6. 服务员上菜：Agent 把最终回答返回给用户。

对应到框架，就是这张图：

这张图比类名重要。类名会变，路径会变，但“模型判断、工具执行、状态流转、最终返回”这条线是你读后面所有章节的主绳。

4. 第一个工程判断：为什么不是直接调模型

如果只是问“Java 里怎么调大模型”，直接用 ChatClient 也能完成。但 Agent 应用多了三件麻烦事：

麻烦事	直接调模型的问题	Agent 框架解决方式
工具调用	模型说要用工具，谁执行、谁记日志、谁处理失败	统一交给工具节点
多轮状态	上下文、工具结果、结构化字段散在各处	统一放进运行状态
流程控制	什么时候继续、什么时候结束、什么时候人工介入	交给 Graph 编排

所以你可以这样理解：

ChatClient 解决“问模型一句话”
ReactAgent 解决“让模型参与一个可执行流程”
Graph Core 解决“这个流程怎么走、状态怎么传”

这就是本章最重要的抽象。

5. 新手容易误解什么

误解一：Spring AI Alibaba 就是模型 SDK。

它当然能接模型，但重点不在“发请求”，而在“把模型放进工程流程里”。模型只是发动机，Agent 和 Graph 才让车能开上路。

误解二：ReactAgent 只是一个 Prompt 模板。

不是。Prompt 只是它的一部分。ReactAgent 还会组织模型节点、工具节点、状态和条件循环。它更像一个预装好的 ReAct 流程。

误解三：工具是模型自己执行的。

模型只负责说“我想调用这个工具”。真正执行工具的是框架侧的工具节点。这个区分非常重要，因为权限、超时、审计、失败重试都发生在框架侧。

6. 本章小结

本章你只要记住一张心智地图：

先把这张图装进脑子里。后面讲工具、记忆、结构化输出、多 Agent，其实都是在这张图上加零件。

7. 练习题

1. 不看源码，用自己的话解释：ChatClient、ReactAgent、Graph Core 分别解决什么问题。
2. 把一次 Agent 对话类比成你熟悉的业务流程，比如工单流转、订单审批或客服派单，画出“谁判断、谁执行、谁保存状态”。
3. 跑通 Chatbot 后，尝试只问一个不需要工具的问题，再问一个可能需要工具的问题，观察回答风格有什么不同。

课后源码索引：想验证实现时再打开

你想验证的结论	源码锚点
Chatbot 示例如何启动	examples/chatbot/src/main/java/com/alibaba/cloud/ai/examples/chatbot/ChatbotApplication.java，类 ChatbotApplication，方法 main(...)、applicationReadyEventListener(...)
Chatbot 如何装配 Agent	examples/chatbot/src/main/java/com/alibaba/cloud/ai/examples/chatbot/ChatbotAgent.java，类 ChatbotAgent，方法 chatbotReactAgent(...)、memorySaver()、executeShellCommand()、executePythonCode()、viewTextFile()
ReactAgent 如何创建图	spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/ReactAgent.java，类 ReactAgent，方法 builder()、call(...)、initGraph()、makeModelToTools(...)
Builder 如何把配置变成节点	spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/DefaultBuilder.java，类 DefaultBuilder，方法 build()、gatherLocalTools()
模型节点如何发起模型调用	spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/node/AgentLlmNode.java，类 AgentLlmNode，方法 apply(...)、buildChatClientRequestSpec(...)
工具节点如何执行 tool call	spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/node/AgentToolNode.java，类 AgentToolNode，方法 apply(...)、executeToolCallsSequential(...)、executeToolCallsParallel(...)
Graph Core 的基础执行结构	spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/StateGraph.java，类 StateGraph，方法 addNode(...)、addEdge(...)、addConditionalEdges(...)、compile(...)