ragent

<p align="center"> <a href="https://github.com/nageoffer/ragent"> <picture> <source srcset="assets/ragent-ai-banner.png"> <img src="assets/ragent-ai-banner.png" alt="Ragent AI"> </picture> </a> </p> <p align="center"> <strong>The first stop for backend programmers to transform into AI engineers</strong><br/> </p> <p align="center"> <a href="https://github.com/nageoffer/ragent/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/nageoffer/ragent?style=flat-square&logo=github&color=e8b227" /></a>&nbsp; <a href="https://github.com/nageoffer/ragent/network/members"><img alt="GitHub forks" src="https://img.shields.io/github/forks/nageoffer/ragent?style=flat-square&logo=github&color=2d6a8a" /></a>&nbsp; <a href="https://github.com/nageoffer/ragent/graphs/contributors"><img alt="Contributors" src="https://img.shields.io/github/contributors/nageoffer/ragent?style=flat-square&color=b56e7a" /></a>&nbsp; <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-4a9b8f?style=flat-square" /></a> <img src="https://img.shields.io/badge/Spring%20AI-2.0-6DB33F?style=flat-square&logo=springboot&logoColor=white" /> </p> ## 🚀 What is Ragent AI? Ragent is an enterprise-level Agentic RAG platform that covers the entire chain from document entry to intelligent Q&A. - **Multi-channel retrieval**: Multi-channel parallel retrieval, deduplication and reordering, balancing accuracy and recall. - **Intent recognition**: Tree-like multi-level classification, active guidance and clarification when confidence is insufficient, extending model, prompt word, topK and other core parameters. - **Model engine**: Model scheduling, first package detection, health check, automatic downgrade, model failure does not affect service. - **MCP integration**: Non-knowledge-based intent automatically calls business tools, retrieval and tools seamlessly integrated. - …… This project has gone through real-world scenarios and has a set of engineering practices that have been tested and improved.  ## 🧭 Quick Navigation > If you like it, please star and collect it. All links will open in a new tab. <p align="left"> <a href="https://github.com/nageoffer/ragent/stargazers"> <img src="assets/star-me.svg" alt="Star this repo" /> </a> </p> | &nbsp; | Link | Description | |:---:|:---|:---| | 📖 | <a href="https://nageoffer.com/ragent" target="_blank">Official Documentation</a> | Complete documentation for Ragent AI | | 🚀 | <a href="https://nageoffer.com/ragent/demo/" target="_blank">Online Experience</a> | Experience Ragent AI without deployment | | ⚡ | <a href="https://nageoffer.com/ragent/local-dev/" target="_blank">Quick Start</a> | Local deployment of Ragent AI frontend and backend projects | | 📝 | <a href="https://nageoffer.com/ragent/interview/" target="_blank">Resume Writing</a> | How to write this project into your resume | | 💡 | <a href="https://nageoffer.com/ragent/why-springai-langchain4j/" target="_blank">Why not use Spring AI / LangChain4j</a> | Technical selection considerations | ## 🤝 Contribution Ragent AI is still evolving. Welcome to participate and contribute to the project. <p align="left"> <a href="https://github.com/nageoffer/ragent/graphs/contributors"> <img src="https://contrib.rocks/image?repo=nageoffer/ragent&columns=8" /> </a> </p> <details> <summary><b>📑 Table of Contents</b>（click to expand）</summary> - [Why learn AI projects](#why-learn-ai-projects) - [1. Current situation in school recruitment](#1-current-situation-in-school-recruitment) - [2. Current situation in social recruitment](#2-current-situation-in-social-recruitment) - [3. The problem is, how to learn?](#3-the-problem-is-how-to-learn) - [Common RAG misconceptions](#rag-common-misconceptions) - [1. Just call an API to use RAG](#1-just-call-an-api-to-use-rag) - [2. RAG is just "retrieval + generation"](#2-rag-is-just-retrieval--generation) - [3. Using OpenAI/LangChain is an enterprise-level solution](#3-using-openailangchain-is-an-enterprise-level-solution) - [4. Only focus on the model, ignoring engineering capabilities](#4-only-focus-on-the-model-ignoring-engineering-capabilities) - [Ragent core design](#ragent-core-design) - [Project quality](#project-quality) - [1. Code scale](#1-code-scale) - [2. Engineering specifications](#2-engineering-specifications) - [3. Scalability](#3-scalability) - [4. Production-level features](#4-production-level-features) - [5. Beautiful console](#5-beautiful-console) - [6. Differences from other projects on the market](#6-differences-from-other-projects-on-the-market) - [Frequently Asked Questions](#frequently-asked-questions) - [1. What can I learn?](#1-what-can-i-learn) - [2. Suitable crowd](#2-suitable-crowd) - [Why open source?](#why-open-source) </details> ## 💡 Why learn AI projects? The AI wave is here, and Java programmers can't avoid it. Whether you're working on business systems or middleware, you'll be asked about AI-related topics during interviews. RAG, Agent, MCP - these questions are becoming more frequent. It's safe to say that **AI has changed from a bonus to a must-answer question**. But to be honest, for most application-layer developers, it's not cost-effective to focus on fine-tuning large models, distillation, and Transformer principles. What's practical is mastering RAG and Agent, which are application-layer technologies that can be implemented and have real-world applications. <details> <summary><b>School recruitment / social recruitment / how to learn?</b>（click to expand）</summary> ### 1. Current situation in school recruitment Resumes are filled with CRUD projects - e-commerce, food delivery, blogs - interviewers are tired of this. When others are still writing XX management systems based on SpringBoot, your resume with a complete AI project stands out. Large factories prioritize candidates with a sense of new technology, and AI projects directly prove your learning ability and technical vision. ### 2. Current situation in social recruitment Since 2024, almost all technical teams have been moving towards AI. Many companies have included AI-related experience in their job descriptions. You may be proficient in Java/Go, but interviewers will ask: What do you know about LLM? Have you done RAG? How is vector retrieval implemented? If you can't answer, you'll lose a bargaining chip. **In short, there are three core reasons to learn AI projects:** 1. **Resume differentiation**. With AI project experience, your resume has a higher pass rate. It's not because AI is magical, but it proves you're not just repeating the wheel. 2. **Interview topics to discuss**. AI projects involve deep technical stacks - Embedding, vector databases, Prompt engineering, model call chains, retrieval strategies - each point can be discussed in depth. 3. **Practical work applications**. AI is not a lab toy; enterprises have large-scale implementations. Learning now is to pave the way for your career development in the next three to five years. ### 3. The problem is, how to learn? Many people follow Bilibili videos or GitHub open-source projects, thinking they've learned. But when asked deep questions during interviews, they're stuck. The reason is simple: those demo-level projects are far from what enterprises really use. Some students attend training camps, only to find they're all Python. Unfamiliar language, unfamiliar ecosystem, limited gains, and returning to Java still unsure. Based on these issues, I decided to create a RAG practical project called **Ragent**. This project covers mainstream RAG technical points and involves MCP and Agent scenarios. More importantly, it's not a toy project; I've **actually implemented RAG systems** in companies, solving real business problems. </details> ## ⚠️ Common RAG misconceptions Many projects claim to be RAG, but most are either toy demos or conceptual packaging. Before learning, let's clarify these misconceptions. The RAG process is as follows:  <details> <summary><b>4 common misconceptions in detail</b>（click to expand）</summary> ### 1. Just call an API to use RAG Many tutorials involve calling OpenAI's Embedding interface, putting data into a vector database, and generating answers with LLM - that's it. This is more like running a demo than actually using RAG. A real RAG system involves many considerations: how to split documents for better effects? What if retrieval recall is not enough? How to fuse and rank multi-channel retrievals? How to control hallucinations? These are what interviewers will ask. Running a demo and creating a deployable system have a huge gap - not just code quantity, but deep understanding of each link. ### 2. RAG is just "retrieval + generation" The name Retrieval-Augmented Generation makes it seem like just retrieval and generation. But in actual engineering, a usable RAG system involves at least these links: - **Data processing**: PDF, Word, PPT, web pages - various formats need to be parsed into clean text. - **Chunking strategy**: too large chunks have poor retrieval, too small chunks lose context. Different documents may need different strategies. - **Problem rewriting**: users ask "how to reimburse", you take these four characters to retrieve, will it work? Multi-round dialogue users say "how to apply", without context, the system doesn't know what they're asking. - **Intent recognition**: users want to query the knowledge base or call business systems? Is it casual chat or a serious question? Wrong paths lead to wrong answers. - **Retrieval strategy**: pure vector retrieval is weak for precise matching. Users ask for an order number, vector retrieval may not find it. How to fuse hybrid retrieval, how many top-k to select, and whether to reorder are all trade-offs. - **Session memory**: 20 rounds of dialogue are fed into the model? Token cost is not affordable. Only recent rounds are considered? Key context may be lost. Memory compression, summarization, and persistence are separate mechanisms. Each link has pitfalls, and each link is worth exploring in depth. ### 3. Using OpenAI/LangChain is an enterprise-level solution OpenAI/LangChain is a good tool, but directly using it doesn't mean it's an enterprise-level solution. Enterprise scenarios involve: - Large-scale document incremental updates, not possible to rebuild indexes every time - Multi-tenant isolation and permission control, different departments see different knowledge bases - High-concurrency retrieval performance, model call cost control and fault tolerance - Request risk control, preventing users from obtaining sensitive information or malicious attacks - Model load balancing, multi-supplier switching and downgrade strategies - Observability, effect monitoring, and user feedback collection These issues OpenAI/LangChain's QuickStart won't tell you, but interviewers and actual business will test you. ### 4. Only focus on the model, ignoring engineering capabilities RAG project core competitiveness lies not in the strength of the model but in engineering capabilities. Same model, different retrieval strategies, Prompt design, and chunking granularity can have vastly different effects. For example, users ask "how to replace printer cartridges", documents say "cartridge replacement steps". Keyword search won't match, but vector retrieval understands they're related. Behind this is Embedding model selection, vector database optimization, and retrieval result reordering - every step is an engineering decision, not just replacing a more expensive model. In interviews, those who can explain these engineering details have more persuasive power. </details> ## 🏗️ Ragent core design Adopting a front-end and back-end separation architecture, the back-end is divided into four Maven modules. Here, it's necessary to emphasize that layering is not just for show; it's to solve practical problems: `framework` layer provides business-unrelated general capabilities, `infra-ai` layer shields differences between model suppliers, and `bootstrap` layer focuses on business logic. Switching model suppliers doesn't require changing business code, and switching business logic doesn't affect infrastructure.  A user's question, in Ragent AI service, goes through the core chain as follows: > In actual project code, the logic is more complex than the chart. The figure only shows the core process, and there are many details and optimizations involved in the implementation.  <details> <summary><b>Multi-channel retrieval architecture, model routing, and fault tolerance</b>（click to expand）</summary> Retrieval is the core of RAG systems. Ragent's retrieval engine adopts a multi-channel parallel + post-processing pipeline architecture:  Each channel executes independently, without affecting each other, and is scheduled in parallel through a thread pool. Post-processors are connected in series, like a pipeline, to refine retrieval results step by step. In a production environment, it's impossible to rely on only one model supplier. Ragent's model routing mechanism solves this problem:  Key design: three-state circuit breaker, used to protect the system from continuously calling failed models.  Documents, from upload to retrieval, go through a pipeline based on node orchestration: <img src="assets/ingestion-pipeline.png" width="25%" /> Each node's configuration is stored in the database, supporting conditional execution and output chain passing. Each task and node has independent execution logs, and issues can be precisely located to a certain step. Ragent doesn't use design patterns just for show; each pattern corresponds to a specific engineering problem: | Design Pattern | Application Scenario | Problem Solved | | ---------- | --------------------------------------------- | ---------------------------------------- | | Strategy Pattern | SearchChannel, PostProcessor, MCPToolExecutor | Retrieval channels, post-processors, and MCP tools are pluggable and replaceable | | Factory Pattern | IntentTreeFactory, StreamCallbackFactory | Complex object creation logic is centrally managed | | Registry Pattern | MCPToolRegistry, IntentNodeRegistry | Components are automatically discovered and registered, and new tools are added without configuration | | Template Method | IngestionNode base class | Unified execution process for ingestion nodes, subclasses focus on core logic | | Decorator Pattern | ProbeBufferingCallback | First package detection capability is added without modifying the original callback | | Responsibility Chain | Post-processor chain, model downgrade chain | Multiple processing steps are connected in series and flexibly combined | | Observer Pattern | StreamCallback | Asynchronous notification of streaming events | | AOP | @RagTraceNode, @ChatRateLimit | Link tracking and current limiting logic are decoupled from business code | </details> ## ✨ Project quality To say a project is enterprise-level, it's not just about talking; it depends on actual engineering quality. Let's evaluate Ragent from several dimensions: ### 1. Code scale - Back-end Java code: about 40,000 lines, covering 400+ source files - Front-end TypeScript/React code: about 18,000 lines - Database design: 20 business tables, covering complete business domains such as sessions, messages, knowledge bases, documents, chunking, intent trees, ingestion pipelines, link tracking, users, etc. - Front-end pages: 22 pages/components, including chat interface, management backend (dashboard, knowledge base management, intent tree editing, ingestion monitoring, link tracking, user management, system settings) > This is not a demo that can be finished over a weekend; it's a system with a complete business loop. </details> ### 2. Engineering Specifications - **Layered Architecture**: framework / infra-ai / bootstrap with clear responsibilities for each layer, eliminating the mixture of infrastructure code and business code. - **Design Pattern Practice**: strategy, factory, observer, decorator, template method, responsibility chain, and facade - each solving actual scalability or decoupling issues. - **framework Infrastructure Layer**: an independent Maven module with 23 classes covering 10 cross-cutting concerns - a three-level exception system + unified exception interception, dual-dimensional idempotence, Snowflake distributed ID algorithm, user context and Trace context cross-thread transmission, `SseEmitterSender` thread-safe SSE encapsulation, unified response body and error code specification. Business modules only need to introduce dependencies and add annotations, with zero boilerplate code. - **Queue-based Concurrent Limiting**: distributed queuing and limiting based on Redis signals + ordered sets (ZSET) + Pub/Sub notifications. Requests first enter the ZSET queue, and then dequeue through Lua script atomic judgment within the head window. Semaphores control the maximum number of concurrent requests and support automatic permission expiration (preventing deadlock). Cross-instance Pub/Sub broadcasts wake up, and local merged notifications avoid the thundering herd effect. Queued timeout automatic kick-out, full process SSE push queuing status. - **8 Dedicated Thread Pools + TTL Propagation**: configured with 8 independent thread pools (MCP batch invocation, RAG context assembly, multi-channel retrieval, internal retrieval, intent classification, memory summarization, model streaming output, and dialogue entry), each with different queue types and rejection strategies. All thread pools are wrapped with `TtlExecutors` to ensure user context and Trace information are not lost in asynchronous threads. - **Three-State Circuit Breaker**: implemented with a classic three-state circuit breaker (CLOSED → OPEN → HALF_OPEN), each model independently maintaining a health state. When the failure count reaches the threshold, it automatically breaks the circuit. After a cooling period, it enters a half-open state to detect requests. If the detection is successful, it recovers; if it fails, it continues to break the circuit. Cooperating with a priority degradation chain, if one model fails, it automatically switches to the next candidate, with no perception at the business layer. > The project extensively applies concurrent threads, suggesting cooperation with the [oneThread dynamic thread pool framework](https://nageoffer.com/onethread) in the community for more learning benefits. ### 3. Scalability This is a key indicator for measuring whether a project is enterprise-level. Ragent's core modules all reserve extension points: - **Add Retrieval Channels**: implement the `SearchChannel` interface, register as a Spring Bean, and automatically take effect. - **Add Post-Processors**: implement the `SearchResultPostProcessor` interface and automatically join the processing chain. - **Add MCP Tools**: implement the `MCPToolExecutor` interface and automatically be discovered by `DefaultMCPToolRegistry`. - **Add Ingestion Nodes**: implement the `IngestionNode` interface and can be inserted into any position in the Pipeline. - **Add Model Suppliers**: implement the `ChatClient` interface at the `infra-ai` layer and configure the candidate list to participate in routing. > No need to modify framework code or hard-coded lists in configuration files; just add an implementation class. This is the correct way to open the door to interface-based programming. ### 4. Production-Level Features Many open-source projects stop at being able to run, but Ragent also considers these issues that must be faced in a production environment: | Feature | Description | |:---|:---| | **Limiting** | supports global concurrent restriction and user-level limiting to prevent model invocation from being overwhelmed | | **Circuit Breaking** | model health check + failure count, automatic circuit breaking for unavailable models to avoid repeated timeouts | | **Observability** | based on AOP's full-link Trace, with records of time-consuming, input-output, and exception information for each link | | **Streaming Output** | SSE real-time push, with a first-packet detection mechanism to ensure users have no perception during model switching | | **Session Management** | memory compression, summary persistence, TTL expiration, to prevent OOM or token explosion due to increased chat rounds | | **Authentication and Authorization** | based on Sa-Token's user authentication system, not a bare API | ### 5. Exquisite Console Ragent provides a complete visual console covering **ordinary users and administrator users** with two usage scenarios, a simple and intuitive interface, and efficient operations. The system has undergone multiple rounds of AI-assisted design optimization to ensure functional integrity while providing a more modern and friendly interactive experience. #### 5.1 User Question and Answer Interface After users visit Ragent's homepage, they can directly input questions in the input box to initiate a Q&A session, while also supporting the opening of **deep thinking mode** to obtain higher-quality answers. Below the input box, example question labels are provided for users to click and automatically fill in questions, facilitating quick experience of system capabilities. - supports natural language input - supports quick filling of example questions - supports deep thinking mode  After users submit questions, the model generates answer results in real-time and provides a good reading experience: - supports Markdown format rendering - supports image content display - supports code highlighting - supports answer evaluation (likes / dislikes)  #### 5.2 Management Backend Ragent provides a fully functional management backend for system configuration and operation management. Administrators can complete model management, system configuration, and data management operations through the backend. <details> <summary><b>Management Backend Interface Screenshot</b> (click to expand)</summary>       </details> To avoid the common rough interface experience of traditional systems, Ragent's console has undergone multiple rounds of AI-assisted design and optimization, iteratively improving and perfecting the interface effect.  ### 6. Differences from Other Projects on the Market | Comparison Dimension | Typical Demo Project | Ragent | | -------- | ------------------ | -------------------------------- | | Retrieval Method | single vector retrieval | multi-channel parallel + post-processing pipeline | | Intent Recognition | none | tree-like intent system + ambiguity guidance | | Problem Handling | original problem direct retrieval | rewriting + splitting + context completion | | Model Invocation | single model, failed if failed | multi-candidate routing + first-packet detection + automatic degradation | | Session Memory | full amount given to model | sliding window + automatic summary compression | | Document Ingestion | manual script | programmable Pipeline + node logs | | Observability | none | full-link Trace | | Tool Invocation | none | MCP protocol integration | | Management Backend | none | complete React management interface | ## ❓ Frequently Asked Questions In one sentence: after learning Ragent, you can not only discuss RAG/Agent technical depth with interviewers but also prove your Java engineering level. <details> <summary><b>What Can Be Learned / Suitable for Whom?</b> (click to expand)</summary> ### 1. What Can Be Learned? Ragent not only teaches you how to invoke APIs but also lets you understand the entire process of a RAG system from scratch. Roughly speaking, you can gain: - **RAG Full-Chain Engineering Capability**: document parsing, chunking strategy, Embedding vectorization, multi-channel retrieval, re-ranking, Prompt assembly, streaming generation, each link to do, why do it this way. - **AI Application Architecture Design**: intent recognition system, problem rewriting and splitting, session memory management, MCP tool invocation, these are AI applications different from traditional CRUD systems core capabilities. - **Model Engineering Practice**: multi-model routing, priority scheduling, first-packet detection, circuit breaking and degradation, solving the problem of model instability in the production environment. - **High-Quality Java Engineering Capability**: layered architecture, design pattern practice, distributed concurrent limiting, multi-thread pool management and context transmission, full-link tracking, these capabilities are not limited to AI projects, but also add points to any Java backend position. - **Complete Front and Back End Project Experience**: backend Spring Boot 3 + frontend React 18, from API design to page interaction, complete full-stack project experience. ### 2. Suitable for Whom **School Recruit Students:** - **Java Backend Direction of School Students**: already have commercial, takeaway and other conventional projects on the resume, need a distinguishing project to pull open the gap. Ragent can let you in the interview to chat AI + engineering, rather than the same CRUD. - **Want to Turn AI Application Direction of Students**: interested in large models, but do not want to start from Python and algorithm. Ragent based on Java technology stack, learning curve smooth, no need to switch language ecology. - **Prepare Intern / Autumn / Spring Recruitment of Students**: large factory recruitment more and more attention to candidates on new technology sensitivity, resume have AI project experience, can directly prove your learning ability and technical vision. **Social Recruitment Students:** - **1-3 Year Experience Java Development**: daily write business code, want to AI direction transformation but do not know where to start. Ragent technical stack you are familiar with, learn AI application layer things, fast and can land. - **3-5 Year Experience Backend Development**: technical ability is not bad, but the interview was asked AI related problems can not answer, less a talk about salary bargaining chip. Through Ragent to fill RAG, Agent, MCP these knowledge points, the interview can chat have depth. - **Want to Jump to AI Team Developers**: more and more JD requirements have AI related experience, Ragent can help you quickly establish RAG system global cognition, interview no longer just talk on paper. </details> ## 🌟 Why Open Source? The reason is simple: **enough confidence in project quality**. Architecture design, code implementation, engineering specifications, every line can withstand scrutiny. Good or not you clone down to see - directory structure, submission records, annotation specifications, all are open. <details> <summary><b>Open Source Background and Value</b> (click to expand)</summary> Previously, when doing the offer community, the first business system 12306 chose to open source, harvested <a href="https://github.com/nageoffer/12306"><img src="https://img.shields.io/github/stars/nageoffer/12306?style=flat-square&logo=github&label=GitHub" style="vertical-align: middle;" /></a> <a href="https://gitee.com/nageoffer/12306/stargazers"><img src="https://gitee.com/nageoffer/12306/badge/star.svg?theme=dark" style="vertical-align: middle;" /></a>, also got many students' recognition and trust. This time, Ragent as the community in the AI field of the first project, also choose open source - since the code quality can withstand the test, there is no need to hide. There are not many projects on the market that dare to put all code out, Ragent dare to do this, because the above-mentioned capabilities - multi-channel retrieval, intent recognition, model fault tolerance, full-link tracking - are not PPT architecture diagrams, but you can run up, can breakpoint debugging, can line-by-line reading of real code. Open source means what for you: - **Source Code is Document**: want to understand how a module is implemented, directly flip code, more accurate and timely than any tutorial. - **Local Debugging**: breakpoint hit to any line, follow a request to complete the entire RAG link, understand deeper than ten times the architecture diagram. - **Can Participate in Contributions**: find Bug to mention Issue, have optimization ideas to mention PR. Participate in an enterprise-level AI open-source project, which is a highlight of the resume. - **Continuous Iteration and Update**: the project will continue to evolve, Star and Watch can get the new features in the first place. </details> <p align="center"> <a href="https://www.star-history.com/?repos=nageoffer%2Fragent&type=date&legend=top-left"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=nageoffer/ragent&type=date&theme=dark&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=nageoffer/ragent&type=date&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/image?repos=nageoffer/ragent&type=date&legend=top-left" /> </picture> </a> </p> <p align="center"> If you think the project is good, give it a Star, which is the best recognition for open-source authors! </p>