SwarmAI Framework

A multi-agent orchestration framework for Java, designed for enterprise use. Built on Spring AI 1.0.4 GA and Spring Boot 3.4 with type-safe state management, dynamic skill generation, RL-powered decision making, and enterprise features.

www.intelliswarm.ai | Documentation | Quick Start | Migration Guide

Architecture

graph TB
    classDef entry fill:#E3F2FD,stroke:#1976D2,stroke-width:2px,color:#000
    classDef core fill:#EDE7F6,stroke:#5E35B1,stroke-width:2px,color:#000
    classDef runtime fill:#FFF3E0,stroke:#F57C00,stroke-width:2px,color:#000
    classDef guard fill:#FCE4EC,stroke:#C2185B,stroke-width:2px,color:#000
    classDef improve fill:#E0F7FA,stroke:#00838F,stroke-width:2px,color:#000
    classDef ext fill:#ECEFF1,stroke:#455A64,stroke-width:2px,color:#000

    subgraph Entry["① Declare a workflow"]
        YAML["YAML DSL<br/><i>swarmai-dsl</i>"]:::entry
        Java["Java Builder API"]:::entry
        Studio["REST · Studio UI<br/><i>swarmai-studio</i>"]:::entry
    end

    Compiler["SwarmCompiler"]:::core
    Engine["<b>Swarm Coordinator</b><br/>8 Process strategies<br/>SEQUENTIAL · PARALLEL · HIERARCHICAL · ITERATIVE<br/>SELF_IMPROVING · SWARM · DISTRIBUTED · COMPOSITE"]:::core

    subgraph Agents["② Agent runtime"]
        direction LR
        A1["Agent"]:::runtime
        A2["Agent"]:::runtime
        A3["Agent"]:::runtime
    end

    Tools["<b>Tool Registry</b><br/>RBAC · Hooks · Audit<br/>25 built-in + MCP + dynamic Skills"]:::runtime

    subgraph Guards["Enterprise guardrails"]
        direction LR
        Budget["Budget Tracker<br/>HARD_STOP · WARN"]:::guard
        Gov["Governance Gates<br/>human approval"]:::guard
        Tenant["Tenant Context<br/>quotas · isolation"]:::guard
    end

    subgraph Insights["Observability &amp; learning"]
        direction LR
        Mem["Memory + Knowledge<br/>JDBC · Redis · Vector"]:::runtime
        Obs["Traces · Metrics<br/>Event Store"]:::runtime
        RL["RL Policy Engine<br/>LinUCB · Thompson"]:::runtime
    end

    LLM[("LLM providers<br/>OpenAI · Anthropic · Ollama<br/><i>via Spring AI ChatClient</i>")]:::ext
    World[("External world<br/>DBs · MCP · Web<br/>Shell · Email · Slack")]:::ext

    YAML --> Compiler
    Java --> Compiler
    Studio --> Compiler
    Compiler --> Engine
    Engine --> A1
    Engine --> A2
    Engine --> A3
    A1 --> Tools
    A2 --> Tools
    A3 --> Tools
    A1 -.-> LLM
    A2 -.-> LLM
    A3 -.-> LLM
    Tools --> World
    Mem --> World

    Engine -. gated by .-> Gov
    Engine -. scoped by .-> Tenant
    A1 -. meters .-> Budget
    A2 -. meters .-> Budget
    A3 -. meters .-> Budget
    A1 -. emits .-> Obs
    A2 -. emits .-> Obs
    A3 -. emits .-> Obs
    A1 -. reads/writes .-> Mem
    Engine -. asks .-> RL

The engine picks one of 8 process strategies, runs agents that call LLMs and tools, and enforces budget, governance, and tenant guardrails along the way.

Try it in 30 seconds

# pr-reviewer.yaml
swarm:
  process: PARALLEL
  budget: { max_tokens: 50000, mode: HARD_STOP }
  agents:
    security-reviewer:
      role: "Security Reviewer"
      tools: [git-diff, semgrep]
      permissionMode: READ_ONLY
    style-reviewer:
      role: "Style Reviewer"
      tools: [git-diff]
      permissionMode: READ_ONLY

docker run -e OPENAI_API_KEY=$KEY intelliswarm/swarmai run pr-reviewer.yml

Live playground: intelliswarm.ai/demo — step through recorded workflow traces in the browser, no install needed.

How SwarmAI compares

	SwarmAI	LangGraph	langchain4j	Spring AI
Language	Java	Python	Java	Java
Multi-agent orchestration	✓	✓	partial	✗
Declarative YAML workflows	✓	✗	✗	✗
Budget enforcement	✓	✗	✗	✗
Governance / approval gates	✓	partial	✗	✗
RBAC on tool execution	✓	✗	✗	✗
Production maturity	new (1.0)	mature	mature	mature
Community size	small	large	medium	large

