Spring AI Alibaba 项目源码学习（一）-整体介绍

Spring AI Alibaba 项目目录结构说明

请关注微信公众号：阿呆-bot

项目概述

Spring AI Alibaba 是一个多模块 Maven 项目，采用分层架构设计，从底层到上层依次为：Graph 核心运行时、Agent 框架、Studio 应用和 Spring Boot Starters。项目遵循模块化设计原则，每个模块都有明确的职责边界。

目录结构说明

第一层模块

项目根目录下包含以下主要模块：

spring-ai-alibaba/
├── spring-ai-alibaba-bom/              # BOM 模块
├── spring-ai-alibaba-graph-core/       # Graph 核心运行时
├── spring-ai-alibaba-agent-framework/ # Agent 框架
├── spring-ai-alibaba-studio/           # Studio 应用
├── spring-boot-starters/               # Spring Boot Starters
│   ├── spring-ai-alibaba-starter-a2a-nacos/
│   └── spring-ai-alibaba-starter-config-nacos/
├── tools/                              # 工具目录
└── docs/                               # 文档目录

模块详细说明

1. spring-ai-alibaba-bom

职责：Bill of Materials (BOM) 模块，统一管理所有 Spring AI Alibaba 模块的依赖版本。

关键特性：

提供依赖版本管理
简化子模块的依赖配置
确保版本一致性

使用方式：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-bom</artifactId>
            <version>1.1.0.0-M4</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

2. spring-ai-alibaba-graph-core

职责：Graph 核心运行时，提供底层的工作流和多 Agent 编排框架。这是整个框架的基础层，提供状态图、节点、边等核心抽象。

关键入口点：

StateGraph：状态图定义类，用于构建工作流图

public class StateGraph {

	/**
	 * Constant representing the END of the graph.
	 */
	public static final String END = "__END__";

	/**
	 * Constant representing the START of the graph.
	 */
	public static final String START = "__START__";

	/**
	 * Constant representing the ERROR of the graph.
	 */
	public static final String ERROR = "__ERROR__";

	/**
	 * Constant representing the NODE_BEFORE of the graph.
	 */
	public static final String NODE_BEFORE = "__NODE_BEFORE__";

GraphRunner：图执行引擎，负责执行编译后的图

public class GraphRunner {

	private final CompiledGraph compiledGraph;

	private final RunnableConfig config;

	private final AtomicReference<Object> resultValue = new AtomicReference<>();

	// Handler for main execution flow - demonstrates encapsulation
	private final MainGraphExecutor mainGraphExecutor;

	public GraphRunner(CompiledGraph compiledGraph, RunnableConfig config) {
		this.compiledGraph = compiledGraph;
		this.config = config;
		// Initialize the main execution handler - demonstrates encapsulation
		this.mainGraphExecutor = new MainGraphExecutor();
	}

