简介

      spring ai alibaba是java的ai agent框架，本系列将深入剖析 Spring AI Alibaba 的源码实现与核心原理，不仅指导agent的开发，更为了改造框架，增加新特性

系列内容：

系列(一) 架构  完成
系列(二) 模型，chat模型，chat client，advisor组件，提示词，消息，结构化转换，chat记忆
系列(三) 外部调用 工具/MCP/skills  
系列(四) graph：StateGraph，CompiledGraph；图执行，节点和边
系列(五) agent，ReactAgent；钩子和拦截器，上下文工程
系列(六) RAG 知识库，包括文档读取，分块，嵌入，向量store；检索增强生成  
系列(七) 多agent，FlowAgent，a2a agent，handoffs模式，toolcalling模式；agent 大规模集群
agent管理运行平台，spring ai alibaba admin，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组件或特性，是本文分析的目录

model  大模型的封装，模型包括Chat，嵌入，audio，image等类型，其中chat模型包括，advisor组件，提示词，记忆等

agent/graph  agent和图紧密相关，可以认为agent是一种既定的”图”形，开发人员可以使用graph低层api直接构建graph，也可以使用agent获得既定的图形，简化和加快agent的开发

外部调用(calling)  调用可能是agent发展演变最快的部分，最初的工具，到mcp，最近的CLI，skills

RAG 

MAS  

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  model拦截器，调用大模型，生成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

系列(二) 模型，chat模型

系列(三) 图，agent