agents-flex/agents-flex

什么是 Agents-Flex？

Agents-Flex 是一个 以 Java 为优先的框架，用于构建与大型语言模型 (LLM) 及其他 AI 服务交互的应用程序。它将 LLM 驱动系统的常见组件（聊天、嵌入、图像/音频生成、工具调用、检索增强生成 (RAG)、向量存储、可观测性等）打包成一组可灵活组合的 模块化 Maven 构件。其目标是让 Java 开发者仅需编写所需的组件，而无需被绑定在特定的执行环境（纯 Java、Spring Boot 或其他 JVM 堆栈）。

---

核心理念与架构

理念	在代码中的体现
统一模型抽象	如 ChatModel、EmbeddingModel、ImageModel、RerankModel 等接口隐藏了供应商特定的 API（OpenAI、Qwen、Ollama 等）。
同步与流式 API	相同的 Prompt、ChatOptions 和拦截器链适用于一般的 chat() 调用与 chatStream() 回调。
工具调用	标注了 Java 方法（@ToolDef、@ToolParam）会被扫描为 Tool 对象；框架会构建请求、执行工具并将结果回传给模型。
持久化代理执行环境	agents-flex-agent 提供了一个状态机，可以暂停、恢复、快照并持久化执行状态（JDBC/Redis 存储）。
RAG 构建组件	文档加载器、解析器、分割器、嵌入生成器、向量存储适配器和重排序器是独立的模块，可以相互连接。
生产级考量	内置模型路由、负载均衡、重试、断路器和 OpenTelemetry 导出器。
插件式扩展性	透过实现对应接口并将模块作为 Maven 依赖项加入，即可新增工具、向量存储或模型供应商。

---

主要模块（概览）

• agents-flex-core – 基础类型（Prompt、Message、Tool、Memory、Document）。
• agents-flex-chat, -embedding, -image, -audio, -ocr, -video – 针对多种供应商的具体模型适配器。
• agents-flex-store – 针对 Redis、Qdrant、Chroma、Milvus、Elasticsearch 等的适配器。
• agents-flex-agent & -agent-store – 协调执行流程、处理工具调用并持久化状态的执行环境。
• agents-flex-tool & -toolsearch – 现成的工具（shell、文件、网页抓取）及可搜索的注册表。
• agents-flex-mcp – 将外部 MCP 服务转换为 Tool 对象的客户端。
• agents-flex-skills 系列 – 可沙盒化的基于文件系统的“技能包”。
• agents-flex-text2sql – 具备架构发现功能的安全、只读自然语言转 SQL 转换。
• agents-flex-wiki – 代理可逐页浏览的层级式知识库。
• agents-flex-spring-boot-starter – 最常见模型与存储的自动配置。
• demos – 展示聊天、工具调用、RAG 及代理工作流程的可执行示例。

---

典型使用流程（示例）

1. 加入 Maven 依赖 – 使用 BOM (agents-flex-bom) 或所需的特定模块（例如 agents-flex-chat-openai + agents-flex-store-redis）。
2. 配置模型 – 透过供应商特定的配置构建器创建 ChatModel（参阅快速入门）。同一个模型可用于一般或流式调用。
3. 定义工具 – 使用 @ToolDef/@ToolParam 标注 Java 方法或以程序方式构建。将工具注册到 Prompt 或 ToolGroup。
4. 构建 Prompt – 结合用户文字、系统指令及选定的工具组。
5. 调用模型 – chat() 会回传 AiMessageResponse。若 hasToolCalls() 为真，则执行工具（executeToolCallsAndGetToolMessages()）并将更新后的 prompt 送回。
6. (选用) 执行代理 – 将上述流程包装在 AgentRunner 中，以获得自动快照、审核钩子与持久化功能。
7. (选用) 加入 RAG – 加载文档、分割、嵌入、存储至向量数据库、检索段落、选择性重排序，然后将检索到的文字喂入 prompt。
8. 观察 – OpenTelemetry 导出器会发出 span/metrics；可透过 -Dagentsflex.otel.enabled=true 启用。

---

谁适合使用？

• Java 后端团队：需要加入 LLM 驱动功能（聊天机器人、代码助手、数据分析代理）且不想切换到 Python 的团队。
• 企业：需要持久性、可审计性并与现有 JVM 基础设施（Spring Boot、JDBC、Redis 等）整合的企业。
• 构建多模型服务的开发者：路由与负载均衡功能让您能在单一端点中混合使用 OpenAI、Qwen、Ollama 等模型。
• 需要插件式工具生态的团队：基于标注的工具扫描器与 MCP 客户端，能轻松将内部服务公开为 LLM 可调用的工具。

---

优势与限制

优势	限制
Java 原生 – 无需 JNI 或外部 Python 执行环境。	生态规模 – 社区贡献的模块比以 Python 为中心的库少。
模块化 Maven 构件 – 仅需发布使用的部分，保持最终 JAR 文件轻量。	学习曲线 – 拦截器链与工具组匹配增加了概念上的复杂度。
内置生产级功能（路由、断路器、OpenTelemetry）。	文档 – 主要为中文/英文 markdown；示例仅限于 demos 文件夹。
丰富的工具调用支持（标注、动态群组、MCP）。	执行环境弹性 – 仍绑定于 JVM；不适合边缘设备或非 Java 堆栈。

---

快速入门

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

执行 demos/chat-demo 模块以取得包含工具调用与流式的完整示例。

---

授权与社区

Agents-Flex 采用 Apache 2.0 授权，可免费商用。存储库显示了由 contrib.rocks 产生的贡献者徽章，代表这是一个开源社区，尽管 README 并未列出个别贡献者。

---

简而言之： Agents-Flex 为 Java 开发者提供了一个生产级工具箱，用于 LLM 聊天、工具协调、RAG 及相关 AI 功能，所有功能皆封装为可互换的 Maven 模块，可轻松放入任何 JVM 应用程序中。