09.基于 Spring AI Alibaba 监督者交接策略实现旅游策划智能体

一灰灰blogSpringAISpringSpringAI约 3693 字大约 12 分钟

SpringAI Alibaba 监督者策略实战:从原理到旅游行程规划智能体

L09-cover.png
L09-cover.png

1. 引言

在多智能体系统中,如何让多个专家 Agent 协同工作是一个核心问题。SpringAI Alibaba 框架提供了多种交接策略(Handoff Strategy),其中监督者策略(Supervisor Pattern)是一种经典的多智能体协作模式。

本教程将基于 /ali/L08-multi-agent-supervisor 项目,介绍一下如何在一个真实的应用场景中你,利用监督者策略,来实现一个旅游行程规划智能体,以此来展示如何构建一个多智能体协作系统。

重要提示:在 SpringAI Alibaba 的最新框架中,监督者策略已经被移除,改为将 Agent 作为工具(Agent-as-Tool)的方式来实现类似效果。 本文也会简单介绍一下两者的区别

2. 背景知识

2.1 多智能体交接策略概述

SpringAI Alibaba 框架支持多种多智能体协作模式:

L09-2.png
L09-2.png
模式特点适用场景
路由模式(Router)单次决策,将请求路由到最合适的 Agent简单的分类和路由任务
监督者模式(Supervisor)多步循环,监督者协调多个专家 Agent复杂的多步骤协作任务
状态驱动交接(State-driven)基于状态和条件的 Agent 切换需要精确控制流程的任务,如典型的LangGraph应用案例

2.2 监督者策略的核心思想

监督者策略的核心是中心化的任务协调:

L09-1.png
L09-1.png
  1. 监督者(Supervisor):负责接收用户请求、分解任务、协调专家、整合结果
  2. 专家 Agent(Specialist):专注于特定领域的任务执行
  3. 循环调度:监督者可以多次调用不同的专家,直到任务完成
用户请求 → 监督者 → 专家A → 监督者 → 专家B → 监督者 → 整合结果 → 用户

2.3 与其他模式的对比

特性路由模式监督者模式
决策次数单次多次
子 Agent 返回直接结束返回监督者
占位符支持❌✅ ({input})
状态聚合❌✅
复杂度低高

3. 项目结构

3.1 整体架构

L08-multi-agent-supervisor/
├── src/main/java/com/git/hui/springai/ali/
│   ├── controller/
│   │   ├── TravelPlanController.java      # REST 控制器(SSE 流式接口)
│   │   └── HookFactory.java               # Hook 工厂(日志和监控)
│   ├── planer/
│   │   ├── TravelSupervisorPlanAgent.java # 监督者 Agent(核心)
│   │   ├── AttractionAgent.java           # 景点推荐专家
│   │   ├── HotelAgent.java                # 住宿推荐专家
│   │   └── TransportAgent.java            # 交通规划专家
│   └── L08Application.java                # Spring Boot 启动类
├── src/main/resources/
│   ├── templates/
│   │   └── travel-plan.html               # 前端界面
│   └── application.yml                    # 配置文件
└── pom.xml                                # Maven 依赖

3.2 依赖配置

<dependencies>
    <!-- SpringAI Alibaba 核心依赖 -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency>
    
    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

3.3 API 配置

spring:
  ai:
    openai:
      api-key: ${silicon-api-key}
      base-url: https://api.siliconflow.cn
      chat:
        options:
          model: Qwen/Qwen3-8B

4. 核心代码解析

4.1 监督者 Agent 实现

L09-3.png
L09-3.png

TravelSupervisorPlanAgent.java 是整个系统的核心,负责协调各个专家 Agent:

@Component
public class TravelSupervisorPlanAgent {
    private final AttractionAgent attractionAgent;
    private final HotelAgent hotelAgent;
    private final TransportAgent transportAgent;
    private final ChatModel chatModel;