	public Flux<GraphResponse<NodeOutput>> run(OverAllState initialState) {

CompiledGraph：编译后的可执行图
OverAllState：全局状态对象，用于在节点间传递数据

核心概念：

Node：工作流中的节点，封装特定操作或模型调用
Edge：节点间的边，表示状态转换
OverAllState：全局状态，携带整个流程的共享数据

3. spring-ai-alibaba-agent-framework

职责：Agent 框架，基于 Graph 核心运行时构建的高级 Agent 开发框架。提供 ReactAgent、SequentialAgent、ParallelAgent 等预构建的 Agent 类型，简化 Agent 开发。

关键入口点：

ReactAgent：核心 Agent 类型，实现 ReAct（Reasoning + Acting）范式

public class ReactAgent extends BaseAgent {
	private static final int DEFAULT_MAX_ITERATIONS = 10;

	private final AgentLlmNode llmNode;

	private final AgentToolNode toolNode;

	private CompiledGraph compiledGraph;

	private List<Hook> hooks;

	private List<ModelInterceptor> modelInterceptors;

	private List<ToolInterceptor> toolInterceptors;

	private int maxIterations;

	private int iterations = 0;

	private String instruction;

	private Function<OverAllState, Boolean> shouldContinueFunc;

	public ReactAgent(AgentLlmNode llmNode, AgentToolNode toolNode, CompileConfig compileConfig, Builder builder) throws GraphStateException {
		super(builder.name, builder.description, builder.includeContents, builder.returnReasoningContents, builder.outputKey, builder.outputKeyStrategy);
		this.instruction = builder.instruction;
		this.llmNode = llmNode;
		this.toolNode = toolNode;
		this.compileConfig = compileConfig;
		this.shouldContinueFunc = builder.shouldContinueFunc;
		this.hooks = builder.hooks;
		this.modelInterceptors = builder.modelInterceptors;
		this.toolInterceptors = builder.toolInterceptors;
		this.includeContents = builder.includeContents;
		this.inputSchema = builder.inputSchema;
		this.inputType = builder.inputType;
		this.outputSchema = builder.outputSchema;
		this.outputType = builder.outputType;
		this.maxIterations = builder.maxIterations <= 0 ? DEFAULT_MAX_ITERATIONS : builder.maxIterations;

		// Set interceptors to nodes
		if (this.modelInterceptors != null && !this.modelInterceptors.isEmpty()) {
			this.llmNode.setModelInterceptors(this.modelInterceptors);
		}
		if (this.toolInterceptors != null && !this.toolInterceptors.isEmpty()) {
			this.toolNode.setToolInterceptors(this.toolInterceptors);
		}
	}

	public static com.alibaba.cloud.ai.graph.agent.Builder builder() {
		return new DefaultAgentBuilderFactory().builder();
	}

SequentialAgent：顺序执行多个子 Agent 的工作流 Agent
ParallelAgent：并行执行多个子 Agent 的工作流 Agent
LlmRoutingAgent：基于 LLM 进行路由决策的工作流 Agent
LoopAgent：循环执行的工作流 Agent

核心特性：

Context Engineering：内置的上下文工程最佳实践
Human In The Loop：人在回路支持
Tool 调用：支持工具调用和 MCP 协议
Hook 机制：支持在 Agent 执行的不同阶段插入自定义逻辑

4. spring-ai-alibaba-studio

职责：Studio 应用，提供可视化的 Agent 开发和管理界面。基于 Spring Boot 和 Next.js 构建，包含后端 API 和前端 Web UI。

关键特性：

Agent 可视化界面
运行时追踪和监控
Agent 配置管理
基于 CopilotKit 的 UI 组件

技术栈：

后端：Spring Boot + Spring AI Alibaba Agent Framework
前端：Next.js + TypeScript + CopilotKit

5. spring-boot-starters

职责：Spring Boot Starters，提供与 Spring Boot 的集成和自动配置。

5.1 spring-ai-alibaba-starter-a2a-nacos

职责：提供 Agent-to-Agent (A2A) 通信的 Nacos 集成，支持分布式 Agent 协调和协作。

关键特性：

基于 Nacos 的服务发现
A2A 通信协议支持
分布式 Agent 编排

5.2 spring-ai-alibaba-starter-config-nacos

职责：提供基于 Nacos 的动态配置管理，支持 Agent 配置的动态更新。

关键特性：

Nacos 配置中心集成
动态配置更新
配置热更新

模块依赖关系

以下 PlantUML 图展示了模块间的依赖关系：

依赖说明：

graph-core 是基础层，不依赖其他 Spring AI Alibaba 模块
agent-framework 依赖 graph-core，提供高级 Agent 抽象
studio 依赖 agent-framework，提供可视化界面
starters 依赖 agent-framework，提供 Spring Boot 集成
所有模块都通过 bom 统一管理依赖版本

工具和辅助目录

tools/

工具目录包含项目开发和维护所需的工具：

ci-config/：CI/CD 配置文件
github-actions/：GitHub Actions 工作流
linter/：代码检查工具配置（checkstyle、markdownlint、yamllint 等）
make/：Makefile 辅助脚本
scripts/：Python 脚本（中文内容检查、换行检查等）
src/checkstyle/：Checkstyle 配置文件

项目构建

项目使用 Maven 进行构建，主要命令：

# 编译项目
mvn clean compile

# 运行测试
mvn test

# 打包项目
mvn clean package

# 代码格式化
mvn spring-javaformat:apply

# 代码检查
mvn checkstyle:check

wasp

自娱自乐

Spring AI Alibaba 项目源码学习（一）-整体介绍

Spring AI Alibaba 项目目录结构说明

项目概述

目录结构说明

第一层模块

模块详细说明

1. spring-ai-alibaba-bom

2. spring-ai-alibaba-graph-core

3. spring-ai-alibaba-agent-framework

4. spring-ai-alibaba-studio

5. spring-boot-starters

5.1 spring-ai-alibaba-starter-a2a-nacos

5.2 spring-ai-alibaba-starter-config-nacos

模块依赖关系

工具和辅助目录

tools/

项目构建

相关资源

公告