Spring AI Alibaba：智能Agent开发实战指南

Spring AI Alibaba 学习使用文档

目录

• 1. 项目概述
• 2. 核心架构
• 3. 快速开始
• 4. 核心概念
• 5. Agent Framework 使用指南
• 6. Graph Core 使用指南
• 7. 高级特性
• 8. 最佳实践
• 9. 常见问题
• 10. 参考资料

1. 项目概述

1.1 什么是 Spring AI Alibaba

Spring AI Alibaba 是一个生产就绪的框架，用于构建 Agentic、Workflow 和多 Agent 应用。该框架基于 ReactAgent 设计理念，使开发者能够构建具有自动上下文工程和**人在回路（Human In The Loop）**交互能力的智能 Agent。

1.2 核心特性

• ReactAgent: 基于 ReAct（Reasoning + Acting）范式的智能 Agent，支持推理和行动能力
• 多 Agent 编排: 内置 SequentialAgent、ParallelAgent、LlmRoutingAgent、LoopAgent 等模式
• 上下文工程: 内置最佳实践策略，包括人在回路、上下文压缩、上下文编辑、模型和工具调用限制、工具重试、规划、动态工具选择等
• 基于 Graph 的工作流: 支持条件路由、嵌套图、并行执行和状态管理，可导出为 PlantUML 和 Mermaid 格式
• A2A 支持: Agent-to-Agent 通信支持，集成 Nacos，实现分布式 Agent 协调和协作
• 丰富的模型、工具和 MCP 支持: 支持多种 LLM 提供商（DashScope、OpenAI 等）、工具调用和模型上下文协议（MCP）

1.3 项目结构

Spring AI Alibaba 采用多模块 Maven 项目结构：

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/
│ └── spring-ai-alibaba-starter-graph-observation/
└── examples/ # 示例代码
├── chatbot/ # ChatBot 示例
├── deepresearch/ # DeepResearch 示例
└── documentation/ # 文档示例

1.4 技术栈要求

• JDK: 17 或更高版本
• Spring Boot: 3.4.8 或更高版本
• Spring AI: 1.1.0-M4 或更高版本
• Maven: 3.6+ 或 Gradle 7.0+

2. 核心架构

2.1 架构图

Spring AI Alibaba 采用分层架构设计：

┌─────────────────────────────────────────────────┐
│ Agent Framework (高级抽象层) │
│ ReactAgent, SequentialAgent, ParallelAgent │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Graph Core (工作流运行时) │
│ StateGraph, Node, Edge, OverAllState │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Spring AI (基础抽象层) │
│ ChatModel, Tool, Message, MCP │
└─────────────────────────────────────────────────┘

2.2 核心组件

2.2.1 Agent Framework

Agent Framework 是高级抽象层，提供：

• ReactAgent: 单 Agent 实现，支持 ReAct 循环
• FlowAgent: 多 Agent 编排基类
  • SequentialAgent: 顺序执行多个 Agent
  • ParallelAgent: 并行执行多个 Agent
  • LlmRoutingAgent: 基于 LLM 的路由 Agent
  • LoopAgent: 循环执行 Agent

2.2.2 Graph Core

Graph Core 是底层工作流运行时，提供：

• StateGraph: 状态图定义，用于定义节点和边
• Node: 节点，封装特定操作或模型调用
• Edge: 边，表示节点之间的转换
• OverAllState: 全局状态，在整个流程中携带共享数据
• CompiledGraph: 可执行图，处理实际执行、状态转换和结果流式传输

3. 快速开始

3.1 环境准备

3.2 创建项目

方式一：使用示例项目

# 克隆仓库
git clone https://github.com/alibaba/spring-ai-alibaba.git
cd spring-ai-alibaba/examples/chatbot

方式二：创建新项目

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

<dependencies>
<!– Agent Framework –>
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-agent-framework</artifactId>
</dependency>

<!– 选择模型提供商 –>
<!– DashScope (阿里云百炼) –>
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
<version>1.1.0.0-M5</version>
</dependency>

<!– 或 OpenAI –>
<!– <dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency> –>

<!– Spring Boot Web –>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>

3.3 配置 API Key

在 application.yml 或环境变量中配置：

spring:
ai:
dashscope:
api-key: ${AI_DASHSCOPE_API_KEY}

或使用环境变量：

export AI_DASHSCOPE_API_KEY=your-api-key

3.4 创建第一个 Agent

