---

🔥Agents-Flex：企业级LLM应用开发框架完全指南

——让Java开发者轻松驾驭AI Agent，从入门到生产落地

---

📌 一、项目概述

Agents-Flex 是一个专为Java工程师和架构师设计的轻量级、模块化、可扩展的AI Agent开发框架，旨在帮助企业快速构建生产级LLM应用程序。

🎯 核心设计理念

特性	说明
零侵入集成	通过接口驱动开发，不影响现有业务代码
配置即代码	告别硬编码，通过配置中心统一管理
生产级 Ready	完整支持监控、 tracing、安全防护
多模态支持	文本、图像、音频、文档理解一站式搞定

📊 当前版本与状态

•最新版本: v2.0.2 (2026年3月4日)•License: Apache License 2.0•Java版本: Java 8+•官方文档: https://agentsflex.com^[1]

---

🚀 二、核心特性详解（v2.0+）

1. MCP（Model Context Protocol）原生支持

MCP是AI Agent领域的java // MCP工具调用示例 McpTool mcpTool

mcpTool.setConnectionType(McpConnectionType.STDIO);mcpTool.setCommand("/usr/local/bin/mcp-server");

适用场景：

•跨系统上下文共享•工具编排与 orchestration•企业内部系统集成

2. AI Skills（智能体技能系统）

