05.Spring AI Alibaba 多智能体Multi-Agent

一灰灰blog约 2833 字大约 9 分钟

Spring AI Alibaba 实战：多智能体（Multi-agent）系统科普与实现指南

1. 引言

在单体智能体（Single-agent）架构中，一个 Agent 需要处理所有任务——从理解用户意图、规划步骤、调用工具到生成最终答案。随着任务复杂度的提升，这种“全能型” Agent 往往会面临上下文爆炸、工具选择困难和专业化不足等问题。

多智能体（Multi-agent）系统通过将复杂任务分解为多个协同工作的专业化 Agent，有效解决了这些问题。本文将基于 Spring AI Alibaba，深入浅出地讲解 Multi-agent 的核心概念、实现模式及最佳实践，并提供完整的代码示例。

本文代码示例基于 Spring AI Alibaba 1.0.0+ 版本，完整项目代码可参考 Java2AI Multi-agent 文档open in new window。

2. 什么是 Multi-agent？

2.1 核心定义

Multi-agent 是指由多个智能体组成的系统，这些智能体通过协作完成复杂任务。与单体智能体不同，Multi-agent 系统中的每个 Agent 通常具备特定的专业领域或职责。

2.2 与单体智能体的对比

特性	单体智能体 (Single-agent)	多智能体 (Multi-agent)
职责	全能型，处理所有任务	专业化，分工明确
上下文	所有信息集中在一个 Agent	上下文按需分配给不同 Agent
工具数量	可能过多，导致选择困难	每个 Agent 拥有少量专用工具
扩展性	随任务复杂度线性增长	通过增加 Agent 横向扩展
适用场景	简单任务、快速原型	复杂工作流、企业级应用

3. Multi-agent 能解决什么问题？

3.1 单体智能体的局限性

上下文窗口限制：长对话历史会迅速填满上下文窗口，导致模型性能下降。
工具选择困难：当 Agent 拥有几十个工具时，LLM 很难准确选择最合适的工具。
专业化不足：一个 Agent 难以同时精通写作、编程、数据分析等多个领域。
状态管理复杂：复杂任务的状态追踪困难，容易丢失中间步骤。

3.2 Multi-agent 的优势

上下文隔离：每个 Agent 只关注自己需要的信息，减少上下文污染。
工具精简：每个 Agent 只配备必要的工具，提高工具调用准确率。
专业化分工：不同 Agent 专注不同领域，提升任务处理质量。
灵活编排：通过组合不同模式（顺序、并行、路由），构建复杂工作流。

4. Spring AI Alibaba 中的 Multi-agent 模式

Spring AI Alibaba 支持多种 Multi-agent 模式，每种模式适用于不同的场景：

4.1 顺序执行（Sequential Agent）

场景：任务需要按固定顺序执行，前一步的输出是后一步的输入。

流程：

Agent A (处理) → 输出 → Agent B (处理) → 输出 → Agent C (最终结果)

示例：写作工作流

Writer Agent：根据用户需求撰写文章
Reviewer Agent：评审并修改文章
Translator Agent：翻译成目标语言

4.2 并行执行（Parallel Agent）

场景：多个任务可以同时进行，最后合并结果。

流程：

      ┌─ Agent A ─┐
输入 ─┼─ Agent B ─┼─ 合并输出
      └─ Agent C ─┘

示例：研究工作流

Web Research Agent：从互联网搜索信息
DB Research Agent：从数据库查询信息
Merge Agent：合并所有来源的数据

4.3 路由模式（LlmRoutingAgent）

场景：根据用户输入动态选择最合适的 Agent。

流程：

用户输入 → Router Agent (LLM决策) → 选择子 Agent → 执行 → 返回结果

示例：客服系统

用户问技术问题 →路由到 Technical Support Agent
用户问账单问题 →路由到 Billing Agent
用户问退货问题 →路由到 Return Agent

4.4 监督者模式（SupervisorAgent）

场景：复杂多步骤任务，需要动态决策下一步执行哪个 Agent。

流程：

用户输入 → Supervisor Agent → 选择子 Agent → 执行 → 返回 Supervisor → 决策下一步...

示例：内容处理工作流

Supervisor 接收"写一篇关于春天的文章并翻译成英文"
路由到 Writer Agent 写文章
Writer 完成后返回 Supervisor
Supervisor 路由到 Translator Agent 翻译
返回最终结果

5. 技术实现：基于 Spring AI Alibaba

5.1 项目依赖

首先在 pom.xml 中引入 Spring AI Alibaba 依赖：

<dependencies>
    <!-- Spring AI Alibaba 核心 -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-agent-framework</artifactId>
        <version>${ali-version}</version>
    </dependency>
    
    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

5.2 核心概念：OverAllState

