Ragent is a Java application platform for Agentic RAG that covers the full path from document ingestion to question answering. It is written as a source-level engineering reference for Java developers moving into AI application work, and it runs as a modular monolith with a Spring Boot backend and a React console for both end users and administrators.
Two execution paths coexist. The v1 path is a fixed workflow: query rewriting, intent recognition, parallel retrieval, and answer assembly run in a set order, which suits knowledge assistants with a stable retrieval route. The v2 path is a ReAct agent built on AgentScope, where knowledge retrieval, MCP tools, and skills become tools the model chooses between inside a reasoning loop, with context trimming and compression, long-term memory across sessions, and configurable human confirmation before write operations.
Retrieval runs vector, keyword, knowledge-graph, and web-search channels in parallel, then deduplicates, fuses results with reciprocal rank fusion, and reranks. Question understanding adds query-term mapping, rewriting and splitting, a tree-shaped intent model, and routing across multiple knowledge bases. Model access goes through tiers with first-token probing, health checks, and circuit-breaker fallback across candidate models, so a new provider plugs in by implementing the chat, embedding, or rerank client interfaces.
Operational mechanisms include Redis fair queuing with distributed concurrency control, RocketMQ transactional messages for chunking, idempotency, an orchestrated ingestion pipeline with node logs and scheduled remote-document refresh, SSE streaming that separates thinking, answer, sources, and suggested follow-ups, and per-run trace records. Langfuse is wired in for per-session views of model reasoning, tool calls, latency, and token use. The backend is split into seven Maven modules (AI clients, system, RAG, agent, bootstrap, framework, and a sample MCP server built on the MCP Java SDK with weather, ticketing, sales, and web-search tools).
Features
- Hybrid retrieval: vector, keyword, knowledge-graph, and web-search channels recalled in parallel, with deduplication, reciprocal rank fusion, and reranking
- Question understanding: query-term mapping, question rewriting and splitting, tree-shaped intent recognition, and routing across multiple knowledge bases
- ReAct agent path: an AgentScope execution engine that treats knowledge retrieval, MCP tools, and skills as tools chosen inside a reasoning loop
- Model fallback: model tiers, first-token probing, health checks, and a three-state circuit breaker that switches between candidate models on timeout, empty response, or error
- MCP tooling: remote tool discovery through AgentScope, schema validation of tool parameters, and human confirmation before write operations
- Session memory: the most recent N messages combined with a persisted summary, plus three-layer context management and cross-session long-term memory on the agent side
- Traffic protection: Redis sorted-set fair queuing with Lua atomic acquisition, expiring semaphores, and Pub/Sub wake-up
- Ingestion pipeline: orchestrated nodes with task state, per-node logs, failure localization, and a state machine for scheduled remote-document refresh
- Streaming answers: SSE events for thinking, body, sources, and suggested questions, with global timeouts and cancellation on client disconnect
- Evidence and feedback: cited sources with original-text preview, follow-up questions, and thumbs up or down on answers
- Observability: trace run and node records with timing, inputs, outputs, and exceptions, a Langfuse view of reasoning and token use, and an admin dashboard with configuration change diffs
- Admin console: React screens for knowledge bases and chunks, knowledge graphs, intent trees, query mappings, ingestion jobs, agent skills, users, and audit logs