@Configuration
public class AgentConfig {

@Bean
public ReactAgent chatBotAgent(ChatModel chatModel) {
return ReactAgent.builder()
.name("ChatBot")
.model(chatModel)
.instruction("你是一个友好的AI助手，能够回答用户的问题。")
.enableLogging(true)
.build();
}
}

3.5 使用 Agent

@RestController
public class ChatController {

@Autowired
private ReactAgent chatBotAgent;

@GetMapping("/chat")
public String chat(@RequestParam String query) {
AssistantMessage response = chatBotAgent.call(query);
return response.getContent();
}
}

3.6 运行应用

mvn spring-boot:run

访问 http://localhost:8080/chat?query=你好 进行测试。

4. 核心概念

4.1 ReactAgent

ReactAgent 是 Spring AI Alibaba 的核心 Agent 实现，基于 ReAct（Reasoning + Acting）范式：

• Reasoning（推理）: Agent 分析问题并制定计划
• Acting（行动）: Agent 执行工具调用获取信息
• 循环迭代: 推理和行动交替进行，直到解决问题

基本用法

ReactAgent agent = ReactAgent.builder()
.name("MyAgent")
.model(chatModel)
.instruction("你是一个专业的助手")
.tools(tool1, tool2, tool3) // 可选：添加工具
.enableLogging(true) // 可选：启用日志
.build();

// 调用 Agent
AssistantMessage response = agent.call("用户的问题");

4.2 工具（Tools）

工具允许 Agent 执行外部操作，如调用 API、执行代码、查询数据库等。

创建自定义工具

public class CalculatorTool implements BiFunction<CalculatorRequest, ToolContext, String> {

public static final String DESCRIPTION = "执行数学计算";

@Override
public String apply(CalculatorRequest request, ToolContext context) {
// 实现计算逻辑
double result = request.a + request.b;
return String.valueOf(result);
}

public static class CalculatorRequest {
@JsonProperty(required = true)
@JsonPropertyDescription("第一个数字")
public double a;

@JsonProperty(required = true)
@JsonPropertyDescription("第二个数字")
public double b;
}

// 创建 ToolCallback
public static ToolCallback createToolCallback() {
return FunctionToolCallback.builder("calculator", new CalculatorTool())
.description(DESCRIPTION)
.inputType(CalculatorRequest.class)
.build();
}
}

使用工具

ReactAgent agent = ReactAgent.builder()
.name("CalculatorAgent")
.model(chatModel)
.tools(CalculatorTool.createToolCallback())
.build();

4.3 消息（Messages）

Spring AI Alibaba 使用 Spring AI 的消息抽象：

• UserMessage: 用户消息
• AssistantMessage: 助手消息
• SystemMessage: 系统消息
• ToolResponseMessage: 工具响应消息

// 使用字符串
AssistantMessage response = agent.call("你好");

// 使用消息对象
UserMessage userMessage = new UserMessage("你好");
AssistantMessage response = agent.call(userMessage);

4.4 状态管理（State Management）

Agent 使用 OverAllState 管理状态：

// 获取执行后的状态
Optional<OverAllState> state = agent.invoke("问题");
if (state.isPresent()) {
OverAllState overallState = state.get();
// 访问状态中的数据
Optional<Object> messages = overallState.value("messages");
}

4.5 内存（Memory）

Agent 可以配置内存保存器来持久化对话历史：

ReactAgent agent = ReactAgent.builder()
.name("AgentWithMemory")
.model(chatModel)
.saver(new MemorySaver()) // 内存保存器
.build();

5. Agent Framework 使用指南

5.1 ReactAgent 详解

5.1.1 基本配置

ReactAgent agent = ReactAgent.builder()
.name("agent-name") // Agent 名称
.description("Agent 描述") // Agent 描述
.model(chatModel) // 使用的模型
.instruction("系统指令") // 系统提示词
.systemPrompt("系统提示词") // 或使用 systemPrompt
.tools(tool1, tool2) // 工具列表
.enableLogging(true) // 启用日志
.build();

5.1.2 高级配置

ReactAgent agent = ReactAgent.builder()
.name("AdvancedAgent")
.model(chatModel)
.instruction("你是一个专业的助手")

// Hooks（钩子）
.hooks(
humanInTheLoopHook, // 人在回路
summarizationHook // 摘要钩子
)

// Interceptors（拦截器）
.interceptors(
contextEditingInterceptor, // 上下文编辑
toolRetryInterceptor, // 工具重试
toolCallLimitInterceptor // 工具调用限制
)

// 内存
.saver(new MemorySaver())

