RAG Agent Platform

Put knowledge bases, Agents, and MCP tools into one self-hosted workflow.

Built with Spring Boot, Next.js, and LangChain4j to bring retrieval, conversation, and tool use together while you keep control of your data, models, and infrastructure.

English · 简体中文

Live Demo: 39.97.58.27/explore

Features · Quick Start · Screenshots · How It Works · Deployment · Scope · Documentation

From document ingestion and vector retrieval to user-facing Agent conversations, this project brings the core RAG workflow into one console: create knowledge bases, configure models and Agents, then connect them to already configured MCP tools. It is designed for teams that need control over their data and deployment, with an Alibaba Cloud environment available for trying the main workflow.

_{Manage knowledge bases, Agents, model providers, and MCP tools from one workspace.}

Features

Capability	What you can do
Knowledge bases and retrieval	Upload and process documents, use PostgreSQL + PGVector for vector retrieval, and connect knowledge bases to RAG conversations.
Configurable Agents	Configure model providers, manage and publish Agents, and stream conversation responses over SSE.
MCP tool integration	Connect Agents to a configured MCP gateway and tool containers; the current UI does not provide a complete tool-import workflow, so configure the gateway and containers manually.
Self-hosted control	Deploy your own workflow with Spring Boot, Next.js, RabbitMQ, S3-compatible object storage, and external model services.

Quick Start

Prerequisites

• Java 17 and Maven 3.9+
• Node.js 20 and pnpm
• PostgreSQL 14+ with the vector extension
• RabbitMQ 3.13+
• S3-compatible object storage, such as Qiniu KODO
• A configured model / reranker provider and SMTP service
• Docker when you use container-managed MCP tools

1. Prepare services and configuration

Create a database and enable PGVector:

createdb agentx
psql -d agentx -c "CREATE EXTENSION IF NOT EXISTS vector;"
psql -d agentx -f docs/sql/01_init.sql

Start RabbitMQ. Create .env from .env.example and fill in the database, RabbitMQ, object-storage, model, and SMTP settings; then provide those values through your shell or IDE run configuration. Spring Boot does not load the repository-root .env file by itself:

cp .env.example .env

Create frontend/.env.local with the browser-visible service addresses:

NEXT_PUBLIC_API_URL=http://localhost:8088/api
NEXT_PUBLIC_WS_URL=ws://localhost:8088/api

2. Start the application

Start the backend from the repository root:

mvn spring-boot:run

In another terminal, start the frontend:

cd frontend
pnpm install
pnpm dev

Open http://localhost:3000. The backend health endpoint is http://localhost:8088/api/health.

Screenshots

Knowledge-base list Browse and organize the knowledge bases available for retrieval from one entry point.	Knowledge-base detail Inspect document processing status and knowledge-base contents.
Model-provider configuration Configure the model services available to an Agent.	Published Agent Start a conversation with an Agent published by another user.

How It Works

flowchart LR
    Browser["Next.js frontend"] --> API["Spring Boot API"]
    API --> Agent["Agent and conversation services"]
    API --> RAG["RAG services"]
    Agent --> LLM["Configured LLM providers"]
    Agent --> MCP["MCP gateway and tool containers"]
    RAG --> Queue["RabbitMQ document processing"]
    RAG --> Data["PostgreSQL + PGVector"]
    RAG --> Storage["S3-compatible object storage"]
    Agent --> Data

Loading

The browser reaches the Spring Boot API through the Next.js console. Document-processing jobs run asynchronously through RabbitMQ and write to PGVector; Agents combine configured model services, knowledge retrieval, and MCP tools, while the current conversation stream returns to the frontend through SSE.

Area	Implementation
Backend	Java 17, Spring Boot 3.2.3, LangChain4j
Frontend	Next.js 15, React 19
Data	PostgreSQL 14+ with PGVector
Asynchronous work	RabbitMQ
File storage	S3-compatible object storage
Streaming	Server-Sent Events (SSE)

Deployment Notes

The Docker Compose setup in this repository is the author's deployment reference, not a one-command installation: it expects an external PostgreSQL and object storage, pulls images from a private registry, and leaves the MCP gateway for you to configure. Treat it as a starting point and fill in the rest for your own infrastructure.

Runtime topology