If you don't need multi-agent orchestration with governance, use Spring AI directly. If you're on Python, use LangGraph. SwarmAI's wedge is JVM teams that need an opinionated agent layer with budget, RBAC, and approval gates baked in.

What's New

• Enterprise Module (swarmai-enterprise) -- Commercial tier with license-gated multi-tenancy, advanced governance, RBAC, audit, and SSO
• Self-Evaluation Module (swarmai-eval) -- Framework for agentic self-evaluation and competitive benchmarks
• Resilience -- Circuit breaker + exponential backoff retry on LLM calls via resilience4j
• Thread-Safe Observability -- ObservabilityContext now propagates across parallel threads via Snapshot API
• Typed Exception Hierarchy -- SwarmException, AgentExecutionException, ProcessExecutionException, ToolExecutionException, ConfigurationException, PermissionDeniedException
• Health Indicators -- Spring Boot Actuator health checks for Memory, Budget, and EventStore subsystems
• Flyway Migrations -- JDBC schema management for memory and audit tables via Flyway
• SPI Interfaces -- AuditSink, MeteringSink, LicenseProvider for enterprise extensibility
• Configuration Validation -- Fail-fast startup validation for budget, observability, and tenant config

Quick Start

Available on Maven Central. Recommended approach is to import the BOM and let it manage versions for all SwarmAI modules:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>ai.intelliswarm</groupId>
            <artifactId>swarmai-bom</artifactId>
            <version>1.0.9</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Core framework -->
    <dependency>
        <groupId>ai.intelliswarm</groupId>
        <artifactId>swarmai-core</artifactId>
    </dependency>

    <!-- Optional: 26 built-in tools (web, PDF, CSV, shell, etc.) -->
    <dependency>
        <groupId>ai.intelliswarm</groupId>
        <artifactId>swarmai-tools</artifactId>
    </dependency>

    <!-- Optional: YAML DSL for declarative workflows -->
    <dependency>
        <groupId>ai.intelliswarm</groupId>
        <artifactId>swarmai-dsl</artifactId>
    </dependency>
</dependencies>

Enterprise + Studio modules (swarmai-enterprise, swarmai-studio) are licensed under BSL 1.1 and distributed via GitHub Packages instead of Maven Central. Configure a <server> block in your ~/.m2/settings.xml with a Personal Access Token having read:packages scope to consume them.

Agent researcher = Agent.builder()
    .role("Research Analyst")
    .goal("Find accurate, up-to-date information")
    .backstory("Experienced researcher who verifies facts.")
    .chatClient(chatClient)
    .tool(webSearchTool)
    .permissionMode(PermissionLevel.READ_ONLY)
    .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: {topic}")
    .agent(researcher).build();

Task report = Task.builder()
    .id("report").description("Write a report from findings")
    .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 in enterprise"));

YAML DSL (Zero-Code)

swarm:
  process: SEQUENTIAL
  agents:
    researcher:
      role: "Research Analyst"
      goal: "Find accurate information"
      tools: [web-search]
      permissionMode: READ_ONLY
    writer:
      role: "Content Writer"
      goal: "Write clear reports"
  tasks:
    research:
      description: "Research: {{topic}}"
      agent: researcher
    report:
      description: "Write a report from findings"
      agent: writer
      dependsOn: [research]
      outputFormat: MARKDOWN

Swarm swarm = swarmLoader.load("workflows/research.yaml", Map.of("topic", "AI agents"));
SwarmOutput result = swarm.kickoff(Map.of());

Build & Test

./mvnw clean test       # 3004 tests, all passing
./mvnw clean install    # install to local Maven repo

Project Structure

swarm-ai/                        (parent POM, 11 modules)
├── swarmai-core/                Core: agents, tasks, 8 process types, state, skills, memory,
│                                knowledge, budget, governance, observability, resilience,
│                                RL (LinUCB, NeuralLinUCB, Thompson sampling, Bayesian optimization)
├── swarmai-tools/               25 built-in tools (web, file, shell, PDF, CSV, security, etc.)
├── swarmai-dsl/                 YAML DSL parser & compiler (38 definition types)
├── swarmai-enterprise/          Enterprise: multi-tenancy, advanced governance, RBAC, audit, SSO
├── swarmai-self-improving/      Dynamic skill generation pipeline (opt-in)
├── swarmai-distributed/         RAFT consensus, distributed goals, intelligence mesh
├── swarmai-eval/                Self-evaluation swarm & competitive benchmarks
├── swarmai-studio/              Web dashboard for workflow monitoring
├── swarmai-bom/                 Bill of Materials for version alignment
└── docker/                      Dockerfiles and docker-compose configs

Key Features

8 Process Types

Process	Description
SEQUENTIAL	Tasks in dependency order, each receives prior outputs
PARALLEL	Independent tasks run concurrently in layers
HIERARCHICAL	Manager delegates to workers, synthesizes results
ITERATIVE	Execute -> review -> refine loop until approved
SELF_IMPROVING	Iterative + dynamic skill genera