Spring AI Multi-Agent 生产级实战：从原理、架构到高并发落地

Spring AI Multi-Agent 生产级实战：从原理、架构到高并发落地

一、先说结论：生产环境为什么要做 Multi-Agent

很多团队第一次做 AI 系统，直觉上会先做一个“万能 Agent”：

• 一个系统 Prompt
• 一组工具
• 一个模型入口
• 所有业务都往里塞

这个方案在 Demo 阶段很顺，但进入生产后会迅速暴露 4 个结构性问题：

所以，**Multi-Agent 并不是“为了高级而高级”，而是把大模型系统从 Prompt Demo 升级为可治理的软件系统。**

从架构视角看，Multi-Agent 的本质是 3 件事：

1. 职责拆分：让不同 Agent 只处理自己最擅长的领域。
2. 执行编排：把多个 Agent 串成有状态的业务流程。
3. 工程治理：对成本、延迟、故障、审计、扩容做系统化控制。

二、什么样的场景真正适合 Multi-Agent

不是所有 AI 需求都需要拆成多智能体。判断标准很简单：

2.1 适合 Multi-Agent 的场景

• 任务链路长：需要“理解意图 -> 检索 -> 执行工具 -> 汇总回复”
• 角色边界清晰：不同步骤需要不同 Prompt、工具集、模型策略
• 需要异步化：部分步骤耗时长，不能让用户一直同步等待
• 需要治理：希望按 Agent 粒度做限流、扩容、熔断、灰度
• 需要审计：必须知道“哪个 Agent 在什么时候做了什么决定”

2.2 不适合 Multi-Agent 的场景

• 单轮问答
• 工具数量很少，流程固定
• 没有明显职责边界
• 业务还处于试验阶段，优先验证价值而非过度架构

一个非常实用的经验是：

当一个 Agent 同时承担“规划、检索、执行、风控、总结”五类职责时，就该拆了。

三、企业级 Multi-Agent 的核心设计原则

要把 Multi-Agent 做成生产系统，建议遵循以下设计原则。

3.1 Agent 不是类，而是可治理的执行单元

在工程上，Agent 不应只是一个 chatClient.prompt().call() 的代码片段，而应该具备：

• 唯一身份：agentCode
• 明确职责：输入、输出、边界、依赖
• 独立治理：超时、重试、并发、熔断、限流
• 可观测：耗时、成功率、Token 用量、失败原因
• 可编排：能被工作流引擎或编排层调度

3.2 上下文必须分层

很多项目出问题，不是因为模型不够强，而是上下文管理混乱。建议把上下文拆成 4 层：

• userContext：用户本轮输入与用户画像
• conversationContext：会话历史摘要
• workflowContext：当前流程内的中间结果
• executionContext：超时、traceId、tokenBudget、tenantId 等运行信息

这样做有两个好处：

• 避免所有 Agent 都拿到全部上下文，减少 Token 浪费
• 让每个 Agent 只读取自己所需的最小上下文，降低幻觉和误操作概率

3.3 编排层必须独立于 Agent

不要把流程控制硬编码进某个 Agent 里。正确方式是：

• Agent 只负责“做事”
• Orchestrator 负责“决定谁在什么时候做什么”

否则后期一旦需要并行执行、失败补偿、流程回放、灰度切流，维护成本会非常高。

3.4 模型调用必须可替换

生产系统不能把业务逻辑直接绑定到某个具体模型厂商。要做到：

• Prompt 与模型参数配置化
• 模型路由抽象化
• 响应结构标准化
• 超时、重试、fallback 策略统一化

Spring AI 的价值就在这里，它把模型接入层标准化了，业务代码可以围绕 ChatClient、ChatModel、ToolCallback 展开，而不是深耕某一家 API 细节。

四、整体架构：从入口到执行再到治理

下面是一套更接近生产落地的参考架构。

┌────────────────────────────┐ │ API Gateway │ │ 鉴权 / 限流 / 灰度 / 审计 │ └─────────────┬──────────────┘ │ ┌─────────────▼──────────────┐ │ Session Coordinator │ │ 会话接入 / Trace / 配额控制 │ └─────────────┬──────────────┘ │ ┌───────────────────▼───────────────────┐ │ Agent Orchestrator │ │ 路由 / DAG / 状态机 / 重试 / 补偿 / SLA │ └───────┬──────────────┬───────────────┘ │ │ ┌──────────▼───────┐ ┌────▼─────────────┐ │ Planner Agent │ │ Policy Agent │ │ 任务规划 / 路由 │ │ 风控 / 审批 / 规则 │ └──────────┬───────┘ └────┬─────────────┘ │ │ ┌──────────────────▼──────────────▼─────────────────┐ │ Domain Agents │ │ RAG Agent / Tool Agent / SQL Agent / Summary Agent │ └────────────┬─────────────┬─────────────┬──────────┘ │ │ │ ┌──────▼──────┐ ┌────▼─────┐ ┌────▼──────┐ │ Vector Store │ │ Tool Hub │ │ Memory Hub │ │ Milvus/PGV │ │ HTTP/RPC │ │ Redis/DB │ └──────┬──────┘ └────┬─────┘ └────┬──────┘ │ │ │ ┌──────▼───────────────────────────▼──────┐ │ Observability & Governance Layer │ │ Prometheus / SkyWalking / OTel / DLQ │ └──────────────────────────────────────────┘

4.1 各层职责

4.2 为什么推荐“同步入口 + 异步内核”

用户入口可以是同步 HTTP 或 SSE，但内部执行建议尽量事件化、异步化：

• 用户不需要知道底层到底是串行还是并行
• 可以把长耗时步骤从同步线程中剥离
• 更容易做削峰、重试、死信、补偿
• 更适合高并发场景下独立扩缩容

这也是企业 Multi-Agent 和 Demo 项目最核心的差别之一。

五、技术选型：为什么是 Spring AI，而不是简单拼 SDK

5.1 Spring AI 的优势

对 Java 团队来说，Spring AI 的真正价值不是“能调模型”，而是它把 AI 能力纳入了 Spring 生态：

• 用统一接口屏蔽不同模型供应商差异
• 可以无缝接入 Spring Boot 配置体系
• 能复用 Spring 的依赖注入、AOP、配置中心、监控能力
• 与 WebFlux、消息中间件、缓存、数据库、网关天然集成

5.2 推荐的生产组合

5.3 不建议直接把 LangChain 风格逻辑硬塞进生产主链路

原因很现实：

• 业务边界容易被 Prompt 流程吞掉
• 状态可见性弱，问题难排查
• 与已有微服务治理体系融合成本高

如果你已经有成熟的 Spring Cloud / K8s / Kafka 基建，那么用 Spring AI 做“模型层标准化”，再用自己的编排层做业务治理，通常更稳。

六、核心对象建模：让 Agent 具备生产属性

这一节给出一套更完整的生产级代码骨架。

6.1 Agent 抽象

public interface Agent { String code(); String description(); AgentType type(); Mono<AgentResult> execute(AgentRequest request); }

public enum AgentType { PLANNER, RAG, TOOL, POLICY, SUMMARY }

6.2 请求上下文

import lombok.Builder; import lombok.Value; import java.time.Instant; import java.util.List; import java.util.Map; @Value @Builder(toBuilder = true) public class AgentRequest { String traceId; String sessionId; String tenantId; String userId; String userInput; List<MessageSnapshot> history; W