第 11 章：工程化入口，让 Agent 住进 Spring Boot 项目

前面我们学的是核心能力。这章回到工程现场：一个框架能不能进项目，不只看 API 好不好用，还要看能不能自动配置、能不能调试、能不能观测、能不能和外部系统集成。

本章边界

本章讲 Spring Boot 项目里常见的接入口：Studio、Starters、A2A、Nacos、Observation。Admin 平台部署不深挖，Nacos/A2A 也不是入门示例的必需条件。

1. 生活类比：样板间和真实交付

Demo 像样板间，灯光好、家具齐、没人住。工程化像真实交付：水电、门禁、监控、维修通道都要有。

Spring AI Alibaba 的工程化入口可以这样理解：

工程入口	像什么	解决什么
Studio	调试仪表盘	看 Agent、Graph 和执行过程
Starters	水电预埋	自动配置 Bean，减少手工装配
A2A	对外服务窗口	让 Agent 按协议被外部调用
Nacos	配置中心和服务登记处	动态配置、服务发现、Agent 注册
Observation	监控探头	记录节点、边、模型、工具的运行情况

2. 最小工程路径

入门不要一上来就搭 Nacos、A2A、Admin。推荐顺序：

先把 Chatbot 跑通 -> 接 Studio 看 Agent -> 接 Observation 看指标 -> 再考虑 A2A / Nacos / Admin

为什么？因为你先要确认框架主链路是通的：模型能调、Agent 能执行、Graph 能跑。否则一上来就把配置中心、服务发现、部署平台都接进来，最后你会分不清是框架没学会，还是环境没搭好。

3. 工程化地图

这张图告诉你：工程化不是一个点，而是一组入口。Studio 负责看得见，Starter 负责装得上，Observation 负责查得出，A2A/Nacos 负责接得出去和管得起来。

4. 运行前置矩阵

能力	入门是否必须	需要什么
Chatbot + Studio UI	建议必须跑	JDK 17、模型 API Key
Graph Observation	非必需，但生产建议接	Micrometer / MeterRegistry、指标采集链路
A2A Nacos	入门不必跑	Nacos 服务、A2A 配置、可被注册的 Agent
Config Nacos	入门不必跑	Nacos 配置中心、模型 / Prompt / MCP 配置
Admin 平台	本教程不展开	后端服务、前端构建、数据库和部署资源

这张表的作用是给你降噪：先跑最小闭环，再接工程设施。

5. 新手容易误解什么

误解一：Starter 是神秘魔法。

Starter 仍然是 Spring Boot 自动配置。读它时就按 Spring Boot 老套路：配置属性、条件装配、Bean 创建。

误解二：Studio 是 Agent 的核心执行引擎。

Studio 是观察和操作入口，底层仍然是 Agent、Graph、Loader。

误解三：A2A 和 Nacos 是入门必需。

不是。它们属于更靠工程集成的一层。先把单体示例跑通，再接这些设施。

6. 本章小结

工程化入口的读法：

AutoConfiguration -> Bean -> Controller / Executor -> Agent / Graph

下一章看几个复杂案例，把前面所有零件拼成真实机器。

7. 练习题

1. 给自己的项目列一张运行前置表：模型 Key、Nacos、DB、Redis、外部服务、网络权限分别是否必需。
2. 设计一组 Agent 运行日志字段：threadId、agentName、nodeName、toolName、latency、error。
3. 解释为什么生产排查不能只看最终回答，还要看模型、工具、节点和边的过程数据。

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

你想验证的结论	源码锚点
Studio 自动配置入口	spring-ai-alibaba-studio/src/main/java/com/alibaba/cloud/ai/agent/studio/SaaStudioWebModuleAutoConfiguration.java，类 SaaStudioWebModuleAutoConfiguration，构造方法 SaaStudioWebModuleAutoConfiguration()
Studio 如何查询可用 Agent	spring-ai-alibaba-studio/src/main/java/com/alibaba/cloud/ai/agent/studio/controller/AgentController.java，类 AgentController，方法 listApps()
Studio 如何执行 Graph	spring-ai-alibaba-studio/src/main/java/com/alibaba/cloud/ai/agent/studio/controller/GraphExecutionController.java，类 GraphExecutionController，方法 graphRunSse(...)、executeGraph(...)
如何从 Spring 上下文扫描 Agent	spring-ai-alibaba-studio/src/main/java/com/alibaba/cloud/ai/agent/studio/loader/ContextScanningAgentLoader.java，类 ContextScanningAgentLoader，方法 loadAgentMap()
A2A 自动配置和执行入口	spring-boot-starters/spring-ai-alibaba-starter-a2a-nacos/src/main/java/com/alibaba/cloud/ai/a2a/autoconfigure/server/A2aServerAutoConfiguration.java，方法 a2aRouterFunction(...)；GraphAgentExecutor.java，方法 execute(...)、cancel(...)、getRunnableConfig(...)
Nacos 配置如何构建 Agent	spring-boot-starters/spring-ai-alibaba-starter-config-nacos/src/main/java/com/alibaba/cloud/ai/agent/nacos/NacosReactAgentBuilder.java，类 NacosReactAgentBuilder，方法 nacosOptions(...)、build()、registerModelListener(...)
Graph 观测如何注册	spring-boot-starters/spring-ai-alibaba-starter-graph-observation/src/main/java/com/alibaba/cloud/ai/autoconfigure/graph/GraphObservationAutoConfiguration.java，类 GraphObservationAutoConfiguration，方法 graphObservationHandler(...)、graphNodeObservationHandler(...)、graphEdgeObservationHandler(...)