Agents-Flex: a Java AI agent framework that stays out of your runtime

What Agents-Flex is for, and who it is not for

Agents-Flex is a Java framework that organizes LLM calls, tool calling, agents, RAG, vector stores, embedding, image generation, audio, MCP, Skills and Text2SQL into separate modules. The README lists the intended uses: intelligent customer service, enterprise knowledge bases, natural-language data analysis, agent workflows, model gateways, AI-assisted office tools, plugin-based tool systems, and Java services that need to connect to multiple model providers at the same time. That last one is the clearest signal about the audience. If your application talks to one provider and always will, the module split buys you little.

The framework is positioned as a counterpart to Spring AI, and the README repeats that it is not tied to a specific runtime or application framework. Core modules are compatible with Java 8+ and are described as runnable in plain Java, Spring Boot, or other JVM stacks. The repository is not archived, and the last push was on 2026-09-10, with v2.2.9 released on 2026-09-03. The root pom.xml defines the current version through a revision property, currently 2.2.9.

The people who benefit most are Java teams that already have a service layer, a build, and an opinion about which stack they run on. Teams looking for a hosted agent product, or for a Python-first ecosystem, are outside the target.

How the module layout maps to a request

The core abstraction set is small. agents-flex-core holds Chat, Prompt, Message, Tool, Memory, Document, Store and observability. Provider modules implement interfaces such as ChatModel, EmbeddingModel, ImageModel and RerankModel, so swapping an OpenAI-compatible endpoint for Ollama or Qwen is a configuration change rather than a rewrite. The README states that the same Prompt, Options, interceptor and context mechanisms apply to both normal chat and streaming output, which is the part that usually diverges in hand-rolled integrations: a streaming path that ignores interceptors and retries.

Around that core sit the pieces that make an application rather than a call. agents-flex-tool provides file system, Shell, Grep, Glob, WebFetch, Python and JavaScript tools. agents-flex-mcp is an MCP client that converts external MCP tools into Agents-Flex Tool instances. agents-flex-store covers Redis, Qdrant, Chroma, Pgvector, MariaDB, Milvus, OpenSearch, Elasticsearch, Alibaba Cloud and Tencent Cloud vector stores. For durable work, agents-flex-agent handles Run state, snapshot recovery, Worker leases, approval, middleware and events, while agents-flex-agent-store persists runs, commands, events and artifacts to JDBC or Redis. The async-task pair does the same job for provider jobs that use submit-and-poll workflows.

The design choice worth noting is that durability is a separate dependency, not a default. A single-process demo needs neither agent-store nor async-task-store. A production deployment that wants snapshot recovery needs both the module and a database behind it.

Installing Agents-Flex and making a first call

Installation is Maven coordinates. For plain Java projects the README gives an aggregate dependency on agents-flex-bom at version 2.2.9; for Spring Boot there is agents-flex-spring-boot-starter at the same version. The BOM is the safer starting point because provider and store modules then inherit the version.

<dependency>
    <groupId>com.agentsflex</groupId>
    <artifactId>agents-flex-bom</artifactId>
    <version>2.2.9</version>
</dependency>

If you prefer to pull only what you use, the README shows individual artifacts such as agents-flex-chat-openai and agents-flex-store-redis, each pinned to 2.2.9.

<dependency>
    <groupId>com.agentsflex</groupId>
    <artifactId>agents-flex-chat-openai</artifactId>
    <version>2.2.9</version>
</dependency>

<dependency>
    <groupId>com.agentsflex</groupId>
    <artifactId>agents-flex-store-redis</artifactId>
    <version>2.2.9</version>
</dependency>

The quick start builds a ChatModel from OpenAIChatConfig and calls chat with a plain string. The README's example points at https://ai.gitee.com with provider GiteeAI and model Qwen3-32B, reading the key from the GITEE_API_KEY environment variable. Replace endpoint, model and apiKey with your own service.

import com.agentsflex.core.model.chat.ChatModel;
import com.agentsflex.model.chat.openai.OpenAIChatConfig;

public class ChatDemo {
    public static void main(String[] args) {
        ChatModel chatModel = OpenAIChatConfig.builder()
            .endpoint("https://ai.gitee.com")
            .provider("GiteeAI")
            .model("Qwen3-32B")
            .apiKey(System.getenv("GITEE_API_KEY"))
            .buildModel();

        String reply = chatModel.chat("Introduce Agents-Flex in one sentence.");
        System.out.println(reply);
    }
}

Run it and you should see one line of model output on stdout. The README also shows a streaming variant built on StreamResponseListener; the class name is truncated in the published README, so check the source for the exact import before you copy it. Build tool is Maven, and most modules need JDK 8+.

Where the framework pushes work back onto you

The module split is the main cost. Spring AI and LangChain4j both ship a broader set of ready-made integrations and, in Spring AI's case, a starter that assumes Spring. Agents-Flex gives you the same kind of abstractions but expects you to choose and wire the storage, the observability exporter and the agent store. agents-flex-observability provides OpenTelemetry span and metric exporters with JDBC persistence, but nothing in the README suggests it is on by default.

The JDK requirement is uneven in a way that matters for legacy services. Most modules run on JDK 8+, but agents-flex-mcp requires JDK 17+. A team on Java 8 that wants MCP tooling has to either run that piece separately or upgrade. The README does not describe a bridge for that case.

Durability has a hard dependency. Snapshot recovery for agent runs is only meaningful with agents-flex-agent-store configured against JDBC or Redis. If you run agents-flex-agent without a store, you get the runtime in memory and lose the recovery property that makes the module worth adding. There is also little guidance in the README on failure modes: what happens when a Worker lease expires, or how a partially executed tool call is reconciled after a restart, is not documented there. Those answers live in the agent and agent-store sources.

Text2SQL deserves its own caution. The README describes read-only SQL checks and interceptor chains, which is a reasonable safety posture, but the framework cannot know whether your schema or your prompt is the weak point. Treat the interceptor as a guard rail, not as a reason to point the tool at a production database.

Agents-Flex compared with LangChain4j and Spring AI

LangChain4j is the closest comparison in language and ambition. It also provides chat models, embedding models, vector stores and an agent layer for Java, and the search data around this project shows people comparing the two directly. The difference in approach is packaging philosophy. LangChain4j has grown a large integration surface and an AI Services layer that generates implementations from interfaces; Agents-Flex keeps a smaller core and splits capabilities into named modules, with agents-flex-toolsearch for progressive tool discovery and agents-flex-wiki for hierarchical knowledge trees as separate artifacts. If you want a broad catalogue of prebuilt integrations, LangChain4j is further along. If you want to add one capability at a time and keep the dependency graph small, Agents-Flex's layout is easier to reason about.

Spring AI is the other reference point, and the README positions Agents-Flex as a counterpart to it. The practical difference is runtime coupling. Spring AI assumes Spring; Agents-Flex states that core modules run in plain Java or Spring Boot, with agents-flex-spring-boot-starter available if you do want auto-configuration for common models and vector stores. For a non-Spring service, or one that mixes frameworks, that decoupling is the reason to pick it.

MyBatis-Flex appears in the same search results, which is a naming coincidence rather than a technical overlap. MyBatis-Flex is a persistence framework; Agents-Flex is not.

Maintenance, licensing and the upgrade surface

The repository is not archived, and the last push was on 2026-09-10. Releases have been frequent: v2.2.9 on 2026-09-03, v2.2.8 on 2026-08-17, v2.2.7 on 2026-08-10. That cadence is consistent with a project that is still moving, but it also means minor versions arrive often enough that pinning matters. The version is centralized in the revision property in the root pom.xml, so a single edit moves the whole build if you inherit from the BOM. Do that deliberately rather than tracking latest.

The licence is Apache-2.0. That is a permissive licence with an explicit patent grant and no copyleft obligation on your own code, which is usually what enterprise Java teams want. It is not legal advice, and if you redistribute the framework or modify it, read the LICENSE file in the repository root rather than this paragraph.

Upgrade cost depends on how much of the module list you use. A project on agents-flex-chat and agents-flex-store is cheap to move. A project on agents-flex-agent plus agents-flex-agent-store is not, because persistence schemas for runs, commands, events and artifacts are part of the upgrade. Check changes.md before bumping those two together.

Editorial conclusion

Adopt Agents-Flex if you are building Java services that must talk to several model providers at once, or if you want RAG, tool calling and agent runs as separate Maven artifacts rather than one bundled runtime. Do not adopt it if you need an agent runtime that survives process restarts but will not run a JDBC or Redis store, or if you cannot move to JDK 17 and MCP is part of your plan. Before committing, verify that the provider modules you need actually exist for your model service, and read the agents-flex-agent and agents-flex-agent-store sources to see what snapshot recovery and Worker leases really persist.

Frequently asked questions

Official sources

1. agents-flex/agents-flex on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases