Agents-Flex: A Modular Java Agent Framework Without a Fixed Runtime
Agents-flex is A lightweight Java AI agent development framework (positioned as a counterpart to Spring AI). It supports features such as RAG, MCP, Skills, Text2SQL , LLM Wiki, Sub-agents, Web Search, TTS (synchronous and streaming), and STT.
At a glance
- What is it?
- Agents-Flex is an Apache-2.0 Java framework that splits LLM calls, tools, agents, RAG, MCP and speech into separate Maven modules. The design favours composition over a single opinionated runtime, and that choice shapes both its strengths and its rough edges.
- Who is it for?
- Agents-Flex fits Java teams that already run Spring Boot or plain JVM services and want to pull in only the pieces they need, for example agents-flex-chat-openai plus agents-flex-store-redis, without adopting a full application framework. It is a poor fit if you need a single stable orchestration API across a long-lived codebase, since the module list is still expanding and the MCP module alone requires JDK 17 while most others target JDK 8.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Java, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Java gap Agents-Flex Tries to Fill
Java developers building LLM features usually face two options: adopt a full application framework, or write provider-specific HTTP glue by hand. Agents-Flex positions itself between those. The README describes it as a lightweight framework that organizes LLM calls, Tool Calling, Agents, RAG, vector stores, Embedding, image generation, audio, MCP, Skills and Text2SQL into clear modules, so developers can compose only what they need without being locked into a specific runtime. The stated audience is concrete: intelligent customer service, enterprise knowledge bases, natural-language data analysis, Agent workflows, model gateways, AI-assisted office tools and Java services that connect to several model providers at once. The last item matters most. If your service talks to exactly one provider and always will, a framework adds a dependency you do not need. If it talks to OpenAI-compatible endpoints, Qwen, Ollama, DeepSeek and LiteLLM, the unified ChatModel interface is the actual product.
How the Module Graph Is Laid Out
The architecture is a set of Maven artifacts rather than one jar. agents-flex-core holds the abstractions: Chat, Prompt, Message, Tool, Memory, Document, Store and observability. Provider integrations sit in sibling modules, so agents-flex-chat covers OpenAI-compatible APIs, Qwen, Ollama, DeepSeek and LiteLLM, while agents-flex-embedding covers OpenAI, Ollama and Qwen. Persistence is split further: agents-flex-store holds vector stores (Redis, Qdrant, Chroma, Pgvector, MariaDB, Milvus, OpenSearch, Elasticsearch, Alibaba Cloud, Tencent Cloud), and agents-flex-agent-store handles JDBC and Redis persistence for Agent runs, commands, events and artifacts. The core interfaces are ChatModel, EmbeddingModel, ImageModel and RerankModel. According to the README, the same Prompt, Options, interceptor and context mechanisms work for both normal chat and streaming output, which is the kind of consistency that usually breaks first when a framework grows by accretion. Two modules are worth calling out because they are unusual in this space: agents-flex-async-task handles submit-and-poll provider jobs with durable tracking and scheduling, and agents-flex-agent describes a durable runtime with snapshot recovery, tool approval, Worker leases, middleware and event streams.
Getting a First Call Running
Installation is standard Maven. For plain Java the README shows the aggregate BOM, com.agentsflex:agents-flex-bom at version 2.2.9. For Spring Boot it shows com.agentsflex:agents-flex-spring-boot-starter, and it notes you can depend on individual modules instead, with agents-flex-chat-openai and agents-flex-store-redis as the examples. The quick start builds a chat model through a config builder and calls chat() with a string. The README's sample sets endpoint to https://ai.gitee.com, provider to GiteeAI, model to Qwen3-32B, and reads the key from the GITEE_API_KEY environment variable. The README explicitly says to replace endpoint, model and apiKey with your own model service configuration, so treat those values as placeholders, not defaults. Versioning is centralized: the README states the repository version is defined by the revision property in the root pom.xml and is currently 2.2.9, matching the latest listed release v2.2.9 from 2026-09-03. Requirements are split by module: most modules need JDK 8 or later, agents-flex-mcp needs JDK 17 or later, and the build tool is Maven.
Where the JDK Split and Module Count Bite
The JDK requirement is the first practical constraint. A team on Java 8 can use the core, chat, embedding and store modules, but cannot add agents-flex-mcp without moving the build to 17. In a monorepo with several services that is a real decision, not a footnote. The second constraint is breadth. The module table lists over thirty artifacts, including several near-neighbours: agents-flex-skills, agents-flex-skills-artifact, agents-flex-skills-sandbox, agents-flex-skills-open-sandbox and agents-flex-skills-aio-sandbox. That granularity lets you avoid dragging in a sandbox runtime you do not use, but it also means picking the right artifact is part of the work. Nothing in the supplied material states a stability guarantee per module, and the release cadence (v2.2.7 on 2026-08-10, v2.2.8 on 2026-08-17, v2.2.9 on 2026-09-03) is roughly weekly, which is fast enough that pinning exact versions and reading release notes before upgrading is the safer habit. The README also gives no guidance on which modules are considered production-ready versus experimental, so that distinction has to be inferred from your own reading of the code.
RAG, Text2SQL and the Safety Interceptors
The RAG story is deliberately decomposed. The README lists document models, parsing, splitting, Embedding, vector stores, retrieval and Rerank as separate building blocks, with agents-flex-doc-extractor handling PDF, Office, HTML, email, archives, streams and URLs, and agents-flex-rerank providing a default implementation plus Gitee Rerank. There is no single RAG pipeline class advertised in the material, so wiring retrieval is your code, which is either the point or the problem depending on your team. Text2SQL is the more opinionated module. The README describes it as natural-language data analysis tools with progressive schema disclosure, read-only SQL checks and interceptor chains. The read-only check is a guardrail, not a sandbox: it constrains generated SQL, and the README does not claim it prevents every dangerous statement, so treat it as one layer and keep database credentials scoped. The same interceptor idea appears in the production-oriented list, alongside model routing, retry, load balancing, circuit breaking and OpenTelemetry observability. Those features are named in the README; the supplied material does not document their configuration keys, so plan to read the module source or the project site before relying on them.
How It Differs From Spring AI and LangChain4j
The README's own framing is that Agents-Flex is a counterpart to Spring AI, and the topics list includes both spring-ai and langchain4j, so comparison is invited. The difference in approach is scope and coupling. Spring AI is built around the Spring ecosystem: the starter gives you auto-configuration for common models and vector stores, and you get the framework's conventions along with it. Agents-Flex keeps the core compatible with Java 8+ and states it can run in plain Java, Spring Boot or other JVM stacks, with the Spring Boot starter as one option among several rather than the centre of gravity. LangChain4j is the closer structural match, since it also offers provider modules and abstractions in plain Java. The distinguishing items in the Agents-Flex material are the durable Agent runtime with snapshot recovery and Worker leases, the async-task modules for submit-and-poll provider jobs, and the file-system Skills modules with progressive disclosure. If you need chains and memory in a plain Java service, all three are plausible; the deciding factor is which one's module boundaries match the pieces you actually intend to deploy.
Licence and Upgrade Cost
The licence is Apache-2.0, which permits commercial use and modification and includes a patent grant, with the usual obligations around preserving notices and stating changes. That is a permissive baseline, and it is the same licence class many Java teams already accept. This is not legal advice; if you redistribute a modified version, have counsel review the notice requirements. Upgrade cost is driven by the version scheme. The README says the repository version comes from the revision property in the root pom.xml, currently 2.2.9, and the release list shows three releases in about a month. For a framework at that cadence, the realistic maintenance burden is reading release notes between minor bumps and re-running your own integration tests against each new 2.2.x, because the supplied material gives no compatibility policy for the module APIs. The BOM exists precisely to make version alignment easier, so using agents-flex-bom rather than individual version strings is the lower-friction path. Budget for the MCP module separately if you use it, since its JDK 17 floor can force a toolchain change independent of the library version.
Editorial conclusion
Agents-Flex fits Java teams that already run Spring Boot or plain JVM services and want to pull in only the pieces they need, for example agents-flex-chat-openai plus agents-flex-store-redis, without adopting a full application framework. It is a poor fit if you need a single stable orchestration API across a long-lived codebase, since the module list is still expanding and the MCP module alone requires JDK 17 while most others target JDK 8. Before committing, verify that the specific provider module you need (chat, embedding, store, audio) exists at version 2.2.9 and check the repository's demos directory for a runnable sample close to your use case.
Community notes