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/.
Clone the repository
A Gitee mirror is also available at gitee.com/nageoffer/ragent.
git clone https://github.com/nageoffer/ragent.git
cd ragentStart 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.
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 -dInitialise 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.
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.sqlConfigure 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`.
ragent:
engine:
type: agent # or workflow
agent:
mcp:
servers:
- name: default
url: http://localhost:9099Run 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.
cd frontend
npm install
npm run devCommands and code are distilled from the project's own documentation — always check the official repo for the latest.
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
Every verified update to Ragent that AI/TLDR tracked, newest first — each links to our coverage and the official changeset.
- 2026-08-111.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-161.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.
How Ragent compares
Ragent alongside other open-source rag frameworks & platforms tools AI/TLDR tracks, ranked by GitHub stars.
| Tool | Stars | What it does |
|---|---|---|
| Dify | ★ 158k | An open-source platform with a visual workflow builder for creating LLM and RAG applications without writing much code. |
| graphify | ★ 123k | Turns a folder of code, docs, PDFs and images into a local knowledge graph with tree-sitter AST parsing and Leiden communities — queryable by agents over MCP, no vector store. |
| RAGFlow | ★ 91.6k | A RAG engine built around deep document understanding that turns complex files into a grounded, citation-backed question-answering layer. |
| Context7 | ★ 62.6k | Context7 pulls current, version-specific documentation and code examples for any library and feeds them into your LLM, available as a CLI skill or an MCP server. |
| Pathway | ★ 62.2k | A Python framework with a Rust streaming engine that keeps ETL, real-time analytics and RAG pipelines continuously up to date as source data changes. |
| LightRAG | ★ 40k | A graph-based RAG system that builds an entity-and-relationship knowledge graph for fast retrieval and easy incremental updates. |
| Quivr | ★ 39.6k | Quivr is an open-source RAG framework that ingests your documents and answers questions about them, working with any LLM and any file type. |
| Ragent | ★ 4.2k | A Java agentic RAG platform covering ingestion, hybrid retrieval, MCP tools and a full admin console |