    public Agent agent() {
        AgentHook logHook = HookFactory.createLogAgentHook();
        
        SupervisorAgent supervisorAgent = SupervisorAgent.builder()
                .name("supervisor_agent")
                .description("内容管理监督者,负责协调景点推荐、城市规划、住宿推荐等")
                .model(chatModel)
                .mainAgent(ReactAgent.builder()
                        .name("main_agent")
                        .model(chatModel)
                        .description("监督者主Agent,负责路由决策")
                        .systemPrompt("""
                                你是一个旅行规划监督者,你的任务是帮助用户制定旅行计划。
                                你可以协调以下专家:
                                - attraction_agent:负责推荐景点、安排游览路线。
                                - transport_agent:负责规划城市间交通和市内交通。
                                - hotel_agent:负责推荐酒店、民宿等住宿。
                                
                                ## 路由决策输出格式
                                当需要做出路由决策时,请以 JSON 数组格式输出:
                                - 选择单个子Agent: ["attraction_agent"]
                                - 选择多个子Agent: ["transport_agent", "hotel_agent"]
                                - 任务完成: [] 或 ["FINISH"]
                                """)
                        .instruction("用户的请求是: {input}")
                        .outputKey("final_output")
                        .build())
                .subAgents(List.of(
                    attractionAgent.agent(), 
                    hotelAgent.agent(), 
                    transportAgent.agent()
                ))
                .hooks(List.of(logHook))
                .build();

        return supervisorAgent;
    }
}

关键点解析:

  1. mainAgent:监督者的主 Agent,负责路由决策
  2. subAgents:专家 Agent 列表
  3. hooks:用于日志记录和监控
  4. {input} 占位符:在执行时会被替换为实际的用户输入
  5. JSON 路由格式:监督者通过输出 JSON 数组来决定下一步调用哪个专家(或者哪几个专家)

4.2 专家 Agent 实现

本文的案例主要是为了演示监督者的交接方式,各子Agent的实现相对简陋,大家完全可以丰富子Agent的能力,将其与外部的工具进行联动,比如查询小红书的旅游推荐、地图的导航、美团/携程的酒店预定等能力

@RequiredArgsConstructor
@Component
public class AttractionAgent {
    private final ChatModel chatModel;

    public ReactAgent agent() {
        ReactAgent agent = ReactAgent.builder()
                .name("attraction_agent")
                .model(chatModel)
                .description("景点推荐专家,善于根据用户的需求推荐各种适合游玩的景点")
                .instruction("""
                        你是一个旅行景点推荐专家。请根据用户的目的地、天数、偏好,
                        推荐合适的景点和游览顺序。
                        当前已知信息:{input}
                        如果某些信息不完整,请基于已有信息尽量给出合理建议。
                        直接返回景点计划,包含每日安排。
                        """)
                .outputKey("attraction_plan")
                .enableLogging(true)
                .build();

        return agent;
    }
}

@RequiredArgsConstructor
@Component
public class HotelAgent {
    private final ChatModel chatModel;

    public ReactAgent agent() {
        ReactAgent agent = ReactAgent.builder()
                .name("hotel_agent")
                .model(chatModel)
                .description("住宿推荐专家,善于根据用户需求推荐适合的住宿")
                .instruction("""
                        你是一个住宿推荐专家。请根据用户的景点计划、预算,推荐合适的住宿地点和酒店。
                        输入:{input}
                        请返回住宿建议,包括区域和酒店示例。
                        """
                )
                .outputKey("hotel_plan")
                .enableLogging(true)
                .build();
        return agent;
    }
}

@RequiredArgsConstructor
@Component
public class TransportAgent {
    private final ChatModel chatModel;

    public ReactAgent agent() {
        ReactAgent agent = ReactAgent.builder()
                .name("transport_agent")
                .model(chatModel)
                .description("交通规划专家,善于根据用户需求规划最佳的出行方式")
                .instruction("""
                        你是一个交通规划专家。请根据用户的出发地、目的地、景点安排,规划交通方式。
                        输入:{input}
                        请返回详细的交通方案,包括城际交通和市内交通建议。
                          """
                )
                .enableLogging(true)
                .outputKey("transport_plan")
                .build();
        return agent;
    }
}