将业务能力封装为可复用、可组合java Skill skill = Skill.builder() .name("订单查询") .description("查询用户订单信息") .parameter("userId", "

" style="box-sizing: border-box; margin: 0px; padding: 1em 1em 1em 0px; overflow-x: auto; white-space: normal; flex: 1 1 0%;">    <groupId>com.agentsflex</groupId>    <artifactId>agents-flex-core</artifactId>    <version>2.0.2</version></dependency>
<!-- MCP扩展（可选） --><dependency>    <groupId>com.agentsflex</groupId>    <artifactId>agents-flex-mcp</artifactId>    <version>2.0.2</version></dependency>

2. 第一个Hello World

public class QuickStart {    public static void main(String[] args) {        // 1. 配置模型（支持GitHub AI/OpenAI/Ollama等）        OpenAiChatModel chatModel = OpenAiChatConfig.builder()            .provider("GitHubAI")            .endpoint("https://ai.github.com")            .requestPath("/v1/chat/completions")            .apiKey(System.getenv("GITHUB_AI_KEY")) // 建议从环境变量加载            .model("Qwen3-32B")            .buildModel();
        // 2. 开始对话（同步/流式/异步均支持）        String response = chatModel.chat(            "Explain what humors is in a way that Java developers can understand?"        );
        // 3. 输出结果        System.out.println("[Agents-Flex]: " + response);    }}

控制台输出示例：

[Agents-Flex] >>>> [GitHubAI/Qwen3-32B] Request: {"model":"Qwen3-32B","messages":[...]}[Agents-Flex] <<<< [GitHubAI/Qwen3-32B] Response: 200 OK (1.2s)[Agents-Flex]: Humors is like exception handling in code...

⚠️ 生产环境建议：通过 application.properties 配置日志前缀，生产部署推荐使用SLF4J集成。

---

💡 五、核心功能深度指南

1. 聊天引擎（Chat）

Agents-Flex提供**完整的对话能力矩阵java // 同步调用 String response = chatModel.chat("你的问题");

// 流式调用（推荐

chatModel.chatStream("你的问题", new StreamResponseListener() {    @Override    public void onMessage(String content) {        System.out.print(content);  // 实时输出    }
    @Override    public void onDone() {        System.out.println("\n[流式输出完成]");    }});
// 异步调用CompletableFuture<String> future = chatModel.chatAsync("你的问题");

2. 提示词模板（Prompt Template）

支持变量替换和**模板复用java // 定义模板 PromptTemplate template = PromptTemplate.builder() .template("请分析以下{{language}}代码的复杂度

<pre class="code-snippet__js" data-lang="：\n\n{{code}}" )"="" style="box-sizing: border-box; margin: 0px; padding: 1em 1em 1em 0px; overflow-x: auto; white-space: normal; flex: 1 1 0%;">    .build();// 使用模板Prompt prompt = template.toPrompt(Map.of(    "language", "Java",    "code", "public void process() {...}"));

3. java

// 定义工具 Tool tool = Tool.builder() .name("get_weather") .

.parameter("city", "城市名称", ParamType.STRING)    .parameter("unit", "温度单位", ParamType.STRING,                Arrays.asList("celsius", "fahrenheit"))    .handler((params, context) -> {        String city = params.get("city");        return weatherService.getWeather(city);    })    .build();
// 执行带工具的对话AiMessage response = chatModel.chatWithTools(    "北京明天天气怎么样？",    Arrays.asList(tool));

###java // 简单记忆 Memory memory = new SimpleMemory();

// 带历史记忆 List

new UserMessage("我喜欢编程"),    new AssistantMessage("很棒！你喜欢哪种语言？"));Memory memory = new HistoryMemory(history);
// 自定义记忆策略Memory customMemory = new CustomMemory()    .maxTokens(4000)    .summaryStrategy(new SummaryStrategy());

5. 向量存储（Rjava

// Milvus示例 MilvusStore store = new MilvusStore(); store

store.setPort(19530);store.setCollectionName("my_docs");
// 存储向量VectorData data = new VectorData()    .setId("doc_001")    .setText("这是文档内容...")    .setVector(embeddingResult.getVector());store.store(data);
// 相似度检索List<VectorData> results = store.search(    embedding,  // 查询向量    10,         // 返回数量    0.7f        // 相似度阈值);

6. MCP协议集成java

// STDIO连接（本地进程） McpClient stdioClient = new McpClient();

stdioClient.setCommand("npx -y @modelcontextprotocol/server-filesystem /data");
// SSE连接（远程服务）McpClient sseClient = new McpClient();sseClient.setTransportType(McpTransportType.SSE);sseClient.setUrl("https://mcp-server.example.com/sse");
// 获取工具列表并调用List<McpTool> tools = sseClient.listTools();McpToolResult result = sseClient.callTool("tool-name", params);

---

🎯 六、生产环境最佳实践

1. Spring Boot集成（推荐）

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

# application.ymlagents-flex:  model:    default-provider: github-ai    providers:      github-ai:        endpoint: ${GITHUB_AI_ENDPOINT:https://ai.github.com}        api-key: ${GITHUB_AI_KEY}        model: Qwen3-32B  endpoints:    web:      expose: metrics,trace  # 暴露监控端点

2. 安全配置

// 敏感信息加密配置@Value("${api.key}")private String apiKey;  // 通过环境变量或加密配置中心加载
// 推荐：使用配置中心的密文String decryptedKey = vaultClient.read("secret/agents-flex/api-key");

3. 监控与yaml

management: endpoints: web: exposure: include: health,info,metrics,prometheus,trace tracing: sampling: probability: 1.0 # 生产环境建议0.1

### 4. 分布式追踪

框架深度集成 OpenTelemetry，自动埋点：

•请求耗时•Token消耗•错误率•工具调用链路

---

📚 七、进阶场景示例

场景java

// 1. 文档加载 DocumentLoader loader = new TextFileLoader("docs/guide

<pre class="code-snippet__js" data-lang=".md" );"="" style="box-sizing: border-box; margin: 0px; padding: 1em 1em 1em 0px; overflow-x: auto; white-space: normal; flex: 1 1 0%;">List<Document> docs = loader.load();// 2. 文本分块TextSplitter splitter = new RecursiveTextSplitter(500);List<TextSegment> segments = splitter.split(docs);// 3. 向量化EmbeddingModel embeddingModel = new OpenAiEmbeddingModel();List<Float[]> vectors = embeddingModel.embed(segments);// 4. 存储到向量库milvusStore.store(segments, vectors);// 5. 检索增强QueryResult relevantDocs = milvusStore.search(queryVector, topK=3);String context = relevantDocs.stream()    .map(d -> d.getText())    .collect(Collectors.joining("\n"));// 6. 生成回答String answer = chatModel.chat(    promptTemplate.apply("context", context, "question", query));

场景2：多Agent协作

// 定义Agent角色Agent researcher = Agent.builder()    .name("研究员")    .systemPrompt("你擅长信息搜集...")    .tools(searchTool, scraperTool)    .build();
Agent analyst = Agent.builder()    .name("分析师")    .systemPrompt("你擅长数据分析...")    .tools(calculatorTool, chartTool)    .build();
// 协作流程String researchResult = researcher.chat("研究AI最新趋势");String analysisResult = analyst.chat("分析: " + researchResult);

场景3：Text2SQL业务java

// 配置数据库Schema上下文 SchemaContext schema = new SchemaContext() .addTable("orders", "订单表

<pre class="code-snippet__js" data-lang="" ,"="" style="box-sizing: border-box; margin: 0px; padding: 1em 1em 1em 0px; overflow-x: auto; white-space: normal; flex: 1 1 0%;">        Column.of("id", "订单ID"),        Column.of("user_id", "用户ID"),        Column.of("amount", "金额", ColumnType.DECIMAL),        Column.of("created_at", "创建时间"))    .addTable("products", "商品表",        Column.of("id", "商品ID"),        Column.of("name", "商品名称"));// 自然语言查询Text2SqlAgent agent = new Text2SqlAgent(chatModel, schema);Text2SqlResult result = agent.analyze(    "统计2024年每月销售额最高的商品",    DataVisualizationChart.builder()        .type(ChartType.LINE)        .title("月度销售趋势")        .build());System.out.println(result.getSql());System.out.println(result.getChartConfig());  // 可直接用于前端渲染

---

🔧 八、常见问题FAQ

Q1: 如何选择合适的模型？

场景	推荐模型
对话交互	Qwen3-32B, GPT-4o
代码生成	Qwen3-32B, Claude-3.5
embedding	text-embedding-3-small, bge-m3
图像生成	DALL-E 3, Stable Diffusion

java // 配置重试策略 ChatOptions options = ChatOptions.builder() .maxRetries(3) .retryDelay(1000) // 毫秒 .build();

###java// 实现CustomModel接口public class MyModel extends AbstractChatModel {
```    @Override    public ChatResponse doChat(List<Message> messages, Options options) {        // 自定义调用逻辑    }}
// 注册到框架ModelRegistry.register("my-model", new MyModel());

---

📈 九、版本演进与迁移

v2.0 重大更新

•✅ MCP协议原生支持•✅ AI Skills技能系统•✅ Text2SQL增强•✅ SSE流式传输优化•✅ OpenTelemetry深度集成

升级注意事项

xml

2.0

<!-- 2. 检查API变更 --><!-- ChatModel API保持兼容 --><!-- 部分配置类有BC Break，需逐个检查 -->

---

🤝 十、贡献与生态

如何参与

1.Fork 仓库2.创建特性分支：git checkout -b feature/xxx3.代码规范：运行 mvn spotless:apply（Google Java Style）4.提交PR，关联Issue

相关资源

资源	链接
官方文档	https://agentsflex.com[2]
示例项目	/demos
中文文档	/readme_zh.md
变更日志	/changes.md
Issue Tracker	GitHub Issues

---

📝 总结

Agents-Flex 为Java开发者提供了一条低门槛、高效率、可信赖的AI应用开发路径：

•🎯 开箱即用：5分钟快速入门•🛡️ 生产就绪：监控、安全、追踪全面支持•🔄 灵活扩展：模块化架构，按需定制•🌐 生态丰富：支持10+向量库、主流模型供应商•📚 文档完善：中英文文档+持续更新

立即访问 https://agents-flex.com^[3] 开启AI开发之旅！

---

本文档基于仓库 v2.0.2 版本编写，最新更新：2026年3月

References

[1]: https://agentsflex.com
[2]: https://agentsflex.com
[3]: https://agents-flex.com