简介
spring ai alibaba是java的ai agent框架，本系列将深入剖析 Spring AI Alibaba 的源码实现与核心原理，不仅指导agent的开发，更为了改造框架，增加新特性
系列内容：
系列( 一) 架构 本文<<
系列( 二) agent&graph，分析ReactAgent/FlowAgent/a2a agent；StateGraph，CompiledGraph
系列( **三)**模型，钩子和拦截器；消息/结构化输出
系列( **四)**上下文工程，记忆
系列( 五) 调用 工具/MCP/skills/CLI
系列( 六) RAG
系列( 七) 可观测和评估
系列(八)多agent
工作流/agentic
系列(九) agent产品级示例解释 DataAgent
热点：agent发布，列表，提示词管理，评估，观测
关键词
Agent ReActAgent/FlowAgent
pipeline/agentic
flow/graph
缩写
spring ai缩写sa
spring ai alibaba 本文缩写saa
参考资料
https://java2ai.com/docs/overview spring ai alibaba官网文档
逻辑架构
上图是saa的逻辑架构图, 展示了 Spring AI Alibaba的整体架构层次，体现了"以 ReactAgent 为核心、Graph 为运行时基座"的设计。整个系统可划分为四个主要层级：
- 用户角色层
业务人员： admin 提示词配置，观测，评估
开发人员： studio 提供chatui
- 核心框架层（agent framework + graph）
agent framework：面向开发者的核心 API 层，提供高阶图形范式
graph-core：作为底层运行时引擎，承担工作流编排与状态管理职责：。
starter：自动配置。
- spring ai扩展
扩展体系，覆盖 AI 应用关键能力域
- Spring AI 生态
位于最底层，saa建立在spring ai生态上，代表框架所依赖的通用 AI 能力模块
组件视图
上图是saa原理源码分析场景视图，每个包对应着saa/sa组件或特性，是本文分析的目录
agent/graph agent和图紧密相关，可以认为agent是一种既定的"图"形，开发人员可以使用graph低层api直接构建graph，也可以使用agent，获得既定的图形
model sa对大模型的封装，模型包括Chat，嵌入，audio，image等类型
上下文工程/记忆(memory)
调用(calling) calling可能是agent发展演变最快的部分，最初的工具，到mcp，最近的CLI，skills
钩子和拦截器 saa的组件，钩子和拦截器不只是给用户嵌入逻辑，负责saa很多核心业务，是很重要的组件
评估 saa的模型评估不是基于sa的评估，而是自己的一套体系，构建了一个 数据集 -> 评估器 -> 实验 -> 报告的评估闭环
可观测 大模型自主性高，功能强，检测
消息/结构化输出
RAG
MAS 多个agent协同工作，每个agent有清晰而独立的智能
studio 简易的agent管理工具，嵌入到agent，带有agent面板，列表agent；提供chat界面，用于调试agent，是开发agent的便利工具
admin 作为管理台，有几个重量级的功能，agent的发布和列表，提示词管理，评估和数据集，观测值得分析
开发架构
本章以saa的agent示例DeepResearch分析saa的开发架构。
DeepResearch 分析用户输入，给出格式化研究报告。DeepResearch 是ReactAgent ，遵循思考，行动( 工具/MCP 调用) ，观测的循环迭代。
上图是DeepResearch 启动，agent内嵌了studio组件，打开http://localhost:8080/chatui/index.html，可看到agent面板，点击agent打开chatui，可与agent交互
关于MCP服务
示例使用mcp.jina.ai MCP 服务器，外部资料搜索的工具，可改为魔搭的bing搜索mcp服务
源码解释
本节解释agent源码，下图是类图，类互动图，蓝色类是DeepResearch，浅绿色是studio，橙色是其他包
DeepResearch是spring boot应用
AgentStaticLoader 标注@Component，spring boot扫描实例化，AgentStaticLoader负责new DeepResearchAgent，也为控制器服务，获取agent列表
DeepResearchAgent 虽然名字带agent，但不是真正的agent，没有继承Agent类，DeepResearchAgent负责构建agent，包括agent依赖的组件，model，hook和拦截器等(图上只展示部分的hook和拦截器)
DeepRearch 是真正的agent，是主agent，引用两个子agent
research-agent 负责搜集资料
critique-agent 负责评审生成的研究报告
ToolCallbackProvider 工 具调用提供者，本实例是MCP封装为工具，MCP将在系列 -" **调用"**分析
下面介绍几个实例用到的**++hook++** ++和拦截器++ ，++hook++ **++和拦截器++**在agent框架是关键的组件，提供核心工具，如FilesystemInterceptor；推理规划，如TodoListInterceptor；维护上下文，如，SummarizationHook，hook和拦截器不仅仅给用户扩展，更是agent框架的提供核心功能
TodoListInterceptor 思考，生成todo清单
FilesystemInterceptor 提供文件系统工具，提供`ls`, `read_file`, `write_file`, `edit_file`等文件操作，本实例，todo清单和生成的研究报告都写入文件
SubAgentInterceptor构建子agent，包装成工具
studio 侧
studio是内置的web服务，主要功能是列表agent，与agent对话(chatui)
SaaStudioWebModuleAutoConfiguration studio包声明的自动配置类，spring boot调起，studio由此启动，同时，该类声明了@ComponentScan，扫描studio范围的spring对象
StudioLoaderAutoConfiguration 这个类实例化ContextScanningAgentLoader
ContextScanningAgentLoader 负责扫描上下文，使用ApplicationContext获取agent实例，但实例方法声明了@ConditionalOnMissingBean(AgentLoader.class)，在DeepResearchAgent已经声明了AgentStaticLoader，ContextScanningAgentLoader没有实例化，设计有点奇怪，最初以为是扫描AgentLoader，然后获取agent bean
AgentController/ExecutionController 两个处理web请求的控制器，列表agent，依赖AgentStaticLoader；执行agent
**总结：**agent的开发，包括model，工具(tool&mcp)，钩子和拦截器，agent可以引用其他agent完成指定的任务，本实例还引用studio，提供agent的列表页面，对话。agent loader机制构建和初始Agent。
最后，还有最重要的角色未提及，上下文工程 ，大模型正确的工作关键是提示词，将在**++系列++** ++-++ **++上下文工程++**分析
运行
本节观测一下agent运行情况
agent首先todolist出任务规划，规划出6个任务
research agent利用搜索工具获取资料，返回主agent
critique-agent评估，返回主agent
主agent出报告，形成思考-工具调用(搜索)-评估的迭代闭环，最后生成研究报告
NEXT
系列( 二) agent&graph