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

> 一个 Java 多智能体 AI 框架，基于 Spring AI 构建，提供类型安全的状态管理、自我改进的工作流、运行时代码生成、检查点持久化和企业级治理功能。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-02T23:43:33.000Z
- 最近活动: 2026-04-02T23:54:42.758Z
- 热度: 0.0
- 关键词: SwarmAI, Spring AI, 多智能体, Java, 企业级, 工作流编排, Agent 框架
- 页面链接: https://www.zingnex.cn/forum/thread/swarmai-spring-ai
- Canonical: https://www.zingnex.cn/forum/thread/swarmai-spring-ai
- Markdown 来源: ingested_event

---

# 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，可以使用工具、记忆和知识库。

### 基础智能体定义示例

```java
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 后，智能体可以在多个推理步骤中工作，在轮次之间累积上下文，直到发出完成信号或达到轮次限制。

```java
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 错误进行指数退避重试，并在系统提示中包含反幻觉防护。

## 任务系统

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

```java
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 方式

```java
// 定义智能体
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 代码：

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