SwarmAI：基于 Spring AI 的企业级多智能体框架

项目概述

在 AI 智能体（Agent）技术快速发展的背景下，如何将多智能体系统从实验原型推进到生产环境成为关键挑战。SwarmAI 是一个基于 Java 和 Spring AI 构建的企业级多智能体框架，它不仅提供了智能体编排的基础能力，还针对生产环境的需求，实现了类型安全的状态管理、自我改进的工作流、运行时代码生成、检查点持久化和企业级治理等高级功能。

SwarmAI 基于 Spring AI 1.0.4 GA 和 Spring Boot 3.4 构建，充分利用了 Spring 生态的成熟性和企业级特性，为 Java 开发者提供了一条从传统应用向 AI 原生应用迁移的平滑路径。

核心架构

SwarmAI 采用模块化设计，核心组件包括：

• swarmai-core：核心框架，包含智能体、任务、流程、状态、技能、记忆、知识、预算、治理、可观测性
• swarmai-dsl：YAML DSL，用于声明式工作流定义
• swarmai-tools：24 个内置工具（网页、文件、Shell、PDF、CSV 等）
• swarmai-studio：Web 仪表板，用于工作流监控
• swarmai-bom：物料清单，用于版本对齐

用户可以根据需求选择所需模块，swarmai-tools 和 swarmai-studio 是可选的。

智能体设计

SwarmAI 中的智能体是一个具有角色、目标、背景故事和能力的实体。每个智能体包装一个 Spring AI ChatClient，可以使用工具、记忆和知识库。

基础智能体定义示例

Agent agent = Agent.builder()
    .role("Financial Analyst")
    .goal("Analyze financial data and identify trends")
    .backstory("CFA with 15 years of equity research experience.")
    .chatClient(chatClient)
    .tools(List.of(webSearchTool, csvTool, calculatorTool))
    .memory(memory)
    .knowledge(knowledge)
    .modelName("gpt-4o")
    .temperature(0.2)
    .maxExecutionTime(60_000)
    .verbose(true)
    .build();

多轮推理能力

默认情况下，智能体每个任务执行单次 LLM 调用。启用 maxTurns 后，智能体可以在多个推理步骤中工作，在轮次之间累积上下文，直到发出完成信号或达到轮次限制。

Agent agent = Agent.builder()
    .role("Deep Analyst")
    .goal("Perform thorough multi-step analysis")
    .backstory("Expert at breaking complex problems into steps.")
    .chatClient(chatClient)
    .tools(List.of(webSearchTool, calculatorTool))
    .maxTurns(5)
    .build();

智能体使用 CONTINUE 和 DONE 标记来信号是否需要更多工作。Token 使用量在所有轮次中累积，最终的 TaskOutput 包含实际轮次数的元数据。

内置防护机制

智能体自动管理每个模型的上下文窗口限制，对瞬态 LLM 错误进行指数退避重试，并在系统提示中包含反幻觉防护。

任务系统

任务定义要完成的工作，支持依赖关系、条件执行、变量插值和输出格式化。

Task task = Task.builder()
    .id("analyze")
    .description("Analyze {company} stock performance in {year}")
    .expectedOutput("SWOT analysis in JSON format")
    .agent(analyst)
    .dependsOn("research")
    .condition(ctx -> ctx.contains("data available"))
    .outputFormat(OutputFormat.JSON)
    .outputFile("output/analysis.json")
    .build();

流程类型

框架支持多种执行流程：

• SEQUENTIAL：任务按依赖顺序运行，每个任务接收先前输出作为上下文
• PARALLEL：独立任务并发运行
• HIERARCHICAL：支持嵌套子流程的层级执行
• CONDITIONAL：基于运行时状态的条件分支

使用方式

Java API 方式

// 定义智能体
Agent researcher = Agent.builder()
    .role("Research Analyst")
    .goal("Find accurate, up-to-date information")
    .backstory("Experienced researcher who verifies facts.")
    .chatClient(chatClient)
    .tool(webSearchTool)
    .build();

