agents-flex

Home > Frameworks > agents-flex

Agents-flex is A Lightweight Java AI Application Development Framework.

agent ai chatbot chatgpt gpt java langchain4j llama3 llm

Why this rank:Strong adoptionRecent releaseHealthy release cadence

Description

Agents-flex is A Lightweight Java AI Application Development Framework.

README

An Elegant Java Framework for LLM Application Development | Truly Open Source · Easy Integration · Production Ready

🚀 Core Features

Agents-Flex is designed for Java engineers and architects, delivering a lightweight, modular, and extensible AI agent development experience to help enterprises rapidly build production-grade LLM applications.

✨ New Core Capabilities (v2.0+)

Feature	Description	Use Cases
MCP Support	Native integration with Model Context Protocol for standardized connection to external data sources and tools	Cross-system context sharing, tool orchestration
AI Skills	Encapsulate business capabilities into reusable, composable Skill units	Rapid domain Agent construction, skill marketplace
Text2SQL / Smart Data Query	Built-in Text2SQL and natural language data analysis capabilities	Zero-code querying for business users, data insights

🔧 Core Capabilities Matrix

🧠 Model Integration    🔌 Tool Invocation        📚 Knowledge Enhancement
├─ Mainstream LLMs      ├─ Function Calling        ├─ Multi-format Document Loading
├─ Ollama Local Deploy  ├─ MCP Tool Protocol       ├─ Intelligent Text Splitting
├─ HTTP/SSE/WS Protocols├─ Local Method Reflection ├─ Vector Store Integration
├─ Multi-Provider Mgmt  ├─ Execution Interceptors  ├─ Custom Embedding Support

⚙️ Engineering Support  🔍 Observability          🛡️ Enterprise-Grade Assurance
├─ Prompt Template Engine├─ OpenTelemetry Integration├─ Sensitive Data Masking
├─ Multi-turn Memory    ├─ Distributed Tracing    ├─ Safe Resource Shutdown
├─ Async/Streaming Resp ├─ Structured Logging     ├─ Apache 2.0 License

💡 Design Principles: Zero-Intrusion Integration · Interface-Driven Extension · Configuration Over Code · Production-Friendly

⚡ Quick Start

1️⃣ Add Dependencies (Maven)

<dependency>
    <groupId>com.agentsflex</groupId>
    <artifactId>agents-flex-core</artifactId>
    <version>2.0.8</version>
</dependency>
<!-- Optional: Add extension modules as needed -->
<dependency>
    <groupId>com.agentsflex</groupId>
    <artifactId>agents-flex-mcp</artifactId>
    <version>2.0.8</version>
</dependency>

2️⃣ Hello World

public class QuickStart {
    public static void main(String[] args) {
        // 1. Configure the model (supports GiteeAI / OpenAI / Ollama, etc.)
        OpenAIChatModel chatModel = OpenAIChatConfig.builder()
            .provider("GiteeAI")
            .endpoint("https://ai.gitee.com")
            .requestPath("/v1/chat/completions")
            .apiKey(System.getenv("GITEE_AI_KEY")) // ✅ Recommended: load from environment variable
            .model("Qwen3-32B")
            .buildModel();

        // 2. Start a conversation (sync/streaming/async all supported)
        String response = chatModel.chat("Explain what humor is in a way that Java developers can understand?");

        // 3. Output the result
        System.out.println("🤖 Agents-Flex: " + response);
    }
}

Console Output Example:

[Agents-Flex] >>> [GiteeAI/Qwen3-32B] Request: {"model":"Qwen3-32B","messages":[...]}
[Agents-Flex] <<< [GiteeAI/Qwen3-32B] Response: 200 OK (1.2s)
🤖 Agents-Flex: Humor is like elegant exception handling in code—seemingly unexpected, yet meticulously designed...

📝 The [Agents-Flex] log prefix can be customized or disabled via application.properties. For production environments, SLF4J integration is recommended.

📦 Module Overview

agents-flex/
├── agents-flex-bom                    # 📦 BOM dependency management for unified versioning
├── agents-flex-core                   # 🧱 Core abstractions: Model/Prompt/Memory/Tool SPI
├── agents-flex-chat                   # 💬 Chat engine: sync/streaming/async invocation
├── agents-flex-tool                   # 🔧 Function Calling engine: method definition/parsing/execution
├── agents-flex-mcp                    # 🔗 MCP protocol support: standardized context & tool connection (New)
├── agents-flex-skills                 # 🎯 AI Skills: capability encapsulation & dynamic loading (New)
├── agents-flex-text2sql                   # 📊 Text2SQL & natural language data analysis (New)
├── agents-flex-embedding              # 🔢 Embedding service: model integration & vector generation
├── agents-flex-store                  # 🗄️ Storage extensions: VectorStore/Memory persistence implementations
├── agents-flex-search-engine          # 🔍 Search engine integration: ES/DB/custom retrieval sources
├── agents-flex-rerank                 # 📈 Re-ranking service: improve RAG retrieval relevance
├── agents-flex-image                  # 🖼️ Image capabilities: text-to-image / image-to-text model integration
├── agents-flex-spring-boot-starter   # ⚙️ Spring Boot auto-configuration (Production Recommended)
├── demos/                             # 🧪 Sample projects: MCP / Skills / Text2SQL demos
├── docs/                              # 📚 Documentation source (VitePress)
└── testresource/                      # 🧪 Test resource files

✅ Production-Ready Recommendations:

Use agents-flex-spring-boot-starter with a configuration center for API key management in production
Inject sensitive information (API Keys / DB passwords) via @Value("${xxx}") + encrypted configuration
Enable management.endpoints.web.exposure.include=metrics,trace for monitoring integration
For RAG scenarios, combine: data + embedding + store + rerank modules

📚 Documentation & Resources

Type	Link	Description
📘 Chinese Docs	https://agentsflex.com	Complete API guide + best practices
🧪 Sample Projects	/demos	MCP integration / Skills orchestration / Text2SQL demos
📋 Changelog	/changes.md	Version history and migration guide
🐛 Issue Tracker	GitHub Issues	Bug reports / feature requests
💬 Community	Join Discussion	Q&A, ideas, and community support

🤝 Contributing

We follow the Apache Way and Contributor Covenant guidelines:

Fork the repo → Create a feature branch (feature/xxx)
Code style: Run mvn spotless:apply for auto-formatting (Google Java Style)
Add unit tests: Aim for ≥ 80% coverage on core modules
Submit a PR linked to an issue, describing the motivation and impact of changes

🌟 Especially welcome: Java 8/11/17 compatibility tests, enterprise use cases, and documentation translations

📜 License

Agents-Flex is released under the Apache License 2.0. You are free to:

✅ Use commercially in your projects
✅ Modify and deploy privately
✅ Contribute code to grow the ecosystem

Please retain the original copyright notice and indicate modifications when distributing. See LICENSE for details.

Release History

