Spring AI Alibaba StateGraph 多Agent协作全解：5种编排模式

前言

当业务流程涉及多个角色、多个环节时，单 Agent 的能力就不够了，需要多个 Agent 分工协作。做企业多Agent开发，最常遇到3个问题：

1. 多Agent有哪些经典的协作编排模式？

2. 每种模式适合什么业务场景？

3. 如何基于 Spring AI Alibaba StateGraph 写出可直接运行的Java代码？

本文一次性讲清5种主流原生编排模式：Sequential串行流水线、Supervisor主管模式、Parallel并行扇入扇出、Router智能路由、Peer-to-Peer对等协作。

每个模式统一结构：核心特点、适用场景、完整可运行代码、优缺点。

文末补充Handoff、GroupChat、Human-in-the-loop等扩展能力，全部基于研发场景统一示例，方便对比理解。

底层核心：Spring AI Alibaba StateGraph 统一维护全局共享State，支持固定边、条件边、并行分支、循环回退、暂停人工介入，是Java生态企业级多Agent工作流的核心引擎。

---

一、Sequential Pipeline 串行流水线模式

核心特点

• 执行顺序预先固定，单向流转，上一个Agent输出存入全局State，作为下一个Agent输入；
• 底层是StateGraph语法糖，自动构建无分支直线图；
• 无动态路由、无分支选择。

适用场景

强依赖线性流程：需求→PRD→编码→测试、文稿起草→校验→润色、数据采集→清洗→统计。

完整代码

import com.alibaba.cloud.ai.graph.agent.ReactAgent;
import com.alibaba.cloud.ai.graph.agent.flow.agent.SequentialAgent;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.stereotype.Service;

@Service
public class DevTeamSequentialAgentDemo {

    private final ReactAgent productAgent;
    private final ReactAgent devAgent;
    private final ReactAgent testAgent;
    private final SequentialAgent pipelineAgent;

    public DevTeamSequentialAgentDemo(ChatModel chatModel) {
        productAgent = ReactAgent.builder()
                .name("ProductAgent")
                .model(chatModel)
                .description("产品经理，负责需求拆解，输出PRD文档")
                .instruction("你是资深产品经理。根据用户原始需求，输出一份规范PRD。" +
                        "包含：业务目标、功能清单、输入输出、边界约束。" +
                        "输入内容：{input}")
                .maxIterations(3)
                .outputKey("prd")
                .build();

        devAgent = ReactAgent.builder()
                .name("DevAgent")
                .model(chatModel)
                .description("后端开发工程师，阅读PRD，设计接口，输出Java伪代码")
                .instruction("你是Java后端开发，根据PRD文档{prd}，输出接口定义+核心代码，标注风险点。")
                .maxIterations(3)
                .outputKey("code")
                .build();

        testAgent = ReactAgent.builder()
                .name("TestAgent")
                .model(chatModel)
                .description("测试工程师，根据PRD+代码，编写测试用例并分析潜在缺陷")
                .instruction("你是测试工程师，PRD：{prd}，代码：{code}。输出：功能用例、边界用例、潜在缺陷清单。")
                .maxIterations(3)
                .outputKey("testReport")
                .build();

        pipelineAgent = SequentialAgent.builder()
                .name("DevPipeline")
                .agents(productAgent, devAgent, testAgent)
                .build();
    }

    public String runPipeline(String userRequirement) {
        var resultState = pipelineAgent.call(userRequirement);
        String prd = resultState.value("prd");
        String code = resultState.value("code");
        String testReport = resultState.value("testReport");

        System.out.println("==== PRD ====\n" + prd);
        System.out.println("\n==== 开发代码 ====\n" + code);
        System.out.println("\n==== 测试报告 ====\n" + testReport);
        return testReport;
    }
}

优缺点

✅ 优点：逻辑简单、调试方便、状态流转清晰

❌ 缺点：串行耗时叠加，前置节点失败整条链路阻塞；不支持自动返工回退

---

二、Supervisor 主管调度模式（主子模式）

核心特点

• 独立主管Agent作为中央决策者，LLM动态判断路由；
• 子Agent执行完返回结果给主管，由主管决定下一步：继续分发、回退重试、结束；
• 基于StateGraph条件边实现循环、回退；JManus/OpenManus均采用该架构。

适用场景

复杂开放任务、需要迭代返工的流程：研发迭代流水线、多轮方案优化、任务拆解分发。

完整代码

import com.alibaba.cloud.ai.graph.CompiledGraph;
import com.alibaba.cloud.ai.graph.StateGraph;
import com.alibaba.cloud.ai.graph.agent.ReactAgent;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.stereotype.Service;

import java.util.Map;
import java.util.function.Function;

@Service
public class DevTeamSupervisorStateGraphDemo {

    private final ReactAgent productAgent;
    private final ReactAgent devAgent;
    private final ReactAgent testAgent;
    private final ReactAgent supervisorAgent;
    private final CompiledGraph graph;

    public DevTeamSupervisorStateGraphDemo(ChatModel chatModel) {
        productAgent = ReactAgent.builder()
                .name("ProductAgent")
                .model(chatModel)
                .instruction("你是资深产品经理，根据需求输出PRD。输入：{input}")
                .maxIterations(2)
                .outputKey("prd")
                .build();

        devAgent = ReactAgent.builder()
                .name("DevAgent")
                .model(chatModel)
                .instruction("根据PRD{prd}，输出Java接口和代码。")
                .maxIterations(2)
                .outputKey("code")
                .build();

        testAgent = ReactAgent.builder()
                .name("TestAgent")
                .model(chatModel)
                .instruction("根据PRD{prd}、代码{code}输出测试报告，标记是否存在严重bug。")
                .maxIterations(2)
                .outputKey("testReport")
                .build();

        supervisorAgent = ReactAgent.builder()
                .name("SupervisorAgent")
                .model(chatModel)
                .instruction("""
                        你是研发项目主管，读取当前state，选择下一步执行节点：
                        可选节点：product、dev、test、end。
                        规则：
                        1. 没有prd → product
                        2. 有prd无code → dev
                        3. 有prd+code，测试报告标记严重bug → dev
                        4. 有prd+code，测试无严重bug → end
                        只输出节点名称，不要多余文字。
                        """)
                .maxIterations(2)
                .outputKey("nextNode")
                .build();

        StateGraph graphBuilder = new StateGraph();
        graphBuilder.addNode("supervisor", (Function<Map<String, Object>, Map<String, Object>>) state -> {
            var res = supervisorAgent.call(state);
            return res;
        });
        graphBuilder.addNode("product", state -> productAgent.call(state));
        graphBuilder.addNode("dev", state -> devAgent.call(state));
        graphBuilder.addNode("test", state -> testAgent.call(state));

        graphBuilder.setEntryPoint("supervisor");
        graphBuilder.addConditionalEdge("supervisor", state -> {
            String next = (String) state.get("nextNode");
            return next;
        });
        graphBuilder.addEdge("product", "supervisor");
        graphBuilder.addEdge("dev", "supervisor");
        graphBuilder.addEdge("test", "supervisor");
        graphBuilder.addEndNode("end");

        this.graph = graphBuilder.compile();
    }

    public Map<String, Object> runPipeline(String userReq) {
        return graph.invoke(Map.of("input", userReq));
    }
}

优缺点

✅ 优点：灵活，支持循环、回退、动态任务分配，企业落地最多

❌ 缺点：主管节点单点压力，必须配置最大轮次，防止无限循环

---

三、Parallel 扇入扇出 Fan-out/Fan-in 并行模式

核心特点

• 同一个输入同时分发给多个独立Agent并行执行；
• 所有分支全部执行完成之后，才进入汇总节点做结果合并、冲突消歧；
• Spring AI Alibaba 提供 ParallelAgent 开箱即用。

适用场景

多专家并行评审、多维度评估、多路信息检索、多方案并行设计。

示例：需求出来后，同时交给架构、安全、测试三个专家并行评估，最后汇总评审结论。

完整代码

import com.alibaba.cloud.ai.graph.agent.ReactAgent;
import com.alibaba.cloud.ai.graph.agent.flow.agent.ParallelAgent;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.stereotype.Service;

@Service
public class DevTeamParallelAgentDemo {

    private final ReactAgent archAgent;
    private final ReactAgent securityAgent;
    private final ReactAgent testReviewAgent;
    private final ReactAgent summaryAgent;
    private final ParallelAgent parallelAgent;

    public DevTeamParallelAgentDemo(ChatModel chatModel) {
        // 架构评审Agent
        archAgent = ReactAgent.builder()
                .name("ArchAgent")
                .model(chatModel)
                .instruction("你是架构师，基于需求{input}做架构可行性评估，输出架构风险。")
                .maxIterations(2)
                .outputKey("archReview")
                .build();
        // 安全评审Agent
        securityAgent = ReactAgent.builder()
                .name("SecurityAgent")
                .model(chatModel)
                .instruction("你是安全工程师，基于需求{input}做安全风险评估。")
                .maxIterations(2)
                .outputKey("securityReview")
                .build();
        // 测试预评审Agent
        testReviewAgent = ReactAgent.builder()
                .name("TestReviewAgent")
                .model(chatModel)
                .instruction("你是测试专家，基于需求{input}评估测试难点。")
                .maxIterations(2)
                .outputKey("testReview")
                .build();
        // 汇总Agent
        summaryAgent = ReactAgent.builder()
                .name("SummaryAgent")
                .model(chatModel)
                .instruction("合并架构评审{archReview}、安全评审{securityReview}、测试评审{testReview}，消除冲突，输出统一评审结论。")
                .maxIterations(2)
                .outputKey("finalSummary")
                .build();

        // 并行编排：三个专家同时跑，全部完成后交给汇总Agent
        parallelAgent = ParallelAgent.builder()
                .name("ReqReviewParallel")
                .forkAgents(archAgent, securityAgent, testReviewAgent)
                .joinAgent(summaryAgent)
                .build();
    }

    public String runReview(String userRequirement) {
        var state = parallelAgent.call(userRequirement);
        System.out.println("==== 架构评审 ====\n" + state.value("archReview"));
        System.out.println("==== 安全评审 ====\n" + state.value("securityReview"));
        System.out.println("==== 测试评审 ====\n" + state.value("testReview"));
        System.out.println("==== 汇总结论 ====\n" + state.value("finalSummary"));
        return state.value("finalSummary");
    }
}

优缺点

✅ 优点：充分利用并发，缩短总耗时，适合多方独立评估

❌ 缺点：分支之间不能互相依赖；汇总节点需要处理观点冲突

---

四、Router 智能路由模式（LLM路由）

核心特点

• 路由Agent根据输入，只选择一个匹配的专家Agent执行，不会全部执行；
• 框架内置 LlmRoutingAgent，自动分类、分发；
• 一次请求只走一条分支。

适用场景

工单分流、智能客服：退款、换货、技术咨询自动分发到对应专项Agent；需求自动归类到后端/前端/数据团队。

完整代码

import com.alibaba.cloud.ai.graph.agent.ReactAgent;
import com.alibaba.cloud.ai.graph.agent.flow.agent.LlmRoutingAgent;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.stereotype.Service;

@Service
public class DevTeamRouterAgentDemo {

    private final ReactAgent backendAgent;
    private final ReactAgent frontendAgent;
    private final ReactAgent dataAgent;
    private final LlmRoutingAgent routingAgent;

    public DevTeamRouterAgentDemo(ChatModel chatModel) {
        backendAgent = ReactAgent.builder()
                .name("BackendAgent")
                .model(chatModel)
                .instruction("你是后端开发，处理后端接口、数据库相关需求：{input}")
                .maxIterations(2)
                .outputKey("backendResult")
                .build();

        frontendAgent = ReactAgent.builder()
                .name("FrontendAgent")
                .model(chatModel)
                .instruction("你是前端开发，处理页面、交互需求：{input}")
                .maxIterations(2)
                .outputKey("frontendResult")
                .build();

        dataAgent = ReactAgent.builder()
                .name("DataAgent")
                .model(chatModel)
                .instruction("你是数据开发，处理报表、统计、数据同步需求：{input}")
                .maxIterations(2)
                .outputKey("dataResult")
                .build();

        // LLM路由：根据输入自动选择其中一个Agent
        routingAgent = LlmRoutingAgent.builder()
                .name("ReqRouter")
                .model(chatModel)
                .description("根据需求内容，选择合适的开发专家处理")
                .candidateAgents(backendAgent, frontendAgent, dataAgent)
                .build();
    }

    public String routeAndRun(String userRequirement) {
        var state = routingAgent.call(userRequirement);
        // 路由只会命中其中一个key
        if (state.value("backendResult") != null) {
            return state.value("backendResult");
        } else if (state.value("frontendResult") != null) {
            return state.value("frontendResult");
        } else if (state.value("dataResult") != null) {
            return state.value("dataResult");
        }
        return "未匹配到对应专家";
    }
}

优缺点

✅ 优点：请求精准分流，减少不必要Agent调用，节省token

❌ 缺点：依赖LLM分类准确率；不适合一个需求同时需要多个专家

---

五、Peer-to-Peer P2P 对等协作模式

核心特点

• 无中心主管，所有Agent地位平等；
• State维护全局messages消息池，Agent轮流发言、追加观点；
• 由LLM自主判断下一个发言者，循环直到达成共识或到达最大轮次。

适用场景

头脑风暴、方案辩论、圆桌评审、多方自由研讨。

完整代码

import com.alibaba.cloud.ai.graph.CompiledGraph;
import com.alibaba.cloud.ai.graph.StateGraph;
import com.alibaba.cloud.ai.graph.agent.ReactAgent;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.stereotype.Service;

import java.util.ArrayList;
import java.util.Map;
import java.util.function.Function;

@Service
public class DevTeamP2PAgentDemo {

    private final ReactAgent productAgent;
    private final ReactAgent devAgent;
    private final ReactAgent testAgent;
    private final CompiledGraph graph;
    private static final int MAX_ROUND = 5;

    public DevTeamP2PAgentDemo(ChatModel chatModel) {
        productAgent = ReactAgent.builder()
                .name("ProductAgent")
                .model(chatModel)
                .instruction("你是产品，基于历史对话{messages}发表你的观点，推动方案讨论。")
                .maxIterations(2)
                .outputKey("content")
                .build();

        devAgent = ReactAgent.builder()
                .name("DevAgent")
                .model(chatModel)
                .instruction("你是开发，基于历史对话{messages}评估实现难度，发表观点。")
                .maxIterations(2)
                .outputKey("content")
                .build();

        testAgent = ReactAgent.builder()
                .name("TestAgent")
                .model(chatModel)
                .instruction("你是测试，基于历史对话{messages}提出测试风险。")
                .maxIterations(2)
                .outputKey("content")
                .build();

        // 发言调度Agent：选择下一个发言角色，判断是否达成共识
        ReactAgent speakerSelector = ReactAgent.builder()
                .name("SpeakerSelector")
                .model(chatModel)
                .instruction("""
                        读取对话历史messages，选择下一个发言节点：product / dev / test / end。
                        如果各方达成共识，输出end；否则输出下一个发言者。只输出节点名。
                        """)
                .maxIterations(2)
                .outputKey("nextSpeaker")
                .build();

        StateGraph graphBuilder = new StateGraph();
        graphBuilder.addNode("selector", state -> {
            var res = speakerSelector.call(state);
            return res;
        });
        graphBuilder.addNode("product", state -> {
            var res = productAgent.call(state);
            appendMessage(state, "ProductAgent", res.value("content"));
            return state;
        });
        graphBuilder.addNode("dev", state -> {
            var res = devAgent.call(state);
            appendMessage(state, "DevAgent", res.value("content"));
            return state;
        });
        graphBuilder.addNode("test", state -> {
            var res = testAgent.call(state);
            appendMessage(state, "TestAgent", res.value("content"));
            return state;
        });

        graphBuilder.setEntryPoint("selector");
        graphBuilder.addConditionalEdge("selector", state -> {
            String next = (String) state.get("nextSpeaker");
            // 轮次超限强制结束
            int round = (Integer) state.getOrDefault("round", 0);
            if (round >= MAX_ROUND) return "end";
            return next;
        });
        graphBuilder.addEdge("product", "selector");
        graphBuilder.addEdge("dev", "selector");
        graphBuilder.addEdge("test", "selector");
        graphBuilder.addEndNode("end");

        this.graph = graphBuilder.compile();
    }

    private void appendMessage(Map<String, Object> state, String who, String content) {
        @SuppressWarnings("unchecked")
        ArrayList<String> messages = (ArrayList<String>) state.getOrDefault("messages", new ArrayList<>());
        messages.add(who + "：" + content);
        state.put("messages", messages);
        int round = (Integer) state.getOrDefault("round", 0);
        state.put("round", round + 1);
    }

    public Map<String, Object> runDiscussion(String userReq) {
        return graph.invoke(Map.of(
                "input", userReq,
                "messages", new ArrayList<String>(),
                "round", 0
        ));
    }
}

优缺点

✅ 优点：去中心化，自由辩论，适合创意研讨

❌ 缺点：流程不可控，容易发散、难以收敛，生产业务落地偏少

---

六、扩展能力（企业生产补充）

1. Handoff 智能交接模式

控制权直接在Agent之间移交，用户持续和当前Agent对话。

• Supervisor：子Agent是工具，不直接对接用户
• Handoff：对话上下文一起移交，用户直接和新Agent沟通
• 场景：售前→售后→技术支持转接

2. GroupChat 群聊模式

P2P的增强版，增加主持人角色，管控发言顺序，避免抢话，适合正式评审会。

3. Human-in-the-loop 人工介入

StateGraph原生支持节点暂停，等待人工审批，审批通过后继续执行；支持断点续跑。

场景：金融放款、合同审核、高危操作，满足合规。

---

七、五大模式选型对照表

编排模式	核心架构	执行顺序	能否循环回退	首选业务场景
Sequential 串行流水线	直线DAG	固定单向	❌	线性固定流程：需求→编码→测试、文档流水线
Supervisor 主管调度	带条件边图	LLM动态调度	✅	复杂迭代任务、研发流水线、多轮优化
Parallel 并行扇入扇出	多分支并行+汇总	多分支同时执行	❌	多专家并行评审、多维度评估
Router 智能路由	分类分流	单选分支	❌	工单分流、客服自动分发
P2P对等协作	去中心化消息池	自主轮流发言	✅	头脑风暴、方案辩论圆桌讨论

---

八、总结

1. 简单固定流程 → Sequential；

2. 需要迭代、返工、复杂开放任务 → Supervisor（企业最常用）；

3. 多专家独立评估、并行评审 → Parallel；

4. 工单、咨询分流 → Router；

5. 自由研讨、辩论 brainstorm → P2P；

6. 跨角色对话转接看Handoff，合规审批开启Human-in-the-loop。

Spring AI Alibaba StateGraph 一套引擎统一支撑5种编排，基于全局State管理状态，Java团队做企业多Agent落地非常友好。