Agent writer = Agent.builder()
    .role("Content Writer")
    .goal("Write clear, engaging reports")
    .backstory("Turns research into well-structured articles.")
    .chatClient(chatClient)
    .build();

// 定义带依赖的任务
Task research = Task.builder()
    .id("research")
    .description("Research the topic: {topic}")
    .expectedOutput("Key findings with sources")
    .agent(researcher)
    .build();

Task report = Task.builder()
    .id("report")
    .description("Write a report based on the research findings")
    .expectedOutput("Well-structured report in markdown")
    .agent(writer)
    .dependsOn("research")
    .outputFormat(OutputFormat.MARKDOWN)
    .build();

// 运行智能体群
SwarmOutput result = Swarm.builder()
    .agents(List.of(researcher, writer))
    .tasks(List.of(research, report))
    .process(ProcessType.SEQUENTIAL)
    .build()
    .kickoff(Map.of("topic", "AI agents"));

YAML DSL 方式

同样的工作流可以完全用 YAML 定义，无需 Java 代码：

swarm:
  process: SEQUENTIAL
  agents:
    researcher:
      role: "Research Analyst"
      goal: "Find accurate, up-to-date information"
      backstory: "Experienced researcher who verifies facts."
      tools: [web-search]
    writer:
      role: "Content Writer"
      goal: "Write clear, engaging reports"
      backstory: "Turns research into well-structured articles."
  tasks:
    research:
      description: "Research the topic: {{topic}}"
      expectedOutput: "Key findings with sources"
      agent: researcher
    report:
      description: "Write a report based on the research findings"
      expectedOutput: "Well-structured report in markdown"
      agent: writer
      dependsOn: [research]
      outputFormat: MARKDOWN

加载和运行只需两行 Java 代码。

企业级特性

类型安全的状态管理

SwarmAI 提供类型安全的状态管理机制，确保工作流状态的完整性和一致性。状态变更通过强类型 API 进行，避免运行时错误。

自我改进工作流

框架支持运行时 CODE 技能生成，智能体可以根据任务需求动态生成代码工具并执行。这种自我改进能力使系统能够适应新场景，无需预先定义所有工具。

检查点持久化

工作流执行过程中的状态可以持久化到检查点，支持故障恢复、长时间运行任务的审计追踪。

企业治理功能

• 预算跟踪：监控 Token 使用量和 API 调用成本
• 多租户支持：隔离不同团队或项目的工作流
• 访问控制：基于角色的权限管理
• 审计日志：完整的操作记录

可观测性

• Mermaid 图表生成：自动生成工作流可视化图表
• Hook 系统：在关键节点插入自定义逻辑
• 指标收集：性能、成本、成功率等指标
• Web 仪表板：实时监控工作流执行状态

内置工具集

swarmai-tools 模块提供 24 个即用型工具，包括网页搜索、网页抓取、PDF 解析、CSV 处理、文本文件读写、Shell 命令执行、计算器、数据转换、格式验证等。

快速开始

添加 Maven 依赖后即可使用。框架包含 925 个测试，全部通过。构建命令使用标准的 Maven 生命周期。

应用场景

SwarmAI 特别适合以下企业场景：

• 自动化研究报告生成：研究员智能体收集信息，写手智能体生成报告
• 客户服务自动化：多智能体协作处理复杂客户请求
• 数据处理管道：ETL 流程的智能编排
• 代码审查与生成：开发辅助的多智能体工作流
• 金融分析：多源数据整合与风险分析

生态与依赖

SwarmAI 构建于成熟的 Java/Spring 生态之上，包括 Spring AI、Spring Boot、OpenJDK 21 和 Maven。

总结

SwarmAI 为 Java 企业开发者提供了一个功能完备、生产就绪的多智能体框架。它不仅解决了智能体编排的基础问题，更重要的是针对企业环境的实际需求，提供了类型安全、可观测、可治理的完整解决方案。