关键点:

  • name:Agent 的唯一标识符,用于路由决策
  • description:简短描述,帮助监督者理解 Agent 的职责
  • instruction:详细的指令模板,包含 {input} 占位符
  • outputKey:输出结果的键名,用于状态聚合

4.3 Agent 依赖关系

在旅游行程规划中,Agent 之间存在依赖关系:

L09-4.png
L09-4.png
用户请求
    ↓
监督者 (Supervisor)
    ↓
景点推荐 (AttractionAgent) ← 必须首先执行
    ↓
    ├── 住宿推荐 (HotelAgent) ← 依赖景点信息
    └── 交通规划 (TransportAgent) ← 依赖景点信息
    ↓
监督者整合 → 最终方案

监督者通过系统提示中的指令来确保执行顺序:

.systemPrompt("""
    请记得在制定计划时,始终先调用 attraction_agent 来推荐景点、安排旅游路线;
    因为 transport_agent 和 hotel_agent 这两个子 Agent 的执行都依赖 attraction_agent 的输出
    """)

4.4 Hook 机制

HookFactory 提供了 Agent 执行过程的监控能力:

public static AgentHook createLogAgentHook() {
    return new AgentHook() {
        @Override
        public CompletableFuture<Map<String, Object>> beforeAgent(
                OverAllState state, RunnableConfig config) {
            System.out.println("BEFORE AGENT: " + getAgentName());
            // 记录输入和状态
            return CompletableFuture.completedFuture(Map.of());
        }

        @Override
        public CompletableFuture<Map<String, Object>> afterAgent(
                OverAllState state, RunnableConfig config) {
            System.out.println("AFTER AGENT: " + getAgentName());
            // 记录输出和结果
            return CompletableFuture.completedFuture(Map.of());
        }
    };
}

5. 实战:旅游行程规划智能体

5.1 系统工作流程

L09-5.png
L09-5.png
  1. 接收用户请求:用户通过 API 提交旅行需求
  2. 监督者分解任务:将复杂任务分解为景点、住宿、交通等子任务
  3. 协调专家执行:按顺序调用各个专家 Agent
  4. 结果整合:汇总所有专家的建议,形成完整的旅行计划

5.2 流式 API 实现

TravelPlanController.java 实现了基于 SSE 的流式接口:

@GetMapping(value = "/plan", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<ServerSentEvent<String>> planTravelStream(
        @RequestParam String destination,
        @RequestParam(required = false, defaultValue = "3") Integer days,
        @RequestParam(required = false) String budget,
        @RequestParam(required = false) String preferences) {

    Agent supervisorAgent = travelSupervisorPlanAgent.agent();

    // 构建用户请求
    String prompt = String.format("我想去%s旅行%d天,预算%s,我喜欢%s。请帮我制定详细的旅行计划。",
            destination, days, budget, preferences);

    // 获取流式输出
    Flux<NodeOutput> agentStream = supervisorAgent.stream(prompt, config);

    return agentStream
            .filter(nodeOutput -> !(nodeOutput instanceof StreamingOutput<?> so &&
                    so.getOutputType() == OutputType.AGENT_MODEL_FINISHED))
            .map(nodeOutput -> {
                // 构建 SSE 事件
                Map<String, Object> data = new HashMap<>();
                data.put("node", nodeOutput.node());
                data.put("agent", nodeOutput.agent());
                data.put("content", extractContent(nodeOutput));
                data.put("stage", determineStage(nodeOutput.agent()));
                
                return ServerSentEvent.<String>builder()
                        .event("message")
                        .data(objectMapper.writeValueAsString(data))
                        .build();
            });
}

5.3 阶段标识

系统通过 Agent 名称来确定当前执行阶段:

private String determineStage(String agentName) {
    if (agentName.contains("attraction")) {
        return "attraction"; // 景点推荐
    } else if (agentName.contains("hotel")) {
        return "hotel"; // 住宿推荐
    } else if (agentName.contains("transport")) {
        return "transport"; // 交通规划
    } else if (agentName.contains("supervisor")) {
        return "supervisor"; // 监督者统筹
    }
    return "unknown";
}

5.4 API 使用示例

# 请求
curl -X GET "http://localhost:8080/api/travel/plan?destination=北京&days=5&budget=5000元&preferences=美食,历史文化"

# 响应(SSE 流式)
event: message
data: {"node":"attraction_agent","agent":"attraction_agent","content":"推荐景点:故宫、天坛...","stage":"attraction"}

event: message
data: {"node":"hotel_agent","agent":"hotel_agent","content":"推荐住宿:王府井附近...","stage":"hotel"}

event: message
data: {"node":"supervisor_agent","agent":"supervisor_agent","content":"完整方案:...","stage":"supervisor"}

6. 流式输出与前端展示

6.1 前端架构

前端采用四面板布局,实时展示各个专家的工作进度:

<div class="content-section">
    <!-- 景点推荐面板 -->
    <div class="stage-panel" id="attractionPanel">
        <div class="stage-header">
            <div class="stage-icon">🏛️</div>
            <div class="stage-title">景点推荐</div>
        </div>
        <div class="stage-content" id="attractionContent">
            <div class="placeholder-text">等待开始规划...</div>
        </div>
    </div>
    
    <!-- 其他面板... -->
</div>

6.2 SSE 连接处理

function startPlanning() {
    const url = `/api/travel/plan?destination=${encodeURIComponent(destination)}&days=${days}`;
    eventSource = new EventSource(url);

    eventSource.addEventListener('message', function(event) {
        const data = JSON.parse(event.data);
        
        if (data.stage && data.hasContent) {
            updateStageContent(data.stage, data.content);
            activatePanel(data.stage);
            updateAgentBadge(data.stage);
        }
    });

    eventSource.addEventListener('done', () => {
        completePlanning();
    });
}

6.3 Markdown 渲染

前端使用 marked.js 渲染 Markdown 内容:

function updateStageContent(stage, content) {
    contentAccumulators[stage] += content;
    
    const contentElement = document.getElementById(stage + 'Content');
    if (contentElement) {
        const htmlContent = marked.parse(contentAccumulators[stage]);
        contentElement.innerHTML = htmlContent;
        contentElement.scrollTop = contentElement.scrollHeight;
    }
}

7. 框架迁移:从监督者到 Agent-as-Tool

7.1 监督者模式的局限性

监督者模式虽然强大,但也存在一些问题:

  1. 复杂度高:需要维护复杂的路由逻辑和 SUPERVISOR_NEXT_KEY 状态管理
  2. 调试困难:多步骤的执行流程难以追踪
  3. 灵活性不足:Hub-and-spoke 模式限制了 Agent 之间的直接交互

7.2 Agent-as-Tool 模式

在最新版本的 SpringAI Alibaba 中,推荐使用 Agent-as-Tool 模式(也称为 Agent Tool 模式):

import com.alibaba.cloud.ai.graph.agent.ReactAgent;
import com.alibaba.cloud.ai.graph.agent.AgentTool;

// 创建专家 Agent
ReactAgent attractionAgent = ReactAgent.builder()
        .name("attraction_agent")
        .model(chatModel)
        .description("景点推荐专家")
        .instruction("你是一个旅行景点推荐专家...")
        .build();

ReactAgent hotelAgent = ReactAgent.builder()
        .name("hotel_agent")
        .model(chatModel)
        .description("住宿推荐专家")
        .instruction("你是一个住宿推荐专家...")
        .build();

// 创建主 Agent,将专家 Agent 作为工具
ReactAgent supervisorAgent = ReactAgent.builder()
        .name("supervisor_agent")
        .model(chatModel)
        .instruction("你是一个旅行规划助手,使用工具来完成任务。")
        .tools(
            AgentTool.getFunctionToolCallback(attractionAgent),
            AgentTool.getFunctionToolCallback(hotelAgent)
        )
        .build();

// 使用
Optional<OverAllState> result = supervisorAgent.invoke("帮我规划北京5日游");

7.3 模式对比

特性监督者模式(已弃用)Agent-as-Tool 模式
实现方式SupervisorAgent.builder()ReactAgent.builder().tools()
路由机制显式 JSON 路由LLM 自动工具选择
执行模式Hub-and-spoke 循环标准工具调用
子 Agent 返回返回监督者继续循环执行后返回结果
状态管理SUPERVISOR_NEXT_KEY标准工具调用状态
复杂度高低
可维护性中高

7.4 多智能体模式选择指南

根据官方文档,选择合适的多智能体模式:

需求场景推荐模式
集中式工作流控制AgentTool(工具调用)
Agent 直接与用户交互Handoffs(交接)
一次性路由决策LlmRoutingAgent(路由)
多步骤迭代路由AgentTool(循环工具调用)

7.5 迁移示例

旧代码(SupervisorAgent - 已弃用):

SupervisorAgent supervisor = SupervisorAgent.builder()
    .name("supervisor")
    .model(chatModel)
    .mainAgent(ReactAgent.builder()
        .name("main_agent")
        .systemPrompt("路由任务到 Agent...")
        .build())
    .subAgents(List.of(writerAgent, translatorAgent))
    .build();

新代码(Agent-as-Tool - 推荐):

ReactAgent supervisor = ReactAgent.builder()
    .name("supervisor")
    .model(chatModel)
    .instruction("使用工具来完成任务。")
    .tools(
        AgentTool.getFunctionToolCallback(writerAgent),
        AgentTool.getFunctionToolCallback(translatorAgent)
    )
    .build();

7.6 注释代码示例

在 TravelSupervisorPlanAgent.java 中,我们可以看到被注释掉的旧实现:

// 旧的实现方式(已被注释)
ReactAgent agent = ReactAgent.builder()
        .name("supervisor_agent")
        .model(chatModel)
        .systemPrompt("你是一个旅行规划监督者...")
        .saver(new MemorySaver())
        .tools(
            AgentTool.getFunctionToolCallback(attractionAgent.agent()),
            AgentTool.getFunctionToolCallback(hotelAgent.agent()),
            AgentTool.getFunctionToolCallback(transportAgent.agent())
        )
        .build();

7.7 相关资源

8. 总结与扩展

8.1 核心要点总结

L09-6.png
L09-6.png
  1. 监督者模式:通过中心化的协调器来管理多个专家 Agent
  2. JSON 路由:监督者通过输出 JSON 数组来决定下一步调用哪个专家
  3. Agent 依赖:专家 Agent 之间可以存在依赖关系
  4. 流式输出:通过 SSE 实现实时的进度展示
  5. 框架演进:从监督者模式到 Agent-as-Tool 模式的演进

8.2 使用体验

从实际的测试体验来看,监督者模式的不可控性远高于前面的串行/并行/路由交接策略,比如上面实现的旅游行程规划agent,虽然我希望它按照现制定计划,再制定行程、住宿的方式来,但是实际情况可能并不总如我的预期。然后简单的使用官方示例中的Agent as Tool的方式来实现,发现效果好像也一般。有可能是使用姿势的问题,接下来会重点使用官方推荐的案例,重新设计下这个agent,看看能否调教的满足预期🥲

题外话:对于业务属性较高的场景,这种不可控性通常是不太能接受的。而大模型的开发中,与传统的开发中,这种不可控性被放大了很多,对于程序员而言,如何解决这些好像也成了我们不得不考虑的问题。从这个角度来看,使用流程相对固定的工作流的方案,可能会更容易被业务方接受、也更容易达成预期。


本教程基于 SpringAI Alibaba 框架,展示了监督者策略在多智能体系统中的应用。虽然最新版本已经移除了监督者模式,但理解其原理对于掌握多智能体协作仍然非常重要。

附录:完整代码清单

项目源码:https://github.com/liuyueyi/spring-ai-demoopen in new window

完整的项目代码可在 ali/L08-multi-agent-supervisor 目录中找到,包括:

  • 后端 Java 代码(4 个 Agent + 1 个 Controller)
  • 前端模板(travel-plan.html)
  • 配置文件(application.yml)
  • Maven 配置(pom.xml)

Author: 一灰 Date: 2026-03-23 Tags: #SpringAI, #多智能体, #监督者策略, #旅游规划

Loading...