一款优雅的 Java 框架，用于 LLM 应用开发 | 真正开源 · 易于集成 · 生产就绪

🚀 核心特性

Agents-Flex 专为 Java 工程师和架构师设计，提供一种 轻量级、模块化且可扩展 的 AI 代理开发体验，帮助企业快速构建生产级 LLM 应用。

✨ 新核心能力 (v2.0+)

特性	描述	使用场景
MCP 支持	原生集成模型上下文协议，实现与外部数据源和工具的标准化连接	跨系统上下文共享、工具编排
AI 技能	将业务能力封装为可复用、可组合的 Skill 单元	快速构建领域 Agent、技能市场
Text2SQL / 智能数据查询	内置 Text2SQL 和自然语言数据分析能力	面向业务用户的零代码查询、数据洞察

🔧 核心能力矩阵

🧠 模型集成    🔌 工具调用        📚 知识增强
├─ 主流 LLMs      ├─ 函数调用        ├─ 多格式文档加载
├─ Ollama 本地部署  ├─ MCP 工具协议       ├─ 智能文本分割
├─ HTTP/SSE/WS 协议  ├─ 本地方法反射     ├─ 向量存储集成
├─ 多提供商管理  ├─ 执行拦截器       ├─ 自定义嵌入支持

⚙️ 工程支持  🔍 可观测性          🛡️ 企业级保障
├─ 提示模板引擎  ├─ OpenTelemetry 集成  ├─ 敏感数据脱敏
├─ 多轮记忆      ├─ 分布式追踪      ├─ 安全资源关闭
├─ 异步/流式响应  ├─ 结构化日志      ├─ Apache 2.0 许可证

💡 设计原则: 零侵入集成 · 接口驱动扩展 · 配置优先于代码 · 生产友好

⚡ 快速入门

1️⃣ 添加依赖 (Maven)

<dependency>
    <groupId>com.agentsflex</groupId>
    <artifactId>agents-flex-core</artifactId>
    <version>2.0.7</version>
</dependency>
<!-- 可选：根据需要添加扩展模块 -->
<dependency>
    <groupId>com.agentsflex</groupId>
    <artifactId>agents-flex-mcp</artifactId>
    <version>2.0.7</version>
</dependency>

2️⃣ Hello World

public class QuickStart {
    public static void main(String[] args) {
        // 1. 配置模型（支持 GiteeAI / OpenAI / Ollama 等）
        OpenAIChatModel chatModel = OpenAIChatConfig.builder()
            .provider("GiteeAI")
            .endpoint("https://ai.gitee.com")
            .requestPath("/v1/chat/completions")
            .apiKey(System.getenv("GITEE_AI_KEY")) // ✅ 建议从环境变量加载
            .model("Qwen3-32B")
            .buildModel();

        // 2. 开始对话（同步/流式/异步均支持）
        String response = chatModel.chat("用 Java 开发者能理解的方式解释一下什么是幽默？");

        // 3. 输出结果
        System.out.println("🤖 Agents-Flex: " + response);
    }
}

控制台输出示例:

[Agents-Flex] >>> [GiteeAI/Qwen3-32B] 请求: {"model":"Qwen3-32B","messages":[...]}
[Agents-Flex] <<< [GiteeAI/Qwen3-32B] 响应: 200 OK (1.2s)
🤖 Agents-Flex: 幽默就像代码中的优雅异常处理——看似出乎意料，却经过精心设计……

📝 [Agents-Flex] 日志前缀可通过 application.properties 自定义或禁用。对于生产环境，建议集成 SLF4J。

📦 模块概览

agents-flex/
├── agents-flex-bom                    # 📦 BOM 依赖管理，统一版本号
├── agents-flex-core                   # 🧱 核心抽象：模型/提示/记忆/工具 SPI
├── agents-flex-chat                   # 💬 对话引擎：同步/流式/异步调用
├── agents-flex-tool                   # 🔧 函数调用引擎：方法定义/解析/执行
├── agents-flex-mcp                    # 🔗 MCP 协议支持：标准化上下文与工具连接（新增）
├── agents-flex-skills                 # 🎯 AI 技能：能力封装与动态加载（新增）
├── agents-flex-text2sql               # 📊 Text2SQL 与自然语言数据分析（新增）
├── agents-flex-embedding              # 🔢 嵌入服务：模型集成与向量生成
├── agents-flex-store                  # 🗄️ 存储扩展：VectorStore/内存持久化实现
├── agents-flex-search-engine          # 🔍 搜索引擎集成：ES/DB/自定义检索源
├── agents-flex-rerank                 # 📈 重排序服务：提升 RAG 检索相关性
├── agents-flex-image                  # 🖼️ 图像能力：图文互转模型集成
├── agents-flex-spring-boot-starter   # ⚙️ Spring Boot 自动配置（推荐用于生产）
├── demos/                             # 🧪 示例项目：MCP / 技能 / Text2SQL 演示
├── docs/                              # 📚 文档源（VitePress）
└── testresource/                      # 🧪 测试资源文件