Five containers plus one external database. nginx routes by path: /api/ goes to the backend, everything else to the frontend.

                      public :80
                           │
                    ┌──────▼──────┐
                    │    nginx    │
                    └──┬───────┬──┘
                 /api/ │       │ /
              ┌────────▼──┐ ┌──▼─────────┐
              │  backend  │ │  frontend  │
              │   :8088   │ │   :3000    │
              │Spring Boot│ │  Next.js   │
              └──┬─────┬──┘ └────────────┘
                 │     │
        ┌────────▼─┐ ┌─▼──────────────┐
        │ RabbitMQ │ │ Alibaba Cloud  │  ← outside compose
        │          │ │ RDS PG+PGVector│
        └──────────┘ └────────────────┘
                 │
        ┌────────▼──────────┐    ┌──────────────┐
        │ docker.sock       │    │    runner    │
        │ (MCP tool         │    │  self-hosted │
        │  containers)      │    │    CI/CD     │
        └───────────────────┘    └──────────────┘

Resource quotas: backend 1.2 CPU / 1536M, frontend 0.6 / 768M, RabbitMQ 0.3 / 512M.

⚠️ The backend's 1.2 CPU limit changes runtime behavior — the JVM derives a ForkJoinPool.commonPool parallelism of only 1 from it. Read Performance tuning before changing it.

First deployment

curl -fsSL https://get.docker.com | sh
git clone https://github.com/NEDONION/rag-agent-platform && cd rag-agent-platform
cp .env.example .env && vim .env        # database, S3, model providers, ...
docker login --username=<username> crpi-c6nc3ef4yktaqunc.cn-beijing.personal.cr.aliyuncs.com
sudo docker compose up -d

Verify:

curl -i http://localhost:8088/api/health
curl -i http://localhost:3000/api/health

Continuous deployment

Pushing to main builds and ships automatically — no server login required:

push main
   │
   ├─ build   (GitHub cloud)   build backend/frontend images → push to Alibaba Cloud ACR
   ├─ config  (GitHub cloud)   package compose and nginx config as an artifact
   │
   └─ deploy  (server runner) ─┐
                               ├─ download artifact
                               ├─ record IMAGE_TAG in .env
                               ├─ docker compose pull backend frontend
                               ├─ docker compose up -d backend frontend
                               ├─ docker compose restart nginx
                               └─ health check (workflow fails on error)

Deployments are picked up by a self-hosted runner on the server polling GitHub, so the connection is purely outbound. The server therefore needs no SSH access or any inbound port, and no server credentials are stored in GitHub Secrets (only ACR_USERNAME, ACR_PASSWORD, and DEPLOY_PATH).

Rollback

Every deployment writes the commit SHA into the server's .env, and each image is tagged with both <sha> and latest:

sed -i 's|^IMAGE_TAG=.*|IMAGE_TAG=<target-commit-sha>|' .env
docker compose up -d backend frontend

The full environment-variable list, CI/CD constraints, measured network data from mainland China, and the operations checklist are in the deployment guide; problems hit during deployment (with the original error output) are recorded in the troubleshooting log.

Project Scope

• This project is primarily self-hosted and also provides an Alibaba Cloud live demo for evaluation.
• Conversation streaming currently uses SSE.
• Agents can connect to a configured MCP gateway and tool containers; the current UI does not provide a complete tool-import workflow, so configure the gateway and containers manually.
• Review the repository configuration and all infrastructure requirements before production use.

Documentation

The complete documentation lives in the documentation index, organized by architecture / modules / reference / operations / development. Common entry points:

Document	Contents
System architecture	Technology stack, DDD layering, and data flow
Infrastructure	MQ, storage, transport, encryption, and other technical subpackages
RAG module	Document processing, vector retrieval, and the RAG path
Agent module	Agent lifecycle and tool integration
Conversation module	Sessions, messages, SSE, and context management
MCP tool module	Tool publishing state machine and container isolation
LLM module	Providers, protocol adapters, and high availability
Users and authentication	Login, API keys, and user settings
Execution tracing	Observability and execution-path records
Tasks and scheduling	Workflow tasks and scheduled jobs
API reference	REST and SSE interfaces
Database design	Table structures, ER diagrams, and indexes
Deployment guide	Topology, CI/CD, and rollback
Local development	Environment setup and commit workflow
Troubleshooting log	Production incident records, continuously updated
Database initialization	Complete PostgreSQL and PGVector schema script (35 tables)

Contributing

Issues and pull requests are welcome. Please describe the problem, your environment, and the verification you performed.