Version	Changes	Urgency	Date
v2.2.9	- fix(agent): propagate chat context into timed tool execution - feat(agent): enhance tool execution with chat context propagation - docs(agent): add demo documentation for agent showcase - refactor(agent): migrate suspension protocol fields to typed properties - feat(tool): add retry information to agent tool context - feat(compression): add compression start callback and refine event system - refactor(compression): replace compression condition with decider interface - refactor(agent):	High	9/3/2026
v2.2.8	- refactor(doc-extractor): replace deprecated ImageUtils with ImageUtil - refactor(documents): replace ExtractedImageHandler with DocumentImagePublisher - style(javadoc): standardize javadoc comment formatting across all classes - docs(util): add documentation for AgentsFlexHttpClient and JsonSanitizer - feat(http): add gzip response decoding support to http client - feat(document): add HTML img tag support to image describer - test(ocr): update integration tests with extended timeout and	High	8/17/2026
v2.2.7	- docs(website): add document extractors documentation and enable MPA mode - docs: remove en documentation files and samples - docs(community): update communication and contribution guidelines - style(docs): refine homepage layout and content structure - refactor(docs): update theme layout and styling for enhanced accessibility - docs(menu): rename Tool to Function Call in navigation and links - docs(sidebar): refactor documentation structure and remove cursor enhancement - refactor(doc-e	High	8/10/2026
v2.2.6	- chore(deps): update fastjson2 dependency to version 2.0.63 - feat(message): enhance JSON sanitization for unquoted string values in tool calls - feat(video): enhance video configuration with generation mode support and validation - feat(image): add model-specific capability validation framework - feat(image): add OpenAI and Gemini image model adapters - refactor(image): enhance image configuration with additional properties and validation - refactor(image): standardize JavaDoc comments a	Medium	7/31/2026
v2.2.4	- docs(sidebar): add sandbox conversation isolation lab to documentation - test(sandbox): add integration tests for AIO and Open Sandbox skill runtimes - test(openai): add DeepSeek API integration test - docs(skills): update documentation and tool names - refactor(runtime): move conversation store implementations to dedicated package - feat(runtime): add conversation workspace isolation for skill runtimes - docs(chat): add comprehensive GlobalChatInterceptors documentation - feat(tool): a	High	7/25/2026
v2.2.0	- refactor(config): handle url-based transport type fallback in McpConfig - refactor(mcp): update schema parsing to use Map instead of JsonSchema object - refactor(client): update HTTP transport customization and schema handling - chore(build): update mcp version from 1.1.3 to 2.0.0 - feat(toolcall): enhance JSON parsing with JavaScript expression support - docs(getting-started): update agents-flex-bom version to 2.1.9 - fix(core): prevent BigInteger overflow when converting BigDecima - f	High	7/13/2026
v2.1.9	- docs(audio): add documentation for audio streaming and recording features - test(openai): update OpenAI chat model test with context attributes and debug logging - fix(chat): resolve chat context management in streaming operations - docs(menu): add audio module section with tts/stt documentation - feat(bom): add audio model dependencies to flex bom - chore(license): add copyright headers to audio module files - fix(audio): ensure client cleanup in Volc streaming TTS model - test(volc):	High	6/25/2026
v2.1.8	- docs(chat): add WebFetch tool documentation and navigation entry - chore: Optimize AI recognition to call intelligent agent name logic - docs(subagent): update agent selection instructions and error messaging - chore(deps): update dependency versions in pom files - feat(chat): add toString methods to chat configuration classes - feat(tools): add toString implementations for tool classes - refactor(demos): rename Main class to SubagentDemo - fix(subagent): correct XML formatting and impr	High	6/12/2026
v2.1.7	## v2.1.7 20260608 - docs(wiki): expand documentation with tree structure support - feat(wiki): add hierarchical structure support for wiki content - refactor(search): replace empty list returns with proper exception handling - docs(websearch): enhance documentation with detailed architecture and examples - test(websearch): switch from Bocha to Baidu Qianfan search provider - refactor(websearch): simplify search result processing in WebSearchTool - feat(baidu): add Baidu Qianfan Search Pr	High	6/9/2026
v2.1.3	- feat(test): add Bailian search integration and provider tool enhancements - feat(chat): add provider tool support and enhance tool serialization - refactor(tool): update MethodTool parameter resolution and add override annotation - refactor(docs): update document module documentation structure - refactor(OpenAIChatRequestSpecBuilder): update tool choice condition logic - fix(chat): handle null responses and improve content extraction logic	High	5/26/2026
v2.1.2	- fix(prompt): correct failOnMissingVariable logic in template processing - feat(prompt): add keep expression on missing variable option - feat(prompt): add failOnMissingVariable option to PromptTemplate - docs(homepage): update homepage features and navigation links - docs(nav): add model router and LLM wiki documentation - feat(router): add model routing infrastructure with load balancing and circuit breaking - feat(embedding): add EmbeddingOptions class for embedding model configuration	High	5/15/2026
v2.1.0	- refactor(chat): rename needReasoningContentForToolMessage to preserveThinkingEnable - feat(wiki): add method to build XML representation of wikis - feat(wiki): add wiki module with Wiki entity and tool integration - refactor(skills): simplify stream mapping in SkillsTool	High	4/22/2026
v2.0.9	- feat(chat): add weather tool integration with location parameter enhancement - refactor(tool): refactor method tool parameter handling with improved array and object type support - feat(milvus): add configurable primary key type support - refactor(store): change document store methods visibility to protected - fix(milvus): correct primary key type handling in vector store	High	4/17/2026
v2.0.8	- test(file2text): add file to text utility test cases - feat(image): add MIME type detection from file extension - refactor(extractor): remove duplicate file extension extraction method - feat(extractor): enhance DOC and DOCX extractors with image support - feat(image): add Bailian image model support and enhance size handling - fix(image): correct image data URI format - refactor(config): update package structure for chat model auto configurations - fix: support num/uuid point id parsin	High	4/17/2026
v2.0.7	- feat(milvus): add support for custom extension fields in vector store - refactor(milvus): rename dimension field to defaultDimension for clarity - feat(milvus): add expression adaptor support for vector store filtering - refactor(milvus): improve search request building and add comprehensive tests - fix(milvus): correct partition names condition check in search builder - chore(deps): update milvus-sdk-java dependency version - refactor(milvus): rename collectionName to defaultCollectionN	Medium	3/30/2026
v2.0.6	- fix(chat): handle null metadata in ChatOptions builder - refactor(core): replace addMetadata with putMetadata in document operations - feat(chat): add metadata support to ChatOptions - refactor(config): update package structure and configuration imports - refactor(model): move chat model classes from llm package to model.chat package - refactor(chat): extend ChatOptions from Metadata class	Medium	3/25/2026
v2.0.5	- test(milvus): update test collection name and add document metadata - test(file2text): add test case for http xlsx to text conversion - feat(extractor): add Excel file extraction support - refactor(core): change vector data type from double to float and update setVector method - refactor(store): change score type from Double to Float across vector stores - refactor(store): optimize Milvus vector store connection management - feat(demo): enhance skills demo with logging and output improve	Low	3/18/2026
v2.0.4	- feat(text2sql): optimize table building logic for JDBC data sources - refactor(core): optimize OpenAI chat message serializer parameter handling - feat(openai): add location-based weather tool functionality - feat(tools): enhance method tool parameter handling with JSON Schema mapping - feat(tool): enhance MethodTool with proper JSON Schema type mapping - feat: Search engines support element data filtering - feat(parser): Support latest vllm output format with multiple possible reasoning	Low	3/12/2026
v2.0.2	- feat(file2text): add encoding detection utility for file extraction - fix(template): update ChartConfigTool markdown template format - feat(text2sql): add chart configuration tool for data visualization - refactor(text2sql): enhance tool descriptions and parameter validation for SQL query tools - refactor(core): simplify tool calls check in AiMessageResponse	Low	3/6/2026
v2.0.1	- docs(nav): update Text2SQL menu item text in Chinese documentation - refactor(text2sql-demo): remove unused table name configuration - docs(chat): update text2sql development documentation - feat(text2sql): enhance SQL validation with structured results - chore(build): update maven configuration and exclude demo modules from publish - refactor(text2sql): replace filter functions with collection-based table and column filtering - docs(chat): update text2sql documentation references - fea	Low	3/2/2026
v2.0.0	# 🚀 v2.0.0 Official Release 📅 Release Date: 2026-03-01 > v2.0 is a major architectural upgrade. > This release transforms the framework into a full-fledged Agent development framework, introducing the Skills system, a complete MCP client architecture, a new data module, enhanced streaming capabilities, and a unified core API. --- # ✨ Core Architecture Upgrade ## 🔁 Architecture Refactoring & Module Changes * Removed `Chain` module (merged into Tinyflow) * Remove	Low	3/1/2026
v1.4.2	- 新增：新增本地 Token 计算的相关内容，方便在某些情况下无法获取外部 token 时使用 - 新增: 新增 file2text 模块 - 新增: Chain 支持主动去暂停执行或恢复执行 - 新增：feat: 新增可观测的相关能力 - 新增：prompt 格式化新增 {{ aa ?? bb ?? 'default'}} 取值语法 - 新增: 添加 Chain 关于算力消耗配置的功能 - 新增: Chain 添加 loopNodeExecutionLimit 配置，保护由于用户配置不当可能造成死循环执行的问题 - 新增: 优化监听器，当多个监听器发生时，有监听器发生错误不影响其他监听器执行 - 新增: Node 支持配置积分消耗的计算逻辑和表达式 - 新增：图片消息添加多张图片的支持 - 新增：大模型节点添加图片识别的能力 - 新增：大模型节点支持多种 json 格式输出 - 新增：支持 Chroma 向量数据库（1.1.10），目前只支持单租户，单数据库（有默认且可配置），感谢 @joe.wen - 新增：TextPromptTemplate.f	Low	11/17/2025
v1.0.0	- fix: fixed NodeContext.isUpstreamFullyExecuted() method - feat: add "concurrencyLimitSleepMillis" config for SparkLlm - feat: openai add chatPath config and embed path config - feat: HistoriesPrompt add temporaryMessages config --- - 修复：NodeContext.isUpstreamFullyExecuted() 方法判断错误的问题 - 新增: SparkLlm 添加 concurrencyLimitSleepMillis 配置 - 新增: openai 添加 chatPath 配置和 embed path 配置 - 新增: HistoriesPrompt 添加 temporaryMessages 配置	Low	4/7/2025
v1.0.0-rc.9	- feat: Added support for vector database Pgvector, thanks @daxian1218 - feat: Chain added "SUSPEND" state and ChainSuspendListener listener - feat: Chain's RefType added "fixed" type. - feat: Chain's Parameter added "defaultValue" - feat: Chain added ChainResumeEvent event - feat: ChainNode added "awaitAsyncResult" property configuration - refactor: Return the complete response and answer information of coze chat to obtain complete information such as conversation_id, thanks @knowpigxia	Low	3/31/2025
v1.0.0-rc.8	- feat: Added LLM support for siliconflow, thanks [@daxian1218](https://gitee.com/daxian1218) - feat: Chain's dynamic code node supports running Javascript scripts, thanks [@hhongda](https://gitee.com/hhongda) - feat: Removed deepseek's invalid dependency on openai module, thanks [@daxian1218](https://gitee.com/daxian1218) - feat: Optimized EmbeddingModel and added direct embedding of String --- - 新增：新增 LLM 对 siliconflow（硅基流动）的支持，感谢 [@daxian1218](https://gitee.com/daxian1218) - 新增：Chain 的动	Low	3/18/2025
v1.0.0-rc.5	- feat: Added support for VectoRex vector database - feat: Added support for DeepSeek large models - feat: ImagePrompt adds support for local files, Stream and Base64 configurations - refactor: agents-flex-bom facilitates one-click import of all modules --- - 新增：添加 VectoRex 向量数据库的支持 - 新增：增加 DeepSeek 大模型的支持 - 新增：ImagePrompt 添加本地文件、Stream 和 Base64 配置的支持 - 优化：agents-flex-bom 方便一键导入所有模块	Low	2/10/2025
v1.0.0-rc.1	- refactor: add BaseFunction.java - fix: spark LLM can not support v4.0 - fix: fix code node can not get the parameters --- - 优化：新增 BaseFunction 类 - 修复：修复星火大模型不支持 v4.0 的问题 - 修复：修复代码节点无法获取参数的问题	Low	11/7/2024
v1.0.0-rc.0	- refactor: refactor llm apis - refactor: refactor chain and nodes - refactor: optimize agents-flex-solon-plugin [@noear_admin](https://gitee.com/noear_admin) --- - 重构：重构 llm api - 重构：重构 chain 链路及其相关节点 - 优化：优化 agents-flex-solon-plugin [@noear_admin](https://gitee.com/noear_admin)	Low	11/4/2024
v1.0.0-beta.12	## v1.0.0-beta.12 20241025 - refactor：add DocumentStoreConfig - refactor：optimize HistoriesPrompt.java - refactor: update pom.xml in agents-flex-bom - refactor: upgrade jedis version to "5.2.0" - refactor: optimize RedisVectorStore - fix: NoClassDefFoundError in jdk17: javax/xml/bind/DatatypeConverter --- - 优化：添加 DocumentStoreConfig，向量数据库的配置都实现 DocumentStoreConfig - 优化：重构优化 HistoriesPrompt，使其支持更多的属性配置 - 优化：更新 agents-flex-bom 的 pom.xml - 优化：升级 jedis 版本为 "5.2.0" - 优化：重构 RedisVectorS	Low	10/25/2024
v1.0.0-beta.10	- feat: Added support for RedisStore vector storage, thanks to @giteeClass - feat: Added support for large model dialogues for Coze Bot, thanks to @yulongsheng - feat: Automatic configuration of Springboot for ElasticSearch Store, thanks to @songyinyin - feat: Added support for Embedding of Tongyi Qianwen, thanks to @sssllg - feat: Added support for all text generation models of Gitee AI's serverless - feat: Added support for all image generation models of Gitee AI's serverless - docs: Cor	Low	9/9/2024

Dependencies & License Audit

Loading dependencies...

Similar Packages

@falai/agentStandalone, strongly-typed AI Agent framework with route DSL and AI provider strategymain@2026-09-05

AstrBotAgentic IM Chatbot infrastructure that integrates lots of IM platforms, LLMs, plugins and AI feature, and can be your openclaw alternative. ✨v4.28.0-beta.1

bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFv2.6.0-fix2

TuyaOpenNext-gen AI+IoT framework for T2/T3/T5AI/ESP32/and more – Fast IoT and AI Agent hardware integrationv1.9.0

aiflows🤖🌊 aiFlows: The building blocks of your collaborative AIv1.1.1

More in Frameworks

onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator

bamlThe AI framework that adds the engineering to prompt engineering (Python/TS/Ruby/Java/C#/Rust/Go compatible)

pyodpsODPS Python SDK and data analysis framework

DrasilGenerate all the things (focusing on research software)