Spring AI Alibaba 1.x 系列【39】多智能体（Multi-agent）架构

文章目录1. 概述2. 两种模式2.1 Tool Calling 工具调用模式2.2 Handoffs 智能体交接模式2.3 如何选择3. Agent 文本指令3.1 description能力描述3.2 instruction行为指令3.2.1 AgentInstructionMessage3.2.2 Instruction 占位符3.3 systemPrompt 系统级指令4. 自定义 Agent 上下文5. 模式一智能体作为工具6. 模式二交接6.1 顺序执行智能体SequentialAgent6.2 并行执行智能体Parallel Agent6.3 循环智能体LoopAgent6.4 路由执行智能体LlmRoutingAgent 1. 概述多智能体Multi-agent将复杂的应用程序分解为多个协同工作的专业化Agent。与依赖单个Agent承载全量任务、全量工具、全量逻辑不同Multi-agent架构可以将更小、职责单一、高度专注的轻量化Agent组合为可编排、可协作、可路由的标准化工作流。单Agent架构核心痛点单个Agent挂载大量工具工具选择决策混乱、大模型幻觉严重全局上下文、对话记忆持续膨胀Token开销大、推理性能低业务职责臃肿耦合难以维护、迭代、横向扩展无法实现工具隔离、权限隔离、场景化资源管控多智能体适用场景单Agent工具过多模型无法精准决策上下文/历史记忆体量过大单Agent难以高效处理任务需要专业化分工规划Agent、检索Agent、审核Agent、计算Agent跨领域业务协作、多角色专家接力处理、复杂长链路流程2. 两种模式框架原生提供两种主流多智能体协作模式覆盖流程编排与拟人化对话两类场景。两大模式核心对比对比维度工具调用Agent Tool交接模式Handoffs控制模式集中式Supervisor 统一调度去中心化Agent 自主移交用户交互子Agent不直接对话仅返回结果交接后新Agent直接与用户交互对话能力有限适合固定任务流水线极强支持跨领域连续对话流程约束强固化、可编排、易管控弱约束、动态灵活、自适应流转上下文优化支持分层裁剪、工具隔离依赖returnReasoningContent做上下文瘦身典型组件SupervisorAgent、Flow顺序/并行编排会话级Agent、领域专属Agent最佳实践混合使用两种模式大领域切换使用「Handoffs交接」单个领域内部复杂子任务使用「Tool Calling子Agent调用」结合outputKey/includeContents实现安全、高效的跨节点数据流转。2.1 Tool Calling 工具调用模式工作原理Supervisor总管Agent将其他子Agent封装为工具进行调用子Agent仅执行专属任务、产出结果不直接对接用户。控制流集中式管控所有路由、调度、任务分发统一由Supervisor控制。适用场景固定结构化工作流、后台自动化任务、子任务拆解编排、权限集中管控。2.2 Handoffs 智能体交接模式工作原理当前活跃Agent自主判断业务边界主动将会话控制权全局状态移交至目标专业Agent交接完成后活动Agent自动切换用户直接与新Agent持续交互。控制流去中心化协作每个Agent具备自主决策能力可主动切换会话处理方无统一总管调度。适用场景跨领域自然对话、专家角色接力、开放式问答流转、人工介入接管。标准执行流程当前Agent判断自身能力边界判定需要其他专业Agent协助完整传递会话控制权 全局State状态 上下文至目标Agent新Agent成为活动节点直接响应用户对话循环往复新Agent可继续交接、或任务完成结束流程2.3 如何选择两种模式分工模式核心用途适用场景智能体交接 Handoffs会话主体切换完整移交对话控制权换人服务跨领域、专家转接、主角色变更、长会话接力工具调用 Agent Tool内部子任务调用不切换当前会话主体仅后台调用子能力数据查询、专项计算、原子化独立任务、临时能力复用整体思路选择判断问题工具调用 (Agent Tool)交接Handoffs需要集中控制工作流程✅ 是❌ 否希望Agent直接与用户交互❌ 否✅ 是专家之间复杂的、类人对话❌ 有限✅ 强你可以混合使用两种模式使用交接(Handoffs)做 Agent 整体身份切换同时每个Agent可把子智能体当作工具(Agent Tool)调用完成专属子任务。3. Agent 文本指令ReactAgent通过Builder提供3个文本指令字段分别控制不同层面的行为字段类型对应消息类型消息位置模板渲染典型用途descriptionString不直接生成 Message—否Agent 能力描述供 LLM 做路由/工具选择instructionStringAgentInstructionMessage列表末尾支持{{}}占位符Agent 行为指令告诉模型如何做systemPromptStringSystemMessage列表开头index0否系统级指令设置模型角色/上下文代码示例// Java专家Agent工具ReactAgentjavaExpertAgentReactAgent.builder().name(java_expert_agent).model(dashScopeChatModel).systemPrompt(你是资深Java后端架构师严格遵循Java编码规范与企业级最佳实践提供专业、严谨、可落地的技术方案。).description( Java技术专家工具专注于Java后端开发、代码审查、架构设计、Bug排查、性能优化 输出专业、规范、可直接运行的代码与解决方案遵循阿里Java开发手册 ).instruction( 你是专业的Java后端技术专家负责解答用户Java相关技术问题、生成高质量代码、排查Bug、优化程序。 要求 1. 代码必须规范、可编译、可运行 2. 遵循阿里巴巴Java开发手册异常、日志、命名严格标准化 3. 优先使用主流框架Spring Boot/Spring Cloud/MyBatis 4. 解释清晰重点突出不冗余技术严谨。 ).saver(newMemorySaver()).build();在消息列表中的最终顺序[0]SystemMessage(systemPrompt)← ReactAgent.systemPrompt[1]UserMessage(用户输入)← 调用时传入[2]AgentInstructionMessage(instruction)← ReactAgent.instruction经模板渲染3.1 description能力描述不参与LLM对话仅在Agent发现与路由阶段使用场景使用方式LlmRoutingAgent 路由决策LLM 根据name description选择子 AgentAgentTool 工具注册ToolCallback.description(agent.description())TaskTool 子 Agent 列表- name: description文本拼接// RoutingNode.java — LLM 路由时生成子 Agent 列表for(AgentsubAgent:subAgents){sb.append(- ).append(subAgent.name()).append(: ).append(subAgent.description()).append(\n);}// LLM 看到// - prose_writer_agent: 可以写散文。// - poem_writer_agent: 可以写现代诗。// → LLM 据此决定路由到哪个 Agent3.2 instruction行为指令参与 LLM 对话通过AgentInstructionMessage注入关键特征支持模板变量如{{role}}、{{skill}}运行时替换被outputSchema增强时自动转义大括号{→\{序列化ID为TEMPLATED_USER// InstructionAgentHook.beforeAgent() — 阶段 1 注入AgentInstructionMessageinstructionMessageAgentInstructionMessage.builder().text(reactAgent.instruction()).build();newMessages.add(instructionMessage);// 追加到列表末尾// AgentLlmNode.renderTemplatedUserMessage() — 阶段 2 模板渲染instructionMessage.mutate().text(renderPromptTemplate(textContent,processedParams))// {{role}} → 作家.rendered(true).build();3.2.1 AgentInstructionMessageSpring AI中定义了四种消息类型消息类型来源用途MessageTypeUserMessage用户输入 / 代码直接构造用户请求USERSystemMessageReactAgent.systemPrompt系统级指令SYSTEMAssistantMessageLLM 响应模型输出ASSISTANTToolResponseMessage工具执行结果工具返回TOOLSpring AI Alibaba中扩展了指令消息类型AgentInstructionMessage用于在消息流中包裹、传递Agent的instruction业务指令单实际对于大模型来说也属于USER类型本身只有四种只是Agent会进行区分。构造函数publicAgentInstructionMessage(StringtextContent,MapString,Objectmetadata,booleanrendered){super(MessageType.USER,textContent,metadata);this.renderedrendered;}和UserMessage对比说明同为MessageType.USERLLM端无法区分AgentInstructionMessage额外提供rendered标记支持模板引擎渲染AgentInstructionMessage支持mutate()不可变更新模板渲染后替换3.2.2 Instruction 占位符在Multi-agent系统中instruction支持使用占位符来动态引用状态中的数据。这是实现Agent之间数据传递的关键机制。支持的占位符占位符说明使用场景{input}用户原始输入第一个 Agent 接收用户问题{outputKey}引用其他 Agent 的输出第二个 Agent 读取第一个 Agent 的结果{stateKey}读取全局状态读取会话里的任意数据占位符工作原理你在instruction里写{xxx}框架执行Agent时自动替换从全局状态OverAllState里找对应的值替换成真实字符串传给AI最佳实践开发必看outputKey 必须有意义例如article、user_info、tool_result占位符必须与 outputKey 一致outputKey xxx 占位符 {xxx}一个 instruction 支持多个占位符请根据用户问题 {input}参考资料 {docs}分析结果 {result}值不存在时会保留原始 {xxx} 字符串示例写作智能体输出结果存在article中ReactAgentwriterAgentReactAgent.builder().name(writer).instruction(你是作家请根据用户问题创作文章{input}).outputKey(article)// 输出存在这里.build();评审智能体使用{article}读取上一个Agent的结果ReactAgentreviewerAgentReactAgent.builder().name(reviewer).instruction(请评审并修改文章\n{article}).outputKey(final_article).build();3.3 systemPrompt 系统级指令关键特征MessageType 为SYSTEMLLM侧作为系统指令处理不支持模板渲染纯字符串始终位于消息列表最前面最高优先级通过ModelRequest.systemMessage()注入// AgentLlmNode.apply()if(StringUtils.hasLength(this.systemPrompt)){requestBuilder.systemMessage(newSystemMessage(this.systemPrompt));}// appendSystemPromptIfNeeded() — 插入到消息列表头部if(modelRequest.getSystemMessage()!null){messages.add(0,modelRequest.getSystemMessage());// index0最前面}4. 自定义 Agent 上下文多智能体系统的核心控制每个Agent能看到什么信息。Spring AI Alibaba允许你精细控制给每个Agent看不同的历史消息给每个Agent传不同的状态数据给每个Agent定制不同的提示词给每个Agent自定义输入/输出格式控制是否给Agent看中间思考过程为什么上下文工程很重要因为信息太多 →Agent会混乱信息太少 → Agent 无法工作信息错误 →Agent回答跑偏5. 模式一智能体作为工具比较简单使用AgentTool转换为工具后添加到ReactAgent中即可AgentTool.getFunctionToolCallback(topicAgent)6. 模式二交接四大智能体对比特性顺序智能体SequentialAgent并行智能体ParallelAgent循环智能体LoopAgent路由智能体LlmRoutingAgent执行逻辑线性依次执行并发执行重复执行1个子智能体LLM决策路由到1个子智能体子智能体数量无限制2~10个仅1个多个候选池核心价值分步流程提升效率重试/遍历智能决策、统一入口动态工具场景分阶段切换工具多工具并行循环调用工具按路由场景加载工具定位流程执行性能优化迭代重试工作流大脑6.1 顺序执行智能体SequentialAgentFlowAgent的具体子类专门用于线性、按顺序执行子智能体的工作流场景将所有子智能体按照【添加的先后顺序】线性、依次执行无分支、无循环。在顺序执行模式中多个Agent按预定义的顺序依次执行Agent A处理初始输入Agent A的输出传递给Agent BAgent B处理并传递给Agent C最后一个Agent返回最终结果关键特性按顺序执行Agent按照subAgents列表中定义的顺序执行状态传递每个Agent的输出通过outputKey存储在状态中可被后续Agent访问消息历史默认情况下所有Agent共享消息历史推理内容控制使用returnReasoningContents控制是否在消息历史中包含中间推理6.2 并行执行智能体Parallel Agent在并行执行模式中多个Agent同时处理相同的输入。它们的结果被收集并合并。流程输入同时发送给所有Agent所有Agent并行处理结果被合并成单一输出6.3 循环智能体LoopAgent循环执行智能体继承自FlowAgent核心能力是按指定策略循环执行单个子智能体支持固定次数、条件判断、JSON数组遍历等多种循环模式。支持多种循环模式用于重复执行单个子智能体COUNT次数循环执行固定次数的循环CONDITION条件循环根据条件判断是否继续循环满足条件时终止循环结构类似do-whileJSON_ARRAY数组遍历解析 JSON 数组遍历数组内每个元素并执行子智能体自定义策略可实现LoopStrategy接口自行拓展自定义循环逻辑核心约束LoopAgent有且仅能配置一个子智能体该子智能体将在每一轮循环中重复执行。6.4 路由执行智能体LlmRoutingAgent 利用大模型的理解能力自动决策、智能路由到最合适的子智能体执行。核心功能基于大模型ChatModel理解用户意图自动从子智能体列表中路由到最匹配的子智能体执行支持兜底智能体路由失败时自动降级支持自定义系统提示词、路由指令灵活控制路由逻辑适用场景多场景智能体统一入口、意图识别、动态分支决策