// 输出配置
.outputKey("result") // 输出键名
.outputKeyStrategy(new ReplaceStrategy()) // 输出策略

.build();

5.2 多 Agent 编排

5.2.1 SequentialAgent（顺序 Agent）

顺序执行多个 Agent，前一个 Agent 的输出作为下一个 Agent 的输入：

// 创建子 Agent
ReactAgent agent1 = ReactAgent.builder()
.name("writer")
.model(chatModel)
.instruction("你是一个作家，负责创作内容")
.outputKey("content")
.build();

ReactAgent agent2 = ReactAgent.builder()
.name("editor")
.model(chatModel)
.instruction("你是一个编辑，负责修改和优化内容")
.inputKey("content") // 使用前一个 Agent 的输出
.outputKey("edited_content")
.build();

// 创建顺序 Agent
SequentialAgent sequentialAgent = SequentialAgent.builder()
.name("writing-pipeline")
.description("写作和编辑流水线")
.rootAgent(agent1) // 根 Agent
.subAgents(List.of(agent2)) // 子 Agent 列表
.build();

// 使用
AssistantMessage result = sequentialAgent.call("写一篇关于春天的文章");

5.2.2 ParallelAgent（并行 Agent）

并行执行多个 Agent，然后合并结果：

// 创建多个专业 Agent
ReactAgent proseWriter = ReactAgent.builder()
.name("prose_writer")
.model(chatModel)
.instruction("你是一个散文作家")
.outputKey("prose_result")
.build();

ReactAgent poemWriter = ReactAgent.builder()
.name("poem_writer")
.model(chatModel)
.instruction("你是一个诗人")
.outputKey("poem_result")
.build();

ReactAgent summaryWriter = ReactAgent.builder()
.name("summary_writer")
.model(chatModel)
.instruction("你是一个总结专家")
.outputKey("summary_result")
.build();

// 创建并行 Agent
ParallelAgent parallelAgent = ParallelAgent.builder()
.name("multi-writer")
.description("并行执行多个创作任务")
.rootAgent(proseWriter) // 根 Agent（可选）
.subAgents(List.of(poemWriter, summaryWriter))
.mergeStrategy(new ParallelAgent.DefaultMergeStrategy()) // 合并策略
.maxConcurrency(3) // 最大并发数
.build();

// 使用
AssistantMessage result = parallelAgent.call("以'春天'为主题创作");

5.2.3 LlmRoutingAgent（LLM 路由 Agent）

使用 LLM 根据输入动态选择执行哪个 Agent：

// 创建路由 Agent
LlmRoutingAgent routingAgent = LlmRoutingAgent.builder()
.name("router")
.model(chatModel)
.instruction("根据用户问题选择合适的 Agent")
.routeAgents(Map.of(
"technical", technicalAgent,
"creative", creativeAgent,
"analytical", analyticalAgent
))
.build();

// 使用
AssistantMessage result = routingAgent.call("用户问题");

5.2.4 LoopAgent（循环 Agent）

循环执行 Agent 直到满足条件：

LoopAgent loopAgent = LoopAgent.builder()
.name("loop-agent")
.model(chatModel)
.instruction("持续处理任务直到完成")
.agent(workerAgent)
.maxIterations(10) // 最大迭代次数
.build();

5.3 Hooks（钩子）

Hooks 允许在 Agent 执行过程中插入自定义逻辑：

5.3.1 HumanInTheLoopHook（人在回路）

允许在关键决策点暂停，等待人工输入：

HumanInTheLoopHook hook = HumanInTheLoopHook.builder()
.enabled(true)
.build();

ReactAgent agent = ReactAgent.builder()
.name("agent")
.model(chatModel)
.hooks(hook)
.build();

5.3.2 SummarizationHook（摘要钩子）

自动对长对话进行摘要，减少上下文长度：

SummarizationHook hook = SummarizationHook.builder()
.trigger(10000) // 触发阈值（字符数）
.clearAtLeast(6000) // 至少清除的字符数
.keep(4) // 保留的消息数
.build();

5.4 Interceptors（拦截器）

Interceptors 用于拦截和修改 Agent 的行为：

5.4.1 ContextEditingInterceptor（上下文编辑）

允许编辑和修改上下文：

ContextEditingInterceptor interceptor = ContextEditingInterceptor.builder()
.enabled(true)
.build();

5.4.2 ToolRetryInterceptor（工具重试）

自动重试失败的工具调用：

ToolRetryInterceptor interceptor = ToolRetryInterceptor.builder()
.maxRetries(3)
.retryDelay(Duration.ofSeconds(1))
.build();

