10.基于 Spring AI Alibaba SubAgent监督者策略实现旅游规划智能体

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

把ReactAgent当工具用?Spring AI Alibaba 监督者模式实现智能旅游规划

L10-cover.png
L10-cover.png

1. 引言

前面的几篇分别介绍四种不同的多智能体交接策略,有串行、并行、路由、监督者策略的,在前一篇多智能体实战 | Spring AI Alibaba 监督者交接策略实现旅游行程规划智能体open in new window中,也提到了在SpringAI alibaba的最新版本中,移除了SupervisorAgent,推荐使用AgentAsTool的方式来实现。因此接下来这一篇将介绍如何将ReactAgent作为工具来交接给主Agent使用

SpringAI Alibaba框架提供了Sub Agent机制,允许我们将多个专业化的Agent组合在一起,通过一个监督者Agent来协调调度,实现任务的分工与协作。

本文将以一个旅游规划智能体为例,详细介绍如何使用Sub Agent实现监督者策略,并解决官方AgentTool因为同步阻塞的调用方式,从而导致的无法流式输出响应给前端的问题。

我们这里的设计目标,依然是沿用上篇文章中提到的《旅游行程规划智能体》

2. Sub Agent 实现方式

2.1 什么是Sub Agent

Sub Agent是一种多智能体协作模式,核心思想是:

  • 监督者Agent:负责理解用户需求,协调调度各个专家Agent
  • 专家Agent:专注于特定领域的任务执行(如景点推荐、住宿规划、交通安排)
  • 工具注入:将专家Agent作为Tool注册到监督者Agent中

2.2 官方Agent Tool支持

SpringAI Alibaba官方提供了Agent Tool支持,可以将ReactAgent作为Tool注入到另一个Agent中。详细参考:Agent Tool官方文档open in new window

基本用法:

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

// 创建专家Agent
ReactAgent expertAgent = ReactAgent.builder()
    .name("expert_agent")
    .model(chatModel)
    .description("专家Agent的描述")
    .systemPrompt("你是一个专业领域的专家...")
    .build();

// 创建监督者Agent,将专家Agent作为Tool注入
ReactAgent supervisorAgent = ReactAgent.builder()
    .name("supervisor_agent")
    .model(chatModel)
    .systemPrompt("你是监督者,负责协调专家...")
    .tools(AgentTool.create(expertAgent))  // 将专家Agent作为Tool
    .build();

2.3 Sub Agent的工作流程

L10-1.png
L10-1.png
用户请求
    ↓
监督者Agent(理解需求,制定计划)
    ↓
调用专家Agent Tool
    ├─→ 专家Agent 1(景点推荐)
    ├─→ 专家Agent 2(住宿规划)
    └─→ 专家Agent 3(交通安排)
    ↓
监督者Agent(整合结果,输出方案)

3. 旅游规划智能体实现

基于Sub Agent机制,我们实现了一个旅游规划智能体系统。该系统包含一个监督者Agent和三个专家Agent。

3.1 系统架构

L10-2.png
L10-2.png
┌─────────────────────────────────────────────────────────┐
│                    用户请求                              │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│              TravelSupervisorPlanAgent                   │
│                  (监督者Agent)                          │
│                                                         │
│  职责:理解用户需求,协调专家Agent,整合最终方案          │
│                                                         │
│  工具列表:                                              │
│  ├─ AgentTool.create(attractionAgent)                   │
│  ├─ AgentTool.create(hotelAgent)                        │
│  └─ AgentTool.create(transportAgent)                    │
└─────────────────────────────────────────────────────────┘
        ↓                   ↓                   ↓
┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│AttractonAgent │  │  HotelAgent   │  │TransportAgent │
│  景点推荐专家  │  │  住宿推荐专家  │  │  交通规划专家  │
└───────────────┘  └───────────────┘  └───────────────┘

3.2 专家Agent实现

每个专家Agent都是独立的ReactAgent,拥有自己的系统提示和职责:

景点推荐专家:

@Component
public class AttractionAgent {
    private final ChatModel chatModel;

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

住宿推荐专家:

@Component
public class HotelAgent {
    private final ChatModel chatModel;

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

交通规划专家:

@Component
public class TransportAgent {
    private final ChatModel chatModel;

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

3.3 监督者Agent实现

监督者Agent负责协调各个专家,通过工具调用的方式调度子Agent:

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

    public Agent agent(String sessionId) {
        ReactAgent agent = ReactAgent.builder()
                .name("supervisor_agent")
                .model(chatModel)
                .systemPrompt("""
                        你是一个旅行规划监督者,你的任务是帮助用户制定旅行计划。
                        你可以协调以下专家:
                        - attraction_agent:负责推荐景点、安排游览路线。
                        - transport_agent:负责规划城市间交通和市内交通。
                        - hotel_agent:负责推荐酒店、民宿等住宿。

                        请记得在制定计划时,始终先调用 attraction_agent 来推荐景点、安排旅游路线;
                        然后再根据推荐的景点来调用 transport_agent 和 hotel_agent,用于规划行程和住宿情况。
                        最后需要将所有的专家输出的内容进行重新组织整合,输出完整的方案给用户。
                        """)
                .saver(new MemorySaver())
                .tools(
                    AgentTool.create(attractionAgent.agent()),
                    AgentTool.create(hotelAgent.agent()),
                    AgentTool.create(transportAgent.agent())
                )
                .build();
        return agent;
    }
}

4. AgentAsTool同步调用的问题

4.1 官方实现的局限性

当我们使用官方提供的AgentTool.create()将子Agent作为Tool时,会遇到一个关键问题:同步阻塞调用。

查看官方AgentTool的实现,我们可以看到它是采用 invoke(xxx) 的方式执行的,这种同步执行subAgent的方案倒也没有什么问题,但是对于我们前端需要获取子Agent的流式输出时,就不太友好了(特别是子Agent的执行耗时较长时,傻等着就显得有点呆了🤣)

public AssistantMessage executeAgent(String input, ToolContext toolContext) {
    // Extract the actual input value from the wrapped JSON structure
    // The input parameter is wrapped as {"input": "actual_value"}
    String actualInput = extractInputValue(input);

    // Build the messages list to add
    // Add instruction first if present, then the user input
    // Note: We must add all messages at once because cloneState doesn't copy keyStrategies,
    // so multiple updateState calls would overwrite instead of append
    List<Message> messagesToAdd = new ArrayList<>();
    if (StringUtils.hasLength(agent.instruction())) {
        messagesToAdd.add(AgentInstructionMessage.builder().text(agent.instruction()).build());
    }
    messagesToAdd.add(new UserMessage(actualInput));

    // 官方的核心实现,这里是同步的调用方式
    Optional<OverAllState> resultState = agent.getAndCompileGraph().invoke(Map.of("messages", messagesToAdd));

    Optional<List> messages = resultState.flatMap(overAllState -> overAllState.value("messages", List.class));
    if (messages.isPresent()) {
        @SuppressWarnings("unchecked")
        List<Message> messageList = (List<Message>) messages.get();
        // Use messageList
        return (AssistantMessage) messageList.get(messageList.size() - 1);
    }
    
    throw new RuntimeException("Failed to execute agent tool or failed to get agent tool result");
}

4.2 问题分析

这种同步阻塞方式导致了几个问题:

问题影响
无法流式输出子Agent的执行过程无法实时传递给前端
用户体验差用户只能看到"加载中",无法了解进度
丢失中间结果子Agent的思考过程、工具调用过程都丢失了
响应时间长需要等待所有子Agent完成才能返回

4.3 前端体验对比

L10-3.png
L10-3.png

使用官方AgentTool(同步阻塞):

用户点击"开始规划"
    ↓
等待...(无反馈)
    ↓
等待...(无反馈)
    ↓
突然显示完整结果

理想的流式输出体验:

用户点击"开始规划"
    ↓
"正在为您推荐景点..."
    ↓
景点推荐内容逐步显示...
    ↓
"正在为您规划住宿..."
    ↓
住宿推荐内容逐步显示...
    ↓
"正在为您安排交通..."
    ↓
完整方案呈现

5. 自定义AgentTool实现流式输出

为了解决官方AgentTool的同步阻塞问题,我们实现了自定义的AgentTool,核心改进是支持将子Agent的流式输出实时转发给前端。

5.1 整体思路

子Agent流式输出 → PlanContext → SSE → 前端实时显示

关键点:

  1. 在Controller层建立SSE连接时,将连接存储到PlanContext
  2. 自定义AgentTool在执行子Agent时,从PlanContext获取SSE连接
  3. 将子Agent的流式输出实时推送到前端

5.2 PlanContext实现

PlanContext用于管理SSE连接,支持按sessionId存储和获取:

public class PlanContext {
    private static InheritableThreadLocal<FluxSink> context = new InheritableThreadLocal<>();
    private static Map<String, FluxSink> sessionEmitter = new ConcurrentHashMap<>();

    public static void set(FluxSink sink) {
        context.set(sink);
    }

    public static FluxSink get() {
        return context.get();
    }

    public static void setSessionEmitter(String sessionId, FluxSink sink) {
        sessionEmitter.put(sessionId, sink);
    }

    public static FluxSink getSessionEmitter(String sessionId) {
        return sessionEmitter.get(sessionId);
    }

    public static void removeSessionEmitter(String sessionId) {
        sessionEmitter.remove(sessionId);
    }
}

5.3 自定义AgentTool实现

自定义AgentTool的核心改进在于执行子Agent时,将流式输出实时转发:

@Slf4j
public class AgentTool {
    private static final ToolCallResultConverter CONVERTER = new MessageToolCallResultConverter();

    public static ToolCallback create(ReactAgent agent) {
        // 使用反射获取Agent的输入Schema
        String originalSchema = getInputSchemaFromAgent(agent);
        
        // 构建工具定义
        DefaultToolDefinition.Builder builder = ToolDefinitions
                .builder(method)
                .name(agent.name())
                .description(agent.description());
        
        if (StringUtils.hasLength(originalSchema)) {
            String wrappedInputSchema = wrapSchemaInInputParameter(originalSchema);
            builder.inputSchema(wrappedInputSchema);
        }
        
        ToolDefinition toolDefinition = builder.build();
        AgentToolExecutor executor = new AgentToolExecutor(agent);
        
        return MethodToolCallback.builder()
                .toolDefinition(toolDefinition)
                .toolMethod(method)
                .toolObject(executor)
                .toolCallResultConverter(CONVERTER)
                .build();
    }
}

5.4 AgentToolExecutor核心逻辑

AgentToolExecutor是执行子Agent的核心,实现了流式输出的转发:

public static class AgentToolExecutor {
    private final ReactAgent agent;

    public AgentToolExecutor(ReactAgent agent) {
        this.agent = agent;
    }

    public AssistantMessage executeAgent(String input, ToolContext toolContext) {
        String actualInput = extractInputValue(input);
        
        // 构建消息列表
        List<Message> messagesToAdd = new ArrayList<>();
        if (StringUtils.hasLength(agent.instruction())) {
            messagesToAdd.add(AgentInstructionMessage.builder()
                    .text(agent.instruction()).build());
        }
        messagesToAdd.add(new UserMessage(actualInput));
        
        // 获取Graph
        var graph = agent.getAndCompileGraph();
        
        // 从ToolContext获取sessionId
        final String sessionId = (String) toolContext.getContext().get("sessionId");

        // 流式调用子Agent
        Flux<NodeOutput> outputFlux = graph.stream(Map.of("messages", messagesToAdd));
        
        // 处理流式输出,实时转发给前端
        NodeOutput lastOutput = outputFlux.map(nodeOutput -> {
            String node = nodeOutput.node();
            String agentName = agent.name();

            log.info("【子Agent执行】收到节点输出 - node: {}, agent: {}", node, agentName);

            // 构建响应数据
            Map<String, Object> data = new HashMap<>();
            data.put("node", node);
            data.put("agent", agentName);

            StringBuilder contentBuilder = new StringBuilder();
            boolean hasContent = false;

            // 提取内容
            if (nodeOutput instanceof StreamingOutput<?> streamingOutput) {
                Message message = streamingOutput.message();
                
                if (message instanceof AssistantMessage assistantMessage) {
                    if (assistantMessage.hasToolCalls()) {
                        // 工具调用
                        data.put("contentType", "tool_execute");
                        var toolCalls = assistantMessage.getToolCalls().get(0);
                        contentBuilder.append("\n[工具执行]:")
                                .append(toolCalls.name());
                        hasContent = true;
                    } else {
                        // 流式消息内容
                        String text = streamingOutput.message().getText();
                        if (text != null && !text.trim().isEmpty()) {
                            contentBuilder.append(text);
                            hasContent = true;
                            data.put("contentType", "delta");
                        }
                    }
                } else if (message instanceof ToolResponseMessage) {
                    data.put("contentType", "tool_complete");
                    contentBuilder.append("[工具执行完成]");
                    hasContent = true;
                }
            }

            data.put("content", contentBuilder.toString());
            data.put("hasContent", hasContent);
            data.put("stage", determineStage(agentName));

            // 关键:通过PlanContext获取SSE连接,实时推送数据
            FluxSink contextSink = PlanContext.getSessionEmitter(sessionId);
            if (contextSink != null) {
                String json = toJsonStr(data);
                contextSink.next(ServerSentEvent.<String>builder()
                        .event("message")
                        .data(json)
                        .build());
            }
            
            return nodeOutput;
        }).blockLast();  // 等待子Agent执行完成

        // 提取最终结果返回给监督者Agent
        OverAllState lastState = lastOutput != null ? lastOutput.state() : null;
        Optional<List> messages = Optional.ofNullable(lastState)
                .flatMap(state -> state.value("messages", List.class));
        
        if (messages.isPresent()) {
            List<Message> messageList = messages.get();
            return (AssistantMessage) messageList.get(messageList.size() - 1);
        }
        
        throw new RuntimeException("Failed to execute agent tool");
    }

    /**
     * 根据Agent名称确定阶段标识
     */
    private String determineStage(String agentName) {
        if (agentName != null) {
            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.5 Controller层实现

Controller负责建立SSE连接,并将连接存储到PlanContext:

@RestController
@RequestMapping("/api/travel")
public class TravelPlanController {
    private final TravelSupervisorPlanAgent travelSupervisorPlanAgent;

    @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) {

        String sessionId = UUID.randomUUID().toString();
        
        Agent supervisorAgent = travelSupervisorPlanAgent.agent(sessionId);
        
        // 构建用户请求
        String prompt = buildPrompt(destination, days, budget, preferences);
        
        RunnableConfig config = RunnableConfig.builder()
                .threadId("1")
                .addMetadata("sessionId", sessionId)
                .build();

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

        return Flux.create(sink -> {
            // 关键:将SSE连接存储到PlanContext
            PlanContext.set(sink);
            PlanContext.setSessionEmitter(sessionId, sink);
            
            // 异步处理Agent流
            CompletableFuture.runAsync(() -> {
                agentStream.subscribe(
                    nodeOutput -> {
                        // 处理监督者Agent的输出...
                    },
                    error -> {
                        log.error("流式规划过程中发生错误", error);
                        sink.next(buildErrorEvent(error));
                    },
                    () -> {
                        // 完成时清理
                        PlanContext.remove();
                        PlanContext.removeSessionEmitter(sessionId);
                    }
                );
            });
        });
    }
}

6. 数据流转详解

6.1 完整的数据流

L10-4.png
L10-4.png
用户输入
    ↓
Controller建立SSE连接
    ↓
PlanContext存储SSE连接 (sessionId → FluxSink)
    ↓
监督者Agent开始执行
    ↓
调用子Agent Tool
    ↓
自定义AgentToolExecutor执行子Agent
    ├─ 子Agent流式输出NodeOutput
    ├─ 从PlanContext获取SSE连接
    └─ 实时推送到前端
    ↓
前端接收SSE事件,更新UI

6.2 数据格式

前端接收的SSE数据格式:

{
  "node": "attraction_agent",
  "agent": "attraction_agent",
  "stage": "attraction",
  "contentType": "delta",
  "content": "推荐景点:黄鹤楼、东湖...",
  "hasContent": true
}
字段说明
node当前执行的节点名称
agent当前执行的Agent名称
stage阶段标识(attraction/hotel/transport/supervisor)
contentType内容类型(delta/tool_execute/tool_complete)
content具体内容
hasContent是否包含有效内容

7. 前端实现

前端使用EventSource API接收SSE数据,实现实时更新:

let eventSource = null;

function startPlanning() {
    const destination = document.getElementById('destination').value.trim();
    const days = document.getElementById('days').value || '3';
    
    // 建立SSE连接
    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);
        }
    });
}

// 内容累加器
const contentAccumulators = {
    attraction: '',
    hotel: '',
    transport: '',
    supervisor: ''
};

function updateStageContent(stage, content) {
    // 累加内容
    contentAccumulators[stage] += content;
    
    // 更新对应面板
    const contentElement = document.getElementById(stage + 'Content');
    if (contentElement) {
        contentElement.innerHTML = marked.parse(contentAccumulators[stage]);
        contentElement.scrollTop = contentElement.scrollHeight;
    }
}

实际效果演示:(启动项目后,访问 http://localhost:8080open in new window)

image.png
image.png

8. 总结

8.1 方案对比

对比项官方AgentTool自定义AgentTool
调用方式同步阻塞流式调用
输出支持仅最终结果实时流式输出
前端体验等待完成实时进度展示
实现复杂度简单中等
适用场景对实时性要求不高需要实时反馈

8.2 核心要点

L10-5.png
L10-5.png
  1. Sub Agent机制:通过将ReactAgent作为Tool注入监督者Agent,实现多智能体协作
  2. 自定义AgentTool:解决官方方案同步阻塞的问题,支持流式输出
  3. PlanContext:管理SSE连接,实现子Agent输出到前端的流式转发
  4. 实时反馈:提升用户体验,让用户了解AI的思考和执行过程

8.3 扩展方向

  • 支持动态加载专家Agent
  • 实现专家Agent的并行执行
  • 添加Agent执行超时控制
  • 支持Agent执行结果缓存

参考资料

文档名称链接
SpringAI Alibaba Agent Tool官方文档SpringAI Alibaba Agent Tool官方文档open in new window
ReactAgent API文档ReactAgent API文档open in new window
Server-Sent Events规范Server-Sent Events规范open in new window

附录:完整代码清单

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

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

  • 后端 Java 代码(4 个 Agent + 1 个 Controller + 1 个自定义AgentTool + PlanContext用于传递会话信息)
  • 前端模板(travel-plan.html)
  • 配置文件(application.yml)
  • Maven 配置(pom.xml)

作者: [一灰]
日期: 2026-03-25
Tags: #SpringAI, #Multi-Agent, #SubAgent, #监督者策略, #Alibaba, #Agent

Loading...