Spring AI LoomAgent

Spring Boot AI Agent — an out-of-the-box solution that makes your app converse, remember, think, and act.

Features

6 Pillars: 💬 Chat · Knowledge · 📁 Files · 🔧 MCP · 🧠 Skill · 🛡 RBAC Platform: 🧠 Skill Market · Knowledge Market · 🎛 Admin Console Advanced: 🧩 Sub-tasks · ⏰ Scheduled tasks · 🖼 Multimodal — one dependency, batteries included.

• 💬 Streaming Chat — SSE multi-turn, collapsible reasoning, message copy/download; multimodal image + document mixed input
• 📚 RAG Knowledge Base — Multi-KB management, Tika parsing + vectorization, built-in JVector local store (swap in any Spring AI vector store)
• 🔧 MCP Tool Integration — Sync/async dual mode; available tools gated by role authorization, enabled per chat
• 🧠 Skill Market — DB-stored prompt templates, 3 sources (self-built / market-pulled / role-granted); no approval flow (submit goes direct APPROVED); pull rejects overwriting same-name USER_CREATED; remove blocked when market_skill_id is set; admin only edits / pulls (no creation); no version field. Skills call MCP via @tool_name. Frontend chat input supports / picker for precise skill selection.
• 🧩 Sub-tasks & ⏰ Scheduled Tasks — Delegate a slice of work to a synchronous "sub-model"; LLM-created schedules run as sub-tasks and survive restarts
• 🛡 RBAC — Two levels: user type (admin / user) + business roles; admin sees all, normal users get the union of their roles' grants
• 🎛 Admin Console — Sidebar SPA: users / roles / skill market / knowledge market / MCP descriptions / logs (formerly usage stats); admin-gated
• 📁 File Management — Disk storage + H2 metadata, upload / preview / download, chat-attachment bridging
• 🧰 Built-in Tools — Time / file / skill / sub-task / schedule / end-to-end deploy (on by default), git / maven (opt-in); see TOOLS.md
• ⚙️ Batteries-included Engineering — Spring Boot auto-config, every bean replaceable via @ConditionalOnMissingBean, Flyway migrations, broad chat / embedding / vector-store support

Built-in Tools

All tools follow the interface + default implementation pattern. Every component is registered with @ConditionalOnMissingBean, allowing consumers to replace any piece with a custom implementation.

For full @Tool method signatures, parameter details, and configuration reference, see TOOLS.md.

Compile & Deploy Tool

Admin Console

Standalone MCP Servers

File, Git, Maven, and Compile each have a standalone MCP server module — the core layer has no Spring dependency and can be deployed via jbang to any MCP-compatible agent (Claude Desktop, Cursor, etc.):

Quick Start: Add a Chat Interface

1. Add LoomAgent Dependency

<dependency>
 <groupId>io.github.wb04307201</groupId>
 <artifactId>spring-ai-loom-agent-spring-boot-starter</artifactId>
 <version>1.1.39</version>
</dependency>

2. Add a Spring AI Model Dependency

The test application uses Alibaba's Qwen (DashScope) via Spring AI Alibaba. Swap the dependency and config for any other provider:

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

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

For other models, see the Spring AI docs.

Note: For document-based Q&A, ensure the model supports multimodal input (e.g., multi_model: true). Document content is injected via System Prompt.

3. Start the Project

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

Document Upload & Conversation

Click the + button next to the input field to upload images or documents. After uploading, type your question and send it.

Supported Document Formats

PDF, DOCX, XLSX, PPTX, MD, TXT, HTML, CSV, RTF, and more.

How It Works

1. Images: Passed as Media type directly to the multimodal model (requires model support, e.g., DashScope Qwen series)
2. Documents: Text content extracted via Apache Tika, injected as System Prompt into the conversation context
3. Mixed scenarios: Images and documents can be uploaded together; the model synthesizes visual information and document text

File Download, Preview, and Deletion

Uploaded and generated files can get download links via MCP tool downloadFileUrl, or preview links via MCP tool viewFileUrl. Files and directories can be removed via MCP tool deleteFileOrDirectory (requires explicit I_CONFIRM_DELETE confirmation — token configurable via spring.ai.loom.agent.file.deleteConfirmToken, supports recursive directory removal, and cleans up temporary file_info records).

The "File" entry provides unified browsing, previewing, downloading, and deleting for all non-knowledge-base files (including tool uploads and git repositories).

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
 top-k: 4 # Top-k results, default 4

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"
 ]
 }
 }
}

The MCP button opens a panel 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 autom