5.4.3 ToolCallLimitInterceptor（工具调用限制）

限制工具调用的次数：

ToolCallLimitInterceptor interceptor = ToolCallLimitInterceptor.builder()
.maxToolCalls(10)
.build();

6. Graph Core 使用指南

6.1 基本概念

Graph Core 是底层工作流运行时，提供更灵活的工作流编排能力。

6.1.1 StateGraph（状态图）

StateGraph 用于定义工作流：

// 创建状态工厂
OverAllStateFactory stateFactory = () -> {
OverAllState state = new OverAllState();
state.registerKeyAndStrategy("input", new ReplaceStrategy());
state.registerKeyAndStrategy("output", new ReplaceStrategy());
return state;
};

// 创建状态图
StateGraph graph = new StateGraph("MyWorkflow", stateFactory)
.addNode("node1", node_async(nodeAction1))
.addNode("node2", node_async(nodeAction2))
.addEdge(START, "node1")
.addEdge("node1", "node2")
.addEdge("node2", END);

6.1.2 Node（节点）

节点封装了工作流中的一个步骤：

// 创建节点动作
NodeAction nodeAction = (state) -> {
// 读取输入
String input = (String) state.value("input").orElse("");

// 处理逻辑
String output = process(input);

// 写入输出
state.put("output", output);

return state;
};

// 添加到图
graph.addNode("process_node", node_async(nodeAction));

6.1.3 Edge（边）

边定义节点之间的转换：

// 简单边
graph.addEdge("node1", "node2");

// 条件边
graph.addConditionalEdges(
"node1",
edge_async((state) -> {
// 根据状态决定下一个节点
String condition = (String) state.value("condition").orElse("default");
return condition;
}),
Map.of(
"option1", "node2",
"option2", "node3",
"default", "node4"
)
);

6.2 完整示例

@Configuration
public class WorkflowConfig {

@Bean
public StateGraph workflowGraph(ChatModel chatModel) throws GraphStateException {
// 创建 ChatClient
ChatClient chatClient = ChatClient.builder(chatModel)
.defaultAdvisors(new SimpleLoggerAdvisor())
.build();

// 创建状态工厂
OverAllStateFactory stateFactory = () -> {
OverAllState state = new OverAllState();
state.registerKeyAndStrategy("input", new ReplaceStrategy());
state.registerKeyAndStrategy("classification", new ReplaceStrategy());
state.registerKeyAndStrategy("result", new ReplaceStrategy());
return state;
};

// 创建分类节点
QuestionClassifierNode classifier = QuestionClassifierNode.builder()
.chatClient(chatClient)
.inputTextKey("input")
.categories(List.of("positive", "negative"))
.build();

// 创建处理节点
NodeAction processor = (state) -> {
String classification = (String) state.value("classification").orElse("");
String result = "处理结果: " + classification;
state.put("result", result);
return state;
};

// 创建路由逻辑
EdgeAction router = (state) -> {
String classification = (String) state.value("classification").orElse("unknown");
return classification.contains("positive") ? "positive" : "negative";
};

// 构建图
StateGraph graph = new StateGraph("CustomerService", stateFactory)
.addNode("classifier", node_async(classifier))
.addNode("processor", node_async(processor))
.addEdge(START, "classifier")
.addConditionalEdges("classifier", edge_async(router),
Map.of("positive", "processor", "negative", "processor"))
.addEdge("processor", END);

return graph;
}
}

6.3 使用 CompiledGraph

@RestController
public class WorkflowController {

private final CompiledGraph compiledGraph;

public WorkflowController(StateGraph stateGraph) throws GraphStateException {
this.compiledGraph = stateGraph.compile();
}

@GetMapping("/workflow")
public String executeWorkflow(@RequestParam String input) {
OverAllState initialState = new OverAllState();
initialState.put("input", input);

Optional<OverAllState> result = compiledGraph.invoke(initialState);

return result.map(state -> (String) state.value("result").orElse(""))
.orElse("执行失败");
}
}

7. 高级特性

7.1 A2A（Agent-to-Agent）通信

A2A 支持分布式 Agent 之间的通信和协作。

7.1.1 配置 A2A Server

<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter-a2a-nacos</artifactId>
<version>1.1.0.0-M5</version>
</dependency>

spring:
cloud:
nacos:
discovery:
server-addr: localhost:8848
ai:
alibaba:
a2a:
enabled: true
agent-name: my–agent

7.1.2 使用 A2A Client

@Autowired
private A2AClient a2aClient;

public void callRemoteAgent() {
A2AMessage request = new A2AMessage("remote-agent", "问题");
A2AMessage response = a2aClient.call(request);
}

7.2 动态配置（Nacos）

支持通过 Nacos 动态配置 Agent：

<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter-config-nacos</artifactId>
<version>1.1.0.0-M5</version>
</dependency>

@Bean
public ReactAgent nacosAgent(NacosOptions nacosOptions) {
return NacosReactAgentBuilder.builder()
.nacosOptions(nacosOptions)
.build();
}

7.3 可观测性（Observation）

集成 OpenTelemetry 进行可观测性监控：

<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter-graph-observation</artifactId>
<version>1.1.0.0-M5</version>
</dependency>

StateGraph graph = new StateGraph("Workflow", stateFactory)
.compile(CompileConfig.builder()
.withLifecycleListener(new GraphObservationLifecycleListener(observationRegistry))
.build());

7.4 MCP（Model Context Protocol）支持

支持 MCP 工具集成：

// 配置 MCP 工具
McpToolCallbackProvider mcpProvider = new McpToolCallbackProvider();
List<ToolCallback> mcpTools = mcpProvider.getToolCallbacks();

ReactAgent agent = ReactAgent.builder()
.name("MCPAgent")
.model(chatModel)
.tools(mcpTools)
.build();

7.5 流式响应

支持流式返回 Agent 响应：

@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> streamChat(@RequestParam String query) {
return agent.stream(query)
.map(AssistantMessage::getContent);
}

8. 最佳实践

8.1 Agent 设计原则

8.2 性能优化

8.3 安全性

8.4 调试和监控

9. 常见问题

9.1 如何选择合适的 Agent 类型？

• 简单任务: 使用 ReactAgent
• 顺序处理: 使用 SequentialAgent
• 并行处理: 使用 ParallelAgent
• 动态路由: 使用 LlmRoutingAgent
• 复杂工作流: 直接使用 Graph Core

9.2 如何处理长对话？

使用 SummarizationHook 自动摘要：

SummarizationHook hook = SummarizationHook.builder()
.trigger(10000)
.clearAtLeast(6000)
.keep(4)
.build();

9.3 如何限制工具调用次数？

使用 ToolCallLimitInterceptor:

ToolCallLimitInterceptor interceptor = ToolCallLimitInterceptor.builder()
.maxToolCalls(10)
.build();

9.4 如何实现人在回路？

使用 HumanInTheLoopHook:

HumanInTheLoopHook hook = HumanInTheLoopHook.builder()
.enabled(true)
.build();

9.5 如何调试 Agent 执行？

10. 参考资料

10.1 官方文档

• Spring AI Alibaba 官方文档
• Agent Framework 文档
• Graph Core 文档
• Spring AI 文档

10.2 示例代码

• GitHub Examples
• Spring AI Alibaba Examples

10.3 社区资源

• GitHub 仓库
• 钉钉群
• 微信公众号

10.4 相关项目

• Spring AI Alibaba Admin: 本地可视化工具包
• Spring AI Extensions: Spring AI 扩展实现
• JManus: Java 实现的 Manus
• DataAgent: 自然语言转 SQL 项目
• DeepResearch: 深度研究实现

10.5 白皮书

• AI-Native Application Architecture White Paper: AI 原生应用架构白皮书

附录

A. 依赖版本说明

当前文档基于以下版本：

• Spring AI Alibaba: 1.1.0.0-M5
• Spring AI: 1.1.0-M4
• Spring Boot: 3.4.8
• JDK: 17+

B. 快速参考

B.1 ReactAgent 构建器

ReactAgent.builder()
.name(String) // 必需
.model(ChatModel) // 必需
.instruction(String) // 可选
.systemPrompt(String) // 可选
.tools(ToolCallback...) // 可选
.hooks(Hook...) // 可选
.interceptors(Interceptor...) // 可选
.saver(MemorySaver) // 可选
.enableLogging(boolean) // 可选
.build()

B.2 常用工具创建

// 函数工具
FunctionToolCallback.builder("toolName", function)
.description("工具描述")
.inputType(InputType.class)
.build()

// Python 工具
PythonTool.createPythonToolCallback("执行 Python 代码")

B.3 状态管理

// 注册键和策略
state.registerKeyAndStrategy("key", new ReplaceStrategy());
state.registerKeyAndStrategy("key", new AppendStrategy());

// 读取值
Optional<Object> value = state.value("key");

// 写入值
state.put("key", value);