✅ 生产就绪建议：

• 在生产环境中使用 agents-flex-spring-boot-starter 配合配置中心管理 API 密钥
• 通过 @Value("${xxx}") 注入敏感信息（API 密钥 / 数据库密码）并结合加密配置
• 启用 management.endpoints.web.exposure.include=metrics,trace 以集成监控
• 对于 RAG 场景，可组合使用：data + embedding + store + rerank 模块

📚 文档与资源

类型	链接	描述
📘 中文文档	https://agentsflex.com	完整 API 指南 + 最佳实践
🧪 示例项目	/demos	MCP 集成 / 技能编排 / Text2SQL 演示
📋 更改日志	/changes.md	版本历史与迁移指南
🐛 问题跟踪	GitHub Issues	Bug 报告 / 功能请求
💬 社区	加入讨论	问答、创意与社区支持

🤝 贡献

我们遵循 Apache Way 和 Contributor Covenant 指南：

1. Fork 仓库 → 创建功能分支 (feature/xxx)
2. 代码风格：运行 mvn spotless:apply 进行自动格式化（Google Java Style）
3. 添加单元测试：核心模块覆盖率目标 ≥ 80%
4. 提交 PR，并关联 Issue，详细说明变更动机及影响

🌟 特别欢迎：Java 8/11/17 兼容性测试、企业级用例以及文档翻译

---

📜 许可证

Agents-Flex 采用 Apache 许可证 2.0 发布。您可以自由地：

• ✅ 在您的项目中进行商业使用
• ✅ 进行修改并在私有环境中部署
• ✅ 贡献代码以丰富生态系统

分发时请保留原始版权声明，并注明所做的修改。详情请参阅 LICENSE。

Agents-Flex 快速上手指南

Agents-Flex 是一款专为 Java 工程师设计的轻量级、模块化 LLM 应用开发框架。它支持主流大模型集成、MCP 协议、AI Skills 以及 Text2SQL 等企业级功能，旨在帮助开发者快速构建生产级的 AI 应用。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• JDK 版本：建议 JDK 8, 11 或 17+（框架兼容多版本 Java）。
• 构建工具：Maven 3.6+ 或 Gradle。
• API Key：准备好一个大模型服务的 API Key（本指南以 GiteeAI 为例，也支持 OpenAI、Ollama 等）。

2. 安装步骤

在您的 Maven 项目 pom.xml 文件中添加核心依赖。如需使用 MCP 协议等扩展功能，可额外添加对应模块。

<dependencies>
    <!-- 核心模块 -->
    <dependency>
        <groupId>com.agentsflex</groupId>
        <artifactId>agents-flex-core</artifactId>
        <version>2.0.7</version>
    </dependency>
    
    <!-- 可选：MCP 协议支持模块 -->
    <dependency>
        <groupId>com.agentsflex</groupId>
        <artifactId>agents-flex-mcp</artifactId>
        <version>2.0.7</version>
    </dependency>
</dependencies>

💡 生产建议：如果是 Spring Boot 项目，推荐直接使用 agents-flex-spring-boot-starter 以获得自动配置支持。

3. 基本使用

以下是一个最简单的 Hello World 示例，展示如何配置模型并进行同步对话。

代码示例

import com.agentsflex.core.llm.chat.OpenAIChatConfig;
import com.agentsflex.core.llm.chat.OpenAIChatModel;

public class QuickStart {
    public static void main(String[] args) {
        // 1. 配置模型（支持 GiteeAI / OpenAI / Ollama 等）
        OpenAIChatModel chatModel = OpenAIChatConfig.builder()
            .provider("GiteeAI")
            .endpoint("https://ai.gitee.com")
            .requestPath("/v1/chat/completions")
            .apiKey(System.getenv("GITEE_AI_KEY")) // ✅ 推荐从环境变量加载 Key
            .model("Qwen3-32B")
            .buildModel();

        // 2. 发起对话（支持同步、流式、异步调用）
        String response = chatModel.chat("Explain what humor is in a way that Java developers can understand?");

        // 3. 输出结果
        System.out.println("🤖 Agents-Flex: " + response);
    }
}

运行结果

控制台将输出类似以下内容：

[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...

下一步

• 更多模型：修改 provider 和 endpoint 即可切换至 OpenAI、Ollama 或其他兼容 OpenAI 接口的服务。
• 高级功能：查看 /demos 目录了解 MCP 集成、Skills 编排及 Text2SQL 的具体实现。
• 详细文档：访问 https://agentsflex.com 获取完整的 API 指南和最佳实践。