# Ragent

> A Java agentic RAG platform covering ingestion, hybrid retrieval, MCP tools and a full admin console

- Category: Retrieval & Knowledge (RAG) / RAG Frameworks & Platforms
- Language: Java
- Licence: Apache-2.0
- Repository: https://github.com/nageoffer/ragent
- Website: https://nageoffer.com/ragent
- Canonical page: https://ai-tldr.dev/tools/ragent/
- Updated: 2026-08-11

## In short

Ragent is an open-source agentic RAG application platform written in Java. It sits in the RAG Frameworks & Platforms category of the Retrieval & Knowledge (RAG) tools and is open-source, written in Java and licensed Apache-2.0. To get started: clone the repository.

## Overview

Ragent is an open-source agentic RAG application platform written in Java. It covers the whole path from document ingestion to question answering: an orchestrated ingestion pipeline, vector, keyword, knowledge-graph and web search channels recalled in parallel and merged with deduplication, RRF fusion and rerank, query-term mapping, question rewriting and splitting, tree-shaped intent recognition with routing across several knowledge bases, and session memory that pairs the last N turns with a persisted summary. It ships with a React console for end users and administrators, and the project describes itself as a source-level engineering reference for Java AI applications.

Two execution engines live side by side, selected with `ragent.engine.type`. The v1 `workflow` engine is a fixed pipeline written in code: rewrite, recognise intent, retrieve over several channels, assemble and generate. The v2 `agent` engine is built on the AgentScope ReAct loop: knowledge search, MCP tools and Skills become tools the model decides whether and how often to call, with long-term memory, context compression and a human confirmation step before write operations. The README recommends v1 for fast, controllable Q&A assistants and v2 for tasks that need planning and actions.

The backend is split into Maven modules — `infra-ai` (chat, embedding, rerank and VLM clients with model tiers, first-token probing, health state and fallback), `rag`, `agent`, `framework`, `system`, `bootstrap` and a standalone `mcp-server` example with weather, ticketing, sales and web-search tools. Production concerns are built in: Redis ZSET fair queuing and distributed concurrency limits, three-state circuit breaking across candidate models, RocketMQ transactional messages for chunk processing, SSE streaming with client-disconnect cancellation, Sa-Token authentication, and trace runs that can be sent to Langfuse. Models, vector stores, object storage, retrieval channels, ingestion nodes and MCP servers are all swapped through interfaces and configuration. The code and docs are in Chinese, and the project is licensed Apache-2.0.

## What it does

- Hybrid retrieval: vector, Elasticsearch keyword, LightRAG graph and web search channels in parallel, with dedup, RRF fusion and rerank
- Query understanding: term mapping, question rewrite and split, tree-shaped intent recognition and multi-knowledge-base routing
- Two engines: a fixed v1 workflow pipeline and a v2 AgentScope ReAct agent with MCP tools, Skills, long-term memory and human confirmation for write actions
- Model tiers with first-token probing, automatic fallback between candidate models and circuit breaking
- Orchestrated ingestion pipeline with MinerU parsing for rich documents, VLM image understanding, scheduled remote refresh and node-level logs
- React console with answer sources, original-text preview, feedback, RAG traces, audit logs and an agent run dashboard

## Getting started

Ragent is a full application, not a library: a Spring Boot backend, a React frontend and several middleware services. The project's local-dev guide uses IntelliJ IDEA with JDK 17 or later and Maven; the step-by-step docs are at nageoffer.com/ragent, and a hosted demo runs at nageoffer.com/ragent/demo/.

1. Clone the repository

   A Gitee mirror is also available at gitee.com/nageoffer/ragent.

```bash
git clone https://github.com/nageoffer/ragent.git
cd ragent
```

2. Start the middleware

   Docker Compose files for Milvus (with RustFS object storage and Attu) and RocketMQ live under resources/docker; resources/docker/lightweight has memory-limited variants for low-spec machines, and there are optional stacks for Langfuse and LightRAG with Neo4j. The default application.yaml also expects PostgreSQL on 127.0.0.1:5432 with a database named ragent and Redis on 6379.

```bash
docker compose -f resources/docker/milvus-stack-2.6.6.compose.yaml up -d
docker compose -f resources/docker/rocketmq-stack-5.2.0.compose.yaml up -d
```

3. Initialise the database

   For a new environment, run the full schema and then the initial data, in that order; the upgrades/ folder is only for existing deployments.

```bash
psql -h 127.0.0.1 -U postgres -d ragent -f resources/database/schema_pg.sql
psql -h 127.0.0.1 -U postgres -d ragent -f resources/database/init_data_pg.sql
```

4. Configure models and pick an engine

   Edit bootstrap/src/main/resources/application.yaml: datasource, Redis, object storage, the model providers the agent chat uses, and `ragent.engine.type` — `workflow` for the v1 pipeline or `agent` for the v2 ReAct engine. MCP servers go under `agent.mcp.servers`.

```yaml
ragent:
  engine:
    type: agent  # or workflow
agent:
  mcp:
    servers:
      - name: default
        url: http://localhost:9099
```

5. Run the backend and the console

   Start the startup class in the bootstrap module from your IDE; the API listens on port 9090 under /api/ragent. Then start the Vite frontend.

```bash
cd frontend
npm install
npm run dev
```

## When to use it

- Build an internal knowledge assistant on a Java and Spring Boot stack instead of a Python RAG framework
- Answer questions across several knowledge bases with intent routing, cited sources and user feedback
- Let an agent call business systems through MCP tools while requiring a human to confirm every write
- Study a complete RAG and agent codebase with tracing, rate limiting and model fallback already wired in

## Version history

- 2026-08-11 1.1.0: Added Elasticsearch keyword, LightRAG graph and web search channels with RRF fusion, a Parse → Chunk → Embed → Index ingestion kernel with MinerU and VLM support, answer sources with suggested follow-ups, database-managed Agent Profiles and Prompt Slots, business change auditing, and tier-based model routing. Existing 1.0.x deployments face breaking database, vector, storage and config changes.
- 2026-06-16 1.0.0: First stable release, covering ingestion, multi-channel vector retrieval with dedup and rerank, tree-shaped intent classification, MCP tool routing, multi-model routing, streaming answers and full-chain tracing, with a React 18 console.