在 Multi-agent 系统中，OverAllState 是贯穿所有 Agent 的共享状态容器。它存储了对话历史、中间结果和全局变量。

// OverAllState 自动管理，无需手动创建
// Agent 通过 outputKey 将输出存入状态
// 后续 Agent 通过占位符 {key} 引用状态中的值

5.3 Instruction 占位符

Agent 之间的数据传递通过 Instruction 占位符 实现：

// 第一个 Agent：写文章
ReactAgent writerAgent = ReactAgent.builder()
    .name("writer_agent")
    .instruction("你是一个作家，请根据用户提问写作：{input}")
    .outputKey("article")  // 输出存入状态，key 为 "article"
    .build();

// 第二个 Agent：评审文章
ReactAgent reviewerAgent = ReactAgent.builder()
    .name("reviewer_agent")
    .instruction("请评审文章：{article}")  // 通过 {article} 引用前序输出
    .outputKey("reviewed_article")
    .build();

在alibaba的框架中，支持的占位符

占位符	说明	使用场景
	用户输入的原始内容	第一个Agent或需要用户输入的 Agent
	引用其他Agent通过 outputKey 存储的输出	顺序执行中，后续Agent引用前面Agent的输出
	引用状态中的任意键值	访问状态中的任何数据

占位符工作原理

自动替换：系统会在执行 Agent 的 instruction 时，自动将占位符替换为对应的实际值状态查找：占位符会从当前状态（OverAllState）中查找对应的值类型安全：占位符的值会被转换为字符串并插入到 instruction 中

6. 实战示例：写作与评审工作流

我们将实现一个顺序执行的 Multi-agent 系统：Writer Agent 负责写作，Reviewer Agent 负责评审。

6.1 创建 Writer Agent

import com.alibaba.cloud.ai.graph.agent.ReactAgent;
import org.springframework.ai.chat.model.ChatModel;

public class WriterAgentFactory {
    
    public static ReactAgent create(ChatModel chatModel) {
        return ReactAgent.builder()
            .name("writer_agent")
            .model(chatModel)
            .description("专业写作 Agent，擅长创作各类文章")
            .instruction("""
                你是一位知名作家，擅长创作各类文章。
                请根据用户的提问进行回答，文章长度控制在 200 字左右。
                
                用户提问：{input}
                """)
            .outputKey("article")
            .build();
    }
}

6.2 创建 Reviewer Agent

public class ReviewerAgentFactory {
    
    public static ReactAgent create(ChatModel chatModel) {
        return ReactAgent.builder()
            .name("reviewer_agent")
            .model(chatModel)
            .description("专业评审 Agent，擅长修改和润色文章")
            .instruction("""
                你是一位资深评论家，擅长对文章进行评审和修改。
                
                待评审文章：{article}
                
                请确保：
                1. 文章包含对西湖风景的描述
                2. 语言优美流畅
                3. 最终只返回修改后的文章，不要包含任何评论信息
                """)
            .outputKey("reviewed_article")
            .build();
    }
}

6.3 创建顺序执行工作流

import com.alibaba.cloud.ai.graph.agent.flow.agent.SequentialAgent;
import java.util.List;

public class BlogWorkflowFactory {
    
    public static SequentialAgent create(ChatModel chatModel) {
        // 创建子 Agent
        ReactAgent writerAgent = WriterAgentFactory.create(chatModel);
        ReactAgent reviewerAgent = ReviewerAgentFactory.create(chatModel);
        
        // 创建顺序执行的 Multi-agent
        return SequentialAgent.builder()
            .name("blog_workflow")
            .description("写作与评审工作流：先写文章，再评审修改")
            .subAgents(List.of(writerAgent, reviewerAgent))
            .build();
    }
}

6.4 执行工作流

import com.alibaba.cloud.ai.graph.OverAllState;
import java.util.Optional;

public class MultiAgentDemo {
    
    public static void main(String[] args) {
        // 假设已初始化 ChatModel
        ChatModel chatModel = /* ... */;
        
        // 创建工作流
        SequentialAgent workflow = BlogWorkflowFactory.create(chatModel);
        
        // 执行任务
        Optional<OverAllState> result = workflow.invoke("帮我写一篇 100 字左右的西湖散文");
        
        // 处理结果
        if (result.isPresent()) {
            OverAllState state = result.get();
            
            // 访问第一个 Agent 的输出
            state.value("article").ifPresent(article -> {
                System.out.println("原始文章: " + article);
            });
            
            // 访问第二个 Agent 的输出
            state.value("reviewed_article").ifPresent(reviewedArticle -> {
                System.out.println("评审后文章: " + reviewedArticle);
            });
        }
    }
}

6.5 运行结果示例

