spring-ai-loom-agent

Spring AI LoomAgent

A Spring Boot auto-configuration library that injects RAG knowledge base, MCP tool calling, and Skill library into Spring AI applications with an out-of-the-box chat UI.

Features

• Chat Interface
  • SSE streaming chat with multi-turn conversation and session management
  • Collapsible model reasoning (Thinking) display
  • One-click message copy and Markdown download
• RAG Knowledge Base
  • Multi-KB CRUD with file upload, Tika parsing, and vectorization
  • Optional LLM keyword/summary metadata enrichment
  • Local JVector HNSW vector store with disk persistence
• MCP Service Integration
  • Synchronous/asynchronous MCP client support, 12 pre-configured services (search, maps, weather, charts, browser automation, etc.)
  • Runtime enable/disable per session with session isolation
• Skill Library
  • Predefined skill templates with parameterized forms (text/dropdown/textarea)
  • Skill-to-MCP tool binding with autonomous LLM discovery and invocation
  • Runtime dynamic CRUD
• File Management
  • Disk file storage + H2 metadata management with knowledge base association
  • Image upload (up to 10MB) with thumbnail preview and full-screen view
• User & Authentication
  • Token-based authentication filter with auto-login support and custom IUser implementation
  • Frontend localStorage session persistence
• Frontend UI (Loom)
  • Sidebar conversation history with KB/MCP/Skill modal panels
  • Responsive layout (sidebar collapses below 768px)
  • Toast notifications
• Engineering
  • Spring Boot auto-configuration with @ConditionalOnMissingBean on all components for full replaceability
  • Flyway database migration with support for 10+ chat models / 12+ embedding models / 24+ vector store backends

Quick Start: Add a Chat Interface

1. Add LoomAgent Dependency

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.1.5</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>io.github.wb04307201</groupId>
        <artifactId>spring-ai-loom-agent-spring-boot-starter</artifactId>
        <version>1.1.19</version>
    </dependency>
</dependencies>

2. Add a Spring AI Model Dependency

The following example uses Alibaba's Qwen (DashScope). Replace with any other LLM as needed:

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    <version>1.1.2.2</version>
</dependency>

spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}
    chat:
      options:
        model: qwen3.6-plus
        multi_model: true
        enable_thinking: true
    embedding:
      options:
        model: text-embedding-v2

For other models, see the Spring AI docs.

3. Start the Project

Visit http://localhost:8080/spring/ai/loom

Replace the Default RAG Implementation

The following example uses Qdrant as the vector store. Add the dependency:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-qdrant</artifactId>
</dependency>

Add configuration:

spring:
  ai:
    vectorstore:
      qdrant:
        host: localhost
        port: 6334
        collection-name: qwen-collection-name

Optional RAG configuration:

spring:
  ai:
    loom:
      agent:
        rag:
          similarityThreshold: 0.50   # Similarity threshold, default 0.0
          topK: 4                     # Top-k results, default 4
          defaultPromptTemplate: |
            Context information is below.

            ---------------------
            {context}
            ---------------------

            Given the context information and no prior knowledge, answer the query.

            Follow these rules:

            1. If the answer is not in the context, just say that you don't know.
            2. Avoid statements like "Based on the context..." or "The provided information...".

            Query: {query}

            Answer:
          defaultEmptyContextPromptTemplate: |
            The user query is outside your knowledge base.
            Politely inform the user that you can't answer it.

MCP Services

Taking the time MCP service as an example, add the dependency:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>

Add configuration:

spring:
  ai:
    mcp:
      client:
        stdio:
          servers-configuration: classpath:mcp-servers.json

mcp-servers.json:

{
  "mcpServers": {
    "time": {
      "command": "uvx",
      "args": [
        "mcp-server-time",
        "--local-timezone=Asia/Shanghai"
      ]
    }
  }
}

After configuring MCP services, an MCP button appears in the toolbar showing available services:

Add Chinese labels and descriptions for tools via configuration:

spring:
  ai:
    loom:
      agent:
        mcps:
          - name: spring-ai-mcp-client - time
            title: Time
            description:
              A Model Context Protocol service that provides time and timezone conversion functionality. This service enables
              large language models to obtain current time information and perform timezone conversions using IANA timezone names,
              with automatic system timezone detection.
            tools:
              - name: get_current_time
                description: Get the current time in a specified timezone
              - name: convert_time
                description: Convert time between different time zones

Skill Library

You can write skills and add them to the skill library. Skills can be configured with parameters and associated tools:

spring:
  ai:
    loom:
      agent:
        skills:
          - name: Monthly Event Report
            description: Collect monthly events on specified topics through web search, generate monthly event insight reports through in-depth analysis, suitable for enterprise intelligence monitoring, industry trend tracking, etc.
            tools:
              - spring-ai-mcp-client - time
              - spring-ai-mcp-client - sequential-thinking
              - spring-ai-mcp-client - bing-search
              - spring-ai-mcp-client - http-mcp
            content: classpath:skills/news-watch.st
            params:
              - name: param1
                label: Topic
                type: text
                required: true
                default-value: Party

Skill content file (classpath:skills/news-watch.st):

Search the web to obtain important monthly events for {param1} in the current year, generate insight reports through in-depth analysis. Requirements:
- Use @get_current_time to get current time
- Use @sequentialthinking to plan all steps, thoughts, and branches
- Use @bing_search to search month by month for important events. Verify with search before each Thinking round
- Use @crawl_webpage to view detailed webpage content from search results
- Thinking rounds should be no less than 5, with divergent brainstorming awareness and thinking branches
- Each round needs to reflect on whether decisions are correct based on query results
- Perform event correlation analysis and form conclusions. Generate "Monthly Event Report"

You can precisely invoke skills through the Skill Library button in the UI. Skills are preloaded by default and can also be used directly in conversations.

---

• For more configuration and extension points, see: Spring AI LoomAgent Customization Guide
• For custom UI integration and API reference, see: Spring AI LoomAgent API Documentation