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 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 Market

Skills are prompt templates that the LLM uses for recurring workflows. The data is fully managed in the database (no more yml skills[] block) and lives in three tables:

6 seeded system skills

On first launch, the init migration seeds 6 system skills (stored directly in each user's user_skill with source=USER_CREATED, default_loaded=true) so every fresh install already has useful ones — including Monthly Event Report, HTTP Test, Deploy Project, Auto E2E, etc. Admins can edit / delete any of them at any time from the Skill Market admin page (no creation from admin).

Skill lifecycle for a normal user

1. Create — In the chat UI's Skill Library → 我的 tab → + 新增, or PUT /spring/ai/loom/skill. The skill is stored in user_skill with source=USER_CREATED. Fully editable (name / desc / content / default-loaded).
2. Submit to market — Library → 共享 tab. Click your skill, the form shows market metadata （无版本号）。 Submitted with status=APPROVED directly (no approval flow). Same (author, name) re-submits UPSERT (overwrites content + status).
3. Pull from market — Library → 市场 tab. Click item → right panel shows full details + 「添加到我的知识库」 button. Creates / refreshes a user_skill row with source=MARKET_PULLED. Re-pull of same name UPSERTs (no error).

• ****: If you already have a same-name USER_CREATED skill, pull is rejected (403) — use 「复制为我的技能」 first to copy as a new USER_CREATED.

1. Receive via role authorization — If admin granted a role → market_skill, the skill is auto-injected into your user_skill on every login with source=ROLE_GRANTED, locked=true. setRoleKnowledges auto-syncs new role grants. You cannot edit or delete it (it's pinned by the role).

What admins can do that normal users cannot

• Edit / 下架 (delete) any market_skill (admin no longer creates new skills — author is the one who publishes from chat UI)
• Authorize any APPROVED market skill to any role via role_skill (auto-syncs to all assigned users)
• 下架 cascades to all user_skill (pullers) and role_skill (role grants) — no orphans

Permission matrix

Using skills in the chat UI

Open the Skill Library button (🧠) — four tabs:

• 我的 — your local user_skill (plus admin's union view). Click a skill to see details, then 应用 (overwrite the textarea and auto-send to the model) or 复制 (overwrite the textarea, no send).
• 市场 — browse all APPROVED market skills and 拉取 them into your user_skill (rejects if you already have a same-name USER_CREATED).
• 共享 — submit a USER_CREATED skill to the market. status is direct APPROVED, no approval. no version number. two-stage click list item → right panel form.
• 我的发布 — track your market submissions (all APPROVED after de-approval). Click list item → right panel with 「撤回共享（下架）」 button. Withdraw cascades to all user_skill and role_skill.

Inside content you can reference MCP tools by @tool_name — the available tools come from the role-based mcps authorization, not from yml.

For the full REST API, see docs/API.md → §6 Skill Management.

Knowledge Base & Knowledge Market

Knowledge bases store documents for RAG retrieval. The knowledge space modal has four tabs:

• 我的 — your own knowledge bases. Create, upload documents, delete.
• 市场 — browse approved market knowledge bases and 添加到我的知识库 (subscribe).
• 共享 — your own knowledge bases not yet shared. Click 共享到市场 to submit for admin approval.
• 我的发布 — track your market submissions (PENDING / APPROVED / REJECTED). Withdraw PENDING items.

Market workflow: submit → PENDING → admin approve → APPROVED → other users can subscribe. Role-based authorization can also auto-grant knowledge bases to users (similar to skills).

For the knowledge market REST API, see docs/API.md → §5.8 Knowledge Market.

Admin Console

The admin console is a sidebar-navigated single-page-app shell. After admin login, all admin pages share a fixed left sidebar:

• 未登录跳 login: All admin HTML paths are auth-protected. Unauthenticated access 302-redirects to /spring/ai/loom/login.html; API calls 401.
• "清理聊天内容" 唯一入口: Only 控制台 → 批量清理 button. The duplicate "清理内容" / "一键清理" buttons in user row / conversation row were consolidated.
• Role gating: All admin paths require user_info.type = 'ADMIN'. Non-admin attempting admin URL is redirected back to chat home.

• For built-in tool reference (time / skill / file / git / maven / compile), see: TOOLS.md
• For standalone MCP server usage (file / git / maven / compile), see the Built-in Tools → Standalone MCP Servers section above
• 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