Agents-Flex

Agents-Flex is a lightweight AI application development framework for the Java ecosystem. It organizes LLM calls, Tool Calling, Agents, RAG, vector stores, Embedding, image generation, audio, MCP, Skills, Text2SQL, and related capabilities into clear modules, so developers can compose only what they need without being locked into a specific runtime or application framework.

It is suitable for building 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.

• Java native: Core modules are compatible with Java 8+ and can run in plain Java, Spring Boot, or other JVM stacks.
• Unified model abstractions: ChatModel, EmbeddingModel, ImageModel, RerankModel, and other interfaces wrap provider-specific capabilities.
• Consistent sync and streaming APIs: The same Prompt, Options, interceptor, and context mechanisms work for both normal chat and streaming output.
• Complete Tool Calling flow: Supports annotation-based scanning, programmatic tool building, tool execution, tool message feedback, and tool-level observability.
• Durable Agent runtime: Provides snapshot recovery, tool approval, Worker leases, middleware, event streams, task planning, and sub-agent scheduling.
• Full RAG building blocks: Includes document models, parsing, splitting, Embedding, vector stores, retrieval, and Rerank support.
• Production-oriented design: Includes model routing, retry, load balancing, circuit breaking, OpenTelemetry observability, and Text2SQL safety interceptors.

• Most modules: JDK 8+
• agents-flex-mcp: JDK 17+
• Build tool: Maven

The current repository version is defined by the revision property in the root pom.xml; it is currently 2.2.7.

For plain Java projects, you can use the aggregate dependency:

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

For Spring Boot projects, use the starter:

<dependency>
    <groupId>com.agentsflex</groupId>
    <artifactId>agents-flex-spring-boot-starter</artifactId>
    <version>2.2.7</version>
</dependency>

You can also depend on only the modules you need:

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

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

The following example uses an OpenAI-compatible API. Replace endpoint, model, and apiKey with your own model service configuration.

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);
    }
}

Streaming output:

import com.agentsflex.core.model.chat.StreamResponseListener;
import com.agentsflex.core.model.chat.response.AiMessageResponse;
import com.agentsflex.core.model.client.StreamContext;

chatModel.chatStream("Explain the Chain of Responsibility pattern in Java.", new StreamResponseListener() {
    @Override
    public void onMessage(StreamContext context, AiMessageResponse response) {
        System.out.print(response.getMessage().getContent());
    }
});

Business methods can be exposed as tools with annotations:

import com.agentsflex.core.model.chat.tool.annotation.ToolDef;
import com.agentsflex.core.model.chat.tool.annotation.ToolParam;

public class WeatherTools {
    @ToolDef(name = "get_weather", description = "Query the weather for a given city")
    public static String getWeather(
        @ToolParam(name = "city", description = "City name", required = true) String city
    ) {
        return city + ": sunny";
    }
}

After registering the tool on a Prompt, the model can call it when needed:

import com.agentsflex.core.model.chat.response.AiMessageResponse;
import com.agentsflex.core.prompt.SimplePrompt;

SimplePrompt prompt = new SimplePrompt("What is the weather in Beijing today?");
prompt.addToolsFromClass(WeatherTools.class);

AiMessageResponse response = chatModel.chat(prompt);
if (response.hasToolCalls()) {
    prompt.setToolMessages(response.executeToolCallsAndGetToolMessages());
    System.out.println(chatModel.chat(prompt).getMessage().getContent());
}

If tools come from runtime configuration, a plugin system, or workflow nodes, you can also build them dynamically with Tool.builder().

For larger tool sets, use ToolGroup to attach tools and system instructions only when the latest user prompt matches. Unmatched groups are omitted from the request body:

ToolGroup weatherGroup = ToolGroup.builder("weather")
    .addTools(ToolScanner.scan(WeatherTools.class))
    .systemPrompt("Always use a weather tool for live weather questions.")
    .matcher(ToolGroupMatchers.promptContains("weather", "temperature", "rain"))
    .build();

MemoryPrompt prompt = new MemoryPrompt();
prompt.addToolGroup(weatherGroup);
prompt.addUserMessage("Will it rain in Beijing today?");
chatModel.chat(prompt);

A Prompt can contain multiple groups. Every request is matched again against the latest user message, so tools selected for one turn do not leak into later unrelated turns. In addition to promptContains and promptMatches, matcher(context -> ...) supports application-specific strategies.

The request body is built only after all interceptors reach the end of the chain. Prompt and ChatOptions changes made before chain.proceed() therefore affect the final request:

ChatInterceptor interceptor = new ChatInterceptor() {
    @Override
    public AiMessageResponse intercept(BaseChatModel<?> model, ChatContext context, SyncChain chain) {
        context.getOptions().setTemperature(0.2f);
        context.setPrompt(new SimplePrompt("rewritten prompt"));
        context.getRequestSpec().addHeader("X-Tenant", "tenant-1");
        return chain.proceed(model, context);
    }
};

ChatRequestSpec contains only the URL, headers, and retry configuration; it no longer exposes the body. Interceptors influence request content through structured Prompt and ChatOptions changes instead of rewriting raw body JSON.

Interceptors can also be activated conditionally for each request. The matcher runs when the registration reaches its position in the chain, so it sees changes made by earlier interceptors:

chatModel.addInterceptorRegistration(
    ChatInterceptorRegistration.builder("premium-audit", new AuditChatInterceptor())
        .matcher(context -> "premium".equals(context.getAttribute("plan")))
        .order(ChatInterceptorOrders.DEFAULT)
        .build()
);

Use GlobalChatInterceptors.addRegistration(...) for a conditional interceptor shared by subsequently created chat models. Existing addInterceptor(...) APIs remain available and register an interceptor that always matches.

Registrations are stably sorted by ascending order for each request. Framework defaults place observability at -1000, ordinary interceptors at 0, and request preparation such as Tool Group resolution at 1000. These are recommendations rather than boundaries: applications may use any integer to run before observability or after Tool Group resolution. Registrations with the same order retain their original registration order.

Agents-Flex includes several mechanisms for complex tasks:

• ReActAgent: Executes multi-step tasks with Thought / Action / Observation.
• RoutingAgent: Routes requests to a more suitable Agent.
• SubagentTools: Lets a parent Agent create subtasks with synchronous or background execution.
• SkillsTool: Reads local Skills directories and loads specialized capability instructions and resources on demand.
• McpClientManager: Connects to MCP Servers and wraps remote tools as Tool instances.

These capabilities are built on the same Tool, Prompt, and ChatModel abstractions, making them easy to combine and replace.

RAG-related capabilities are distributed across multiple modules:

• Document models: Document, VectorData, Metadata
• Text processing: Loader, Parser, Splitter, Doc Extractor
• Vectorization: OpenAI, Ollama, and Qwen Embedding
• Vector stores: Redis, Qdrant, Chroma, Pgvector, MariaDB, Milvus, OpenSearch, Elasticsearch, and more
• Retrieval: SearchWrapper, DocumentStore, VectorStore
• Relevance optimization: Rerank models

A typical flow is: load documents, split text, generate Embeddings, write them to a vector store, retrieve relevant passages for a user question, and then let a ChatModel generate the final answer.

LLM Wiki can be understood as a hierarchical knowledge base designed for Agents. Instead of slicing knowledge only into flat chunks, it organizes content as a Wiki tree with paths, titles, summaries, page bodies, and child pages. An Agent first sees summaries of available pages, then calls tools to read more specific child pages only when needed, enabling step-by-step navigation with less context.

agents-flex-wiki provides the basic abstractions for this pattern: Wiki, WikiProvider, and WikiTool. WikiTool exposes the available child Wikis of the root or current node to the model, and reads content by path through get_wiki_content(path). It is useful for documentation systems with clear chapter structures, where you want an Agent to browse knowledge like a table of contents. It can also be combined with traditional RAG, WebSearch, and Skills.

agents-flex-mcp supports stdio, http-sse, and http-stream transports. It can load MCP services from mcp-servers.json and convert MCP tools into Agents-Flex tools.

agents-flex-skills supports file-system-based Skills, which are useful for packaging repeatable professional tasks such as code review, document generation, file processing, and local knowledge retrieval.

agents-flex-text2sql targets natural-language data analysis. It provides tools for listing data sources, inspecting table schemas, and executing SQL, with built-in read-only SQL checks, parameterized-query constraints, LIMIT control, tenant isolation, and audit extension points.

The framework includes model routing, allowing multiple model instances to be combined into one RoutedChatModel or RoutedEmbeddingModel. It supports:

• Least-active load balancing
• Weighted random load balancing
• Tag-based routing
• Automatic retry
• Circuit breaking and half-open recovery
• Runtime metrics

Observability is based on OpenTelemetry and supports tracing and metrics collection. You can switch between Logging, OTLP, or custom exporters with system properties:

-Dagentsflex.otel.enabled=true
-Dagentsflex.otel.exporter.type=otlp
-Dagentsflex.otel.metric.export.interval=30

agents-flex-spring-boot-starter provides auto-configuration for:

• Chat: OpenAI, Qwen, Ollama, DeepSeek
• Store: Alibaba Cloud, Chroma, Elasticsearch, OpenSearch, Tencent Cloud

It is designed for quickly integrating models and vector stores into existing Spring Boot services.

agents-flex-core/                 Core APIs and base implementations
agents-flex-doc-extractor/        Document content extraction
agents-flex-agent/                Durable Agent runtime and extension contracts
agents-flex-agent-store/          JDBC and Redis Agent runtime persistence
agents-flex-observability/        OpenTelemetry persistence exporters
agents-flex-chat/                 Chat model integrations
agents-flex-embedding/            Embedding model integrations
agents-flex-image/                Image model integrations
agents-flex-video/                Video model integrations
agents-flex-audio/                Audio model integrations
agents-flex-store/                Vector store integrations
agents-flex-search-engine/        Search engine integrations
agents-flex-tool/                 Common tools
agents-flex-mcp/                  MCP client
agents-flex-skills/               Skills capability system
agents-flex-skills-sandbox/       Sandbox runtimes for Skills
├── agents-flex-skills-open-sandbox/
└── agents-flex-skills-aio-sandbox/
agents-flex-subagent/             Subagents and background tasks
agents-flex-text2sql/             Natural-language data analysis
agents-flex-websearch/            Web search
agents-flex-spring-boot-starter/  Spring Boot auto-configuration
demos/                            Example projects
docs/                             Chinese and English documentation

mvn clean install

To build or test a single module with its dependencies:

mvn -pl agents-flex-chat/agents-flex-chat-openai -am test

• Chinese documentation home: docs/zh/index.md
• English documentation home: docs/en/index.md
• Quick start: docs/zh/chat/getting-started.md
• Maven dependencies: docs/zh/intro/maven.md
• MCP: docs/zh/chat/mcp.md
• Skills: docs/zh/chat/skills.md
• Subagent: docs/zh/chat/subagent.md
• Text2SQL: docs/zh/chat/text2sql.md
• WebSearch: docs/zh/chat/websearch.md

Agents-Flex is open source under the Apache License 2.0. See LICENSE for details.