# ageerle/ruoyi-ai: a Java and Langchain4j platform for multi-agent AI apps

> RuoYi AI bundles model management, vector-backed knowledge bases, a visual workflow designer and Supervisor-mode agents into one Spring Boot stack. It is aimed at teams that want an admin panel and a user frontend out of the box rather than a library.

**ageerle/ruoyi-ai** — An enterprise AI development framework for building AI agents. It provides unified management of multi-provider LLMs, secure enterprise knowledge bases with high-precision retrieval, visual workflow orchestration and multi-agent coordination. Compatible with mainstream Agent Skill standards, it enables developers to efficiently build production-gra

- Repository: https://github.com/ageerle/ruoyi-ai
- Website: https://doc.ruoyiai.chat
- Stars: 5,732 · Forks: 1,414
- Language: Java
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/ageerle-ruoyi-ai

## The problem RuoYi AI addresses for Java teams

Most agent frameworks ship as a library. You get a client for a model provider and you assemble the rest: conversation storage, a retrieval pipeline, a tool registry, a UI, and some way for a non-engineer to change a prompt. RuoYi AI takes the opposite position. It is a full-stack application, and the README describes it as an out-of-the-box platform whose modules cover model management, knowledge management, tool management, workflow orchestration and multi-agent coordination.

The intended user is a Java team that needs to put an AI assistant in front of employees or customers and does not want to build the surrounding product. The repository is split into ruoyi-admin, ruoyi-common, ruoyi-extend and ruoyi-modules, with a pom.xml at the root, so the project follows the familiar RuoYi multi-module Maven layout. If your organisation already runs a RuoYi-based admin system, the conventions here will look familiar.

The trade-off is explicit. You inherit a large surface area with opinions about storage, authentication and deployment. A team that only wants to call a model and stream tokens back will find more machinery than it needs.

## How the model, knowledge and agent layers fit together

The README lists the core framework as Spring Boot 3.5.8 with Langchain4j, MySQL 8.0, Redis, and a vector database chosen from Milvus, Weaviate or Qdrant. That combination tells you the data flow: relational records and cache in MySQL and Redis, embeddings and retrieved chunks in the vector store, and prompt orchestration in the Langchain4j layer.

Model access is deliberately plural. The model management module names DeepSeek, Zhipu, MIMO, Bailian and OpenAI, and it also integrates external platforms: Coze, DIFY, FastGPT and RAGFlow. That means a request can be served either by a provider SDK or by delegating to a platform that already hosts the agent. The knowledge module handles document parsing for PDF, Word and Excel plus image analysis, then indexes into the vector database for retrieval.

On top of that sits the agent layer, described as an Agent framework based on Langchain4j with Supervisor mode orchestration, multiple decision models, and the ability to combine tools and skills. Tool integration uses the MCP protocol, and the project states compatibility with mainstream Agent Skill standards. Workflow orchestration is separate and visual: a drag-and-drop designer where nodes include model calls, email sending and manual review, executed with SSE streaming. Realtime communication uses WebSocket alongside SSE, and security is handled by Sa-Token with JWT.

## Installing RuoYi AI with Docker Compose

The README documents two Docker deployment methods and recommends the one-click path, which starts the backend, admin panel, user frontend and dependencies together from docs/docker/ruoyi-ai/docker-compose-all.yaml. It requires Docker Engine on Linux or macOS, or Docker Desktop on Windows, plus Docker Compose V2. The commands below are the Linux and macOS sequence as given in the README.

First clone the tagged release and create the environment file from the example, then pin the image version. The README notes that public GHCR images do not require a docker login.

```bash
git clone --depth 1 --branch v3.1.0 https://github.com/ageerle/ruoyi-ai.git
cd ruoyi-ai
cp docs/docker/ruoyi-ai/.env.example docs/docker/ruoyi-ai/.env
sed -i 's/^RUIYI_VERSION=.*/RUIYI_VERSION=v3.1.0/' docs/docker/ruoyi-ai/.env
```

Next pull the pre-built images and bring the stack up in detached mode, then check that the containers are running.

```bash
docker compose --env-file docs/docker/ruoyi-ai/.env \
  -f docs/docker/ruoyi-ai/docker-compose-all.yaml pull
docker compose --env-file docs/docker/ruoyi-ai/.env \
  -f docs/docker/ruoyi-ai/docker-compose-all.yaml up -d
docker compose --env-file docs/docker/ruoyi-ai/.env \
  -f docs/docker/ruoyi-ai/docker-compose-all.yaml ps
```

According to the README, the admin panel is then reachable at port 25666 with the default credentials admin / admin123, the user frontend at port 25137, and the backend API at port 26039. Replace SERVER_IP with the address of the machine you deployed to. On Windows, the README gives a PowerShell variant that uses Copy-Item and a -replace pipeline to edit the same .env file before running the same compose commands.

The first real use is to log into the admin panel, register a model provider under model management, and then create a knowledge base and upload a document so the retrieval path has something to index. The README does not walk through that sequence step by step; it points to https://doc.ruoyiai.chat for the documentation, so expect to read the docs site for the configuration screens.

## Where RuoYi AI is the wrong choice

The clearest limitation is the stack itself. This is a Java, Spring Boot and Maven project. If your team writes Python and expects to import an agent library into an existing service, RuoYi AI is not that. You would be adopting an application, its build system, its database schema and its admin conventions, and running it as a separate service.

The deployment surface is also wide. The README's own architecture section lists MySQL 8.0, Redis and a vector database, and the one-click Compose file starts the backend plus two frontends plus dependencies. That is a reasonable footprint for an internal platform and a heavy one for a prototype. The README does not document a lightweight single-container mode for evaluation.

The workflow designer is honest about its scope: the README says it currently supports model calls, email sending, manual review and other nodes. That wording signals an early node set, so a team expecting a general-purpose automation engine should check the current node list before designing around it.

Finally, the README does not document rollback or downgrade steps between releases. Version pinning is described, but what happens to database schema and vector indexes when you move from v3.0.0 to v3.1.0 is not covered in the README. Treat upgrades as something to test against a copy of your data.

## How this differs from a plain Langchain4j integration

The natural alternative is to use Langchain4j directly. Langchain4j is a Java library for integrating LLMs into applications, and RuoYi AI is built on it. The difference is what each one gives you.

With Langchain4j alone you write the service, choose and configure the vector store client, define the tool interfaces, and build or buy your own UI. You keep full control over the dependency graph and you deploy it inside whatever application you already have. Nothing is imposed on your database or your authentication scheme.

RuoYi AI sits one level up. It takes Langchain4j and adds the persistence, the Sa-Token and JWT security layer, the admin panel, the user frontend, the document parsing pipeline and the visual designer. You trade control over the internals for a working product surface. The same trade-off applies against platform-level alternatives such as DIFY, FastGPT or Coze, which the README lists as integrations rather than competitors: RuoYi AI can call out to them, and in that configuration it acts as the management and orchestration front end rather than the execution engine.

If you need to embed an agent inside an existing Java service with minimal new infrastructure, Langchain4j on its own is the smaller commitment. If you need a deployed assistant with users, roles and a knowledge base, the assembled platform saves the integration work.

## Licence, maintenance and upgrade cost

The repository is licensed under MIT, and the README carries the MIT badge. For most adopters that means the usual permissions to use, modify and redistribute the code with the licence and copyright notice retained, but the licence covers the code in this repository only. The README also references a Commercial Edition hosted at web.ruoyiai.chat with WeChat QR code login, and the relationship between that offering and the MIT-licensed code is not explained in the README. If you plan to resell or host this for third parties, read the LICENSE file and clarify that boundary yourself rather than assuming the badge settles it.

On maintenance, the repository is not archived and the last push was on 2026-09-08, which is recent. Releases are tagged: v3.1.0 on 2026-08-04, v3.0.0 on 2026-04-13 and v2.1.0 on 2025-05-30. The gap between v2.1.0 and v3.0.0 is roughly eleven months, so major versions do not arrive on a fixed cadence.

Upgrade cost is the practical concern. The deployment instructions pin RUIYI_VERSION in docs/docker/ruoyi-ai/.env, which suggests image tags are the intended upgrade lever. Because the stack includes MySQL and a vector database, an upgrade can involve schema changes and re-indexing, and the README does not describe a migration procedure. Budget for a staging deployment that mirrors production data before you move a tag.

## Conclusion

Adopt RuoYi AI if you already run Java and Spring Boot services and want a working admin panel plus user frontend instead of wiring a chat UI yourself. Skip it if your stack is Python, since the agent layer is Langchain4j and the whole build is Maven and Spring Boot. Before committing, verify that the vector store you intend to use is actually configured in docs/docker/ruoyi-ai/.env, and pin RUIYI_VERSION to v3.1.0 rather than tracking latest, because the configuration surface moves between releases.

## FAQ

### What is RuoYi AI and who is it for?

It is a full-stack enterprise AI platform built on Spring Boot 3.5.8 and Langchain4j, covering model management, knowledge bases with RAG, visual workflow orchestration and multi-agent coordination. It targets Java teams that want an admin panel and user frontend included rather than assembling those pieces themselves.

### How do I install RuoYi AI with Docker?

The README recommends cloning the v3.1.0 tag, copying docs/docker/ruoyi-ai/.env.example to .env, pinning RUIYI_VERSION=v3.1.0, then running docker compose with docker-compose-all.yaml to pull and start all services. The admin panel comes up on port 25666 and the user frontend on port 25137.

### Which vector databases does RuoYi AI support for its knowledge base?

The README lists Milvus, Weaviate and Qdrant as the supported vector databases alongside MySQL 8.0 and Redis. Document parsing covers PDF, Word and Excel plus image analysis before indexing.

## Sources

- [ageerle/ruoyi-ai on GitHub](https://github.com/ageerle/ruoyi-ai)
- [License: MIT](https://github.com/ageerle/ruoyi-ai/blob/main/LICENSE)
- [Project website](https://doc.ruoyiai.chat)
- [README](https://github.com/ageerle/ruoyi-ai/blob/main/README.md)
- [Releases](https://github.com/ageerle/ruoyi-ai/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ageerle-ruoyi-ai