agents-flex/agents-flex

What is Agents‑Flex?

Agents‑Flex is a Java‑first framework for building applications that talk to large language models (LLMs) and other AI services. It bundles the usual pieces of an LLM‑powered system—chat, embeddings, image/audio generation, tool calling, Retrieval‑Augmented Generation (RAG), vector stores, observability, etc.—into a set of modular Maven artifacts that can be mixed‑and‑matched. The goal is to let Java developers compose only the parts they need without being forced into a particular runtime (plain Java, Spring Boot, other JVM stacks).

---

Core ideas & architecture

Idea	How it shows up in the code
Unified model abstractions	Interfaces such as ChatModel, EmbeddingModel, ImageModel, RerankModel hide provider‑specific APIs (OpenAI, Qwen, Ollama, etc.).
Sync & streaming API	Same Prompt, ChatOptions, and interceptor chain work for normal chat() calls and chatStream() callbacks.
Tool calling	Annotated Java methods (@ToolDef, @ToolParam) are scanned into Tool objects; the framework builds the request, executes the tool, and feeds the result back to the model.
Durable Agent runtime	agents-flex-agent provides a state machine that can pause, resume, snapshot, and persist runs (JDBC/Redis stores).
RAG building blocks	Document loaders, parsers, splitters, embedding generators, vector‑store adapters, and rerankers are separate modules that can be wired together.
Production‑ready concerns	Model routing, load‑balancing, retries, circuit‑breakers, and OpenTelemetry exporters are built‑in.
Plug‑in style extensibility	New tools, vector stores, or model providers are added by implementing the corresponding interface and adding the module as a Maven dependency.

---

Main modules (high‑level view)

• agents-flex-core – basic types (Prompt, Message, Tool, Memory, Document).
• agents-flex-chat, ‑embedding, ‑image, ‑audio, ‑ocr, ‑video – concrete model adapters for many providers.
• agents-flex-store – adapters for Redis, Qdrant, Chroma, Milvus, Elasticsearch, etc.
• agents-flex-agent & ‑agent‑store – runtime that orchestrates a turn, handles tool calls, persists state.
• agents-flex-tool & ‑toolsearch – ready‑made utilities (shell, file, web fetch) and a searchable registry.
• agents-flex-mcp – client that turns external MCP services into Tool objects.
• agents-flex-skills family – file‑system‑based “skill packages” that can be sandboxed.
• agents-flex-text2sql – safe, read‑only natural‑language‑to‑SQL conversion with schema discovery.
• agents-flex-wiki – hierarchical knowledge base that agents can browse page‑by‑page.
• agents-flex-spring-boot-starter – auto‑configuration for the most common models and stores.
• demos – runnable examples that show chat, tool calling, RAG, and agent workflows.

---

Typical usage flow (example)

1. Add Maven dependencies – either the BOM (agents-flex-bom) or the specific modules you need (e.g., agents-flex-chat-openai + agents-flex-store-redis).
2. Configure a model – create a ChatModel via a provider‑specific config builder (see Quick‑Start). The same model can be used for normal or streaming calls.
3. Define tools – annotate Java methods with @ToolDef/@ToolParam or build them programmatically. Register the tools on a Prompt or a ToolGroup.
4. Build a Prompt – combine user text, system instructions, and the selected tool group(s).
5. Call the model – chat() returns an AiMessageResponse. If hasToolCalls() is true, execute the tools (executeToolCallsAndGetToolMessages()) and send the updated prompt back.
6. (Optional) Run an Agent – wrap the above in AgentRunner to get automatic snapshotting, approval hooks, and persistence.
7. (Optional) Add RAG – load documents, split, embed, store in a vector store, retrieve passages, optionally rerank, then feed the retrieved text into the prompt.
8. Observe – OpenTelemetry exporters emit spans/metrics; you can enable them via -Dagentsflex.otel.enabled=true.

---

Who should use it?

• Java back‑end teams that need to add LLM‑driven features (chatbots, code assistants, data‑analysis agents) without switching to Python.
• Enterprises that require durability, auditability, and integration with existing JVM infrastructure (Spring Boot, JDBC, Redis, etc.).
• Developers building multi‑model services – the routing and load‑balancing features let you blend OpenAI, Qwen, Ollama, etc., in a single endpoint.
• Teams that want a plug‑in tool ecosystem – the annotation‑based tool scanner and MCP client make it easy to expose internal services as LLM‑callable tools.

---

Strengths & limitations

Strengths	Limitations
Java‑native – no need for JNI or external Python runtimes.	Ecosystem size – fewer community‑contributed modules than Python‑centric libraries.
Modular Maven artifacts – you can ship only what you use, keeping the final JAR small.	Learning curve – the interceptor chain and tool‑group matching add conceptual overhead.
Built‑in production features (routing, circuit‑breakers, OpenTelemetry).	Documentation – primarily in Chinese/English markdown; examples are limited to the demos folder.
Rich tool‑calling support (annotations, dynamic groups, MCP).	Runtime flexibility – still tied to the JVM; not a good fit for edge devices or non‑Java stacks.

---

Getting started quickly

<dependency>
  <groupId>com.agentsflex</groupId>
  <artifactId>agents-flex-bom</artifactId>
  <version>2.3.0</version>
  <type>pom</type>
  <scope>import</scope>
</dependency>

ChatModel model = OpenAIChatConfig.builder()
    .endpoint("https://api.openai.com/v1")
    .model("gpt-4o")
    .apiKey(System.getenv("OPENAI_KEY"))
    .buildModel();

SimplePrompt p = new SimplePrompt("Summarize the latest Java 21 features.");
System.out.println(model.chat(p).getMessage().getContent());

Run the demos/chat-demo module for a more complete example that includes tool calling and streaming.

---

License & community

Agents‑Flex is Apache 2.0 licensed, making it free for commercial use. The repository shows a contributor badge generated by contrib.rocks, indicating an open‑source community, though the README does not list individual contributors.

---

In short: Agents‑Flex gives Java developers a production‑grade toolbox for LLM chat, tool orchestration, RAG, and related AI capabilities, all packaged as interchangeable Maven modules that can be dropped into any JVM application.