原始文章: 西湖，位于杭州城西，是一颗璀璨的明珠。湖水清澈见底，四周绿树成荫...
评审后文章: 西湖，位于杭州城西，是一颗璀璨的明珠。湖水清澈见底，四周绿树成荫，远处的雷峰塔倒映在水中...

7. 实现注意事项

7.1 上下文工程（Context Engineering）

核心原则：确保每个 Agent 只看到它需要的信息。

避免上下文污染：不要将所有历史记录都传递给每个 Agent
合理使用 outputKey：明确每个 Agent 的输出键名
控制推理内容：通过 returnReasoningContents 控制是否包含中间推理

7.2 Agent 描述的重要性

在路由模式（LlmRoutingAgent）中，Agent 的 description 至关重要：

// ✅ 好的描述：明确职责边界
.description("专门处理编程问题，包括代码编写、调试、优化，擅长 Java/Python")

// ❌ 不好的描述：模糊不清
.description("处理各种问题")

7.3 错误处理与重试

最大迭代次数：设置合理的最大迭代次数防止无限循环
异常捕获：捕获工具调用异常，返回友好错误信息
状态恢复：使用 MemorySaver 保存状态，支持中断恢复

7.4 性能优化

并行执行：独立任务使用 ParallelAgent 并行处理
缓存机制：对重复查询结果进行缓存
流式输出：使用流式处理提升用户体验

8. 扩展应用场景

8.1 智能客服系统

Supervisor Agent
├── Technical Support Agent (技术问题)
├── Billing Agent (账单问题)
└── Return Agent (退货问题)

8.2 数据分析工作流

Sequential Agent
├── Data Collection Agent (数据收集)
├── Data Cleaning Agent (数据清洗)
├── Analysis Agent (数据分析)
└── Report Agent (报告生成)

8.3 研究助手

Parallel Agent
├── Web Research Agent (网络搜索)
├── Paper Research Agent (论文检索)
└── Database Agent (数据库查询)

9. 最佳实践总结

明确职责：每个 Agent 只做一件事，做到极致
合理编排：根据任务特点选择合适的模式（顺序/并行/路由）
上下文隔离：通过 outputKey 和占位符控制信息流动
描述清晰：为每个 Agent 编写明确的描述，便于路由决策
错误处理：设置最大迭代次数，捕获异常，提供友好提示
性能优化：并行执行独立任务，使用流式输出

10. 总结

Multi-agent 系统通过专业化分工和灵活编排，有效解决了单体智能体在复杂任务中的局限性。Spring AI Alibaba 提供了丰富的 Multi-agent 模式（Sequential、Parallel、Routing、Supervisor），让开发者能够轻松构建复杂的 AI 应用。

本文的示例行对比较简单，主要是介绍了SpringAI Alibaba的Multi-Agent的相关知识点：

✅ Multi-agent 的核心概念与优势
✅ Spring AI Alibaba 中的各种模式
✅ 顺序执行工作流的实现方法
✅ 上下文工程和 Agent 设计的最佳实践

那么在真实的项目系统中，多Agent的写作时，如何抉择这些模式（路由还是监督者？或者简单的串行/并行？），接下来我们将以结合具体的应用场景，来演示一下如何实现要给生产可用的多Agent协作示例

参考资料

作者：一灰
日期：2026 年 3 月 15 日
标签：#SpringAI #Multi-agent #AI-Agent #Java #智能体协作

05.Spring AI Alibaba 多智能体Multi-Agent

# Spring AI Alibaba 实战：多智能体（Multi-agent）系统科普与实现指南

# 1. 引言

# 2. 什么是 Multi-agent？

# 2.1 核心定义

# 2.2 与单体智能体的对比

# 3. Multi-agent 能解决什么问题？

# 3.1 单体智能体的局限性

# 3.2 Multi-agent 的优势

# 4. Spring AI Alibaba 中的 Multi-agent 模式

# 4.1 顺序执行（Sequential Agent）

# 4.2 并行执行（Parallel Agent）

# 4.3 路由模式（LlmRoutingAgent）

# 4.4 监督者模式（SupervisorAgent）

# 5. 技术实现：基于 Spring AI Alibaba

# 5.1 项目依赖

# 5.2 核心概念：OverAllState

# 5.3 Instruction 占位符

# 6. 实战示例：写作与评审工作流

# 6.1 创建 Writer Agent

# 6.2 创建 Reviewer Agent

# 6.3 创建顺序执行工作流

# 6.4 执行工作流

# 6.5 运行结果示例

# 7. 实现注意事项

# 7.1 上下文工程（Context Engineering）

# 7.2 Agent 描述的重要性

# 7.3 错误处理与重试

# 7.4 性能优化

# 8. 扩展应用场景

# 8.1 智能客服系统

# 8.2 数据分析工作流

# 8.3 研究助手

# 9. 最佳实践总结

# 10. 总结

# 参考资料