1. 项目概述
这个项目展示了如何使用Spring AI Alibaba框架构建一个旅游行程规划的多智能体系统。系统通过监督者模式(Supervisor Pattern)协调多个专家Agent(景点推荐、住宿推荐、交通规划)共同完成复杂的旅游行程规划任务。
作为一位在AI和分布式系统领域有多年实践经验的开发者,我发现这种多智能体架构特别适合解决需要多领域专业知识的复杂任务。旅游规划就是一个典型场景——它需要同时考虑景点、住宿、交通等多个维度的协调,这正是多智能体系统的用武之地。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心架构解析
2.1 多智能体协作模式
Spring AI Alibaba框架支持三种主要的智能体协作模式:
| 模式 | 特点 | 适用场景 |
|---|---|---|
| 路由模式(Router) | 单次决策,将请求路由到最合适的Agent | 简单的分类和路由任务 |
| 监督者模式(Supervisor) | 多步循环,监督者协调多个专家Agent | 复杂的多步骤协作任务 |
| 状态驱动交接 | 基于状态和条件的Agent切换 | 需要精确控制流程的任务 |
在本项目中,我们采用的是监督者模式。这种模式的核心优势在于:
- 可以处理需要多次迭代的复杂任务
- 支持任务分解和结果聚合
- 允许专家Agent之间的依赖关系
2.2 系统组件设计
项目的核心组件包括:
-
监督者Agent:TravelSupervisorPlanAgent
- 负责接收用户请求
- 分解任务并协调专家Agent
- 整合最终结果
-
专家Agent:
- AttractionAgent:景点推荐专家
- HotelAgent:住宿推荐专家
- TransportAgent:交通规划专家
-
辅助组件:
- HookFactory:提供执行过程监控
- TravelPlanController:REST API接口
3. 关键技术实现
3.1 监督者Agent配置
监督者Agent的配置是整个系统的核心:
java复制@Bean
public Agent travelSupervisorAgent() {
return SupervisorAgent.builder()
.name("supervisor_agent")
.model(chatModel)
.mainAgent(ReactAgent.builder()
.name("main_agent")
.model(chatModel)
.systemPrompt("""
你是一个旅行规划监督者,负责协调以下专家:
- attraction_agent:景点推荐
- hotel_agent:住宿推荐
- transport_agent:交通规划
请先调用attraction_agent,再根据景点信息协调其他专家。
""")
.build())
.subAgents(List.of(
attractionAgent.agent(),
hotelAgent.agent(),
transportAgent.agent()
))
.hooks(List.of(HookFactory.createLogAgentHook()))
.build();
}
关键配置项说明:
mainAgent:核心决策逻辑所在subAgents:专家Agent列表hooks:用于监控和日志记录
3.2 专家Agent实现
以景点推荐Agent为例:
java复制@Bean
public ReactAgent attractionAgent() {
return ReactAgent.builder()
.name("attraction_agent")
.model(chatModel)
.description("景点推荐专家")
.instruction("""
根据用户的目的地、天数、偏好,
推荐合适的景点和游览顺序。
输入:{input}
直接返回景点计划,包含每日安排。
""")
.outputKey("attraction_plan")
.build();
}
每个专家Agent都需要定义:
- 唯一名称(用于路由)
- 描述(帮助监督者理解其职责)
- 指令模板(包含{input}占位符)
- 输出键名(用于结果聚合)
3.3 依赖管理
旅游规划场景中,Agent之间存在明确的依赖关系:
- 必须先执行景点推荐
- 住宿推荐依赖景点信息
- 交通规划也依赖景点信息
这种依赖关系通过在监督者的systemPrompt中明确说明来实现:
code复制请记得在制定计划时,始终先调用attraction_agent来推荐景点、安排旅游路线;
因为transport_agent和hotel_agent这两个子Agent的执行都依赖attraction_agent的输出
4. 系统工作流程
4.1 完整执行流程
- 用户提交旅行请求(目的地、天数、预算等)
- 监督者接收请求并分析
- 首先调用景点推荐Agent
- 根据景点信息协调住宿推荐Agent
- 同时协调交通规划Agent
- 整合所有专家的建议
- 返回完整的旅行计划
4.2 流式API实现
项目提供了SSE(Server-Sent Events)流式接口,实时展示规划进度:
java复制@GetMapping(value = "/plan", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<ServerSentEvent<String>> planTravelStream(
@RequestParam String destination,
@RequestParam int days) {
return supervisorAgent.stream(
String.format("我想去%s旅行%d天", destination, days),
RunnableConfig.DEFAULT
).map(nodeOutput ->
ServerSentEvent.<String>builder()
.data(extractContent(nodeOutput))
.build()
);
}
这种设计让用户可以实时看到:
- 当前正在执行的Agent
- 每个步骤的中间结果
- 最终整合的完整方案
5. 实战经验分享
5.1 调试技巧
在多智能体系统中,调试是一个挑战。我们总结了几点经验:
-
使用Hook记录执行过程:
java复制public static AgentHook createLogAgentHook() { return new AgentHook() { @Override public CompletableFuture<Map<String, Object>> beforeAgent( OverAllState state, RunnableConfig config) { log.info("Before agent: {}", state.currentAgent()); return CompletableFuture.completedFuture(Map.of()); } }; } -
明确Agent职责边界:
- 每个Agent应该只负责一个明确的领域
- 避免功能重叠导致的混乱
-
测试单个Agent:
- 在集成前先单独测试每个Agent
- 确保其输入输出符合预期
5.2 性能优化
-
并行调用独立Agent:
- 对于没有依赖关系的Agent可以并行调用
- 例如住宿推荐和交通规划可以并行执行
-
缓存常用结果:
- 对高频查询的结果进行缓存
- 减少重复计算
-
限制迭代次数:
- 设置最大迭代次数防止无限循环
- 例如最多允许5次Agent交接
6. 框架演进与迁移
6.1 从Supervisor到Agent-as-Tool
最新版本的Spring AI Alibaba已经移除了SupervisorAgent,转而推荐使用Agent-as-Tool模式。迁移示例:
旧版(Supervisor):
java复制SupervisorAgent.builder()
.mainAgent(reactAgent)
.subAgents(List.of(agent1, agent2))
.build();
新版(Agent-as-Tool):
java复制ReactAgent.builder()
.tools(
AgentTool.getFunctionToolCallback(agent1),
AgentTool.getFunctionToolCallback(agent2)
)
.build();
6.2 两种模式对比
| 特性 | Supervisor模式 | Agent-as-Tool模式 |
|---|---|---|
| 路由机制 | 显式JSON路由 | LLM自动工具选择 |
| 状态管理 | 需要手动维护 | 框架自动处理 |
| 调试难度 | 较高 | 较低 |
| 灵活性 | 受限 | 更高 |
6.3 迁移建议
-
逐步迁移:
- 先迁移简单的Agent
- 再处理复杂依赖关系
-
测试保障:
- 建立完善的测试用例
- 确保迁移前后行为一致
-
文档更新:
- 更新系统架构图
- 修改相关文档说明
7. 扩展与优化方向
7.1 增强专家Agent能力
目前的专家Agent实现相对简单,可以考虑:
-
集成外部API:
- 景点Agent接入旅游平台数据
- 酒店Agent接入预订系统
-
个性化推荐:
- 基于用户历史偏好
- 结合季节和天气因素
-
多模态输出:
- 生成地图路线
- 提供景点图片
7.2 系统可靠性提升
-
错误处理:
- Agent执行失败的重试机制
- 优雅降级方案
-
监控告警:
- 执行耗时监控
- 异常情况告警
-
限流保护:
- 防止过多并发请求
- 设置QPS限制
7.3 用户体验优化
-
交互式规划:
- 允许用户中途调整需求
- 实时反馈修改效果
-
方案对比:
- 生成多个可选方案
- 突出差异点
-
导出分享:
- PDF格式导出
- 社交媒体分享
在实际项目中,我们发现多智能体系统的最大优势在于它的灵活性和可扩展性。随着业务需求的变化,可以相对容易地添加新的专家Agent或调整现有Agent的职责,而不用重构整个系统。这种架构特别适合快速迭代的业务场景。
