# AgentFlow4J：Java 生态中的多 Agent 工作流编排框架

> 一个用于构建有状态多 Agent 工作流的 Java 框架，支持图结构编排、自动重试、持久化检查点和内置治理机制。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-24T10:15:18.000Z
- 最近活动: 2026-05-24T10:21:31.487Z
- 热度: 163.9
- 关键词: AgentFlow4J, Java, 多Agent系统, Spring AI, 工作流编排, LLM应用, 企业级AI, 状态管理, Agent治理, 生产级框架
- 页面链接: https://www.zingnex.cn/forum/thread/agentflow4j-java-agent
- Canonical: https://www.zingnex.cn/forum/thread/agentflow4j-java-agent
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者**：DataLLM Hub
- **来源平台**：GitHub
- **原始标题**：AgentFlow4J
- **原始链接**：https://github.com/datallmhub/agentflow4j
- **发布时间**：2026年5月24日

---

## 背景：Java 生态中的 Agent 编排缺口

随着大型语言模型（LLM）应用的普及，多 Agent 系统（Multi-Agent Systems）正在成为构建复杂 AI 应用的主流架构。在 Python 生态中，LangChain、AutoGen 等框架已经提供了丰富的 Agent 编排能力。然而，对于大量使用 Java 的企业级应用来说，选择却相对有限。

Spring AI 的出现填补了一部分空白，它提供了与 LLM 交互的基础能力（ChatClient、工具调用等），但在多 Agent 编排、状态管理、故障恢复等方面，开发者仍然需要编写大量的胶水代码。

AgentFlow4J 正是为了解决这一问题而生。它构建在 Spring AI 之上，为 Java 开发者提供了一套完整的、生产级的多 Agent 工作流编排方案。

---

## 项目概述：有状态的多 Agent 运行时

AgentFlow4J 的核心理念是：将多 Agent 工作流视为一个**运行时问题**，而非单纯的代码组织问题。

现实世界中的 AI 系统往往具有以下特征：

- **多步骤**：一个任务需要多个 Agent 协作完成
- **有状态**：执行过程中需要维护和共享上下文
- **易失败**：LLM 调用可能超时、返回格式错误、或产生幻觉
- **长运行**：某些工作流可能需要数分钟甚至数小时才能完成

AgentFlow4J 提供了处理这些复杂性的结构化方案，让开发者可以专注于业务逻辑，而非底层的编排细节。

---

## 核心特性：从编排到治理

### 1. 双 API 设计：Squad API 与 Graph API

项目提供了两个层次的 API，适应不同的使用场景：

**Squad API** 适合动态路由场景，配置简单：

```java
CoordinatorAgent coordinator = CoordinatorAgent.builder()
    .executors(Map.of("research", researcher, "writing", writer))
    .routingStrategy(RoutingStrategy.llmDriven(chatClient))
    .build();

AgentResult result = coordinator.execute(
    AgentContext.of("Compare Claude 4 and GPT-5"));
```

**Graph API** 适合需要显式控制流的场景，支持循环、条件分支和完整的状态管理：

```java
AgentGraph graph = AgentGraph.builder()
    .addNode("triage", triageAgent)
    .addNode("specialist", specialistAgent)
    .addNode("policy_gate", policyAgent)
    .addEdge("triage", "specialist")
    .addEdge("specialist", "policy_gate")
    .checkpointStore(jdbcStore)
    .build();
```

### 2. 有状态执行与持久化

与无状态的单次 LLM 调用不同，AgentFlow4J 提供了完整的**类型化状态管理**：

- 使用 `StateKey<T>` 替代原始的 `Map<String, Object>`，在编译期就能捕获类型错误
- 支持检查点（checkpoint）机制，工作流可以在任意节点暂停并在之后恢复
- 内置 JDBC 和 Redis 两种检查点存储实现

这意味着即使应用重启，未完成的工作流也可以从中断点继续执行，而不会丢失上下文。

### 3. 内置弹性机制

生产环境中的 LLM 调用不可避免地会遇到各种问题。AgentFlow4J 内置了多种弹性策略：

- **重试（Retry）**：可配置的重试策略，支持指数退避
- **熔断（Circuit Breaker）**：当 LLM 服务不稳定时自动降级
- **预算控制（Budget Policy）**：限制单次运行的 Token 消耗和 API 调用成本

这些机制都可以通过声明式配置启用，无需在业务代码中手动实现。

### 4. 治理优先：安全与可控

AgentFlow4J 的一个重要设计哲学是：**Agent 不应被隐式信任**。框架提供了多种治理机制：

**工具策略（Tool Policy）**：精确控制每个 Agent 可以调用的工具

```java
ExecutorAgent paymentAgent = ExecutorAgent.builder()
    .tools(webSearch, shellTool)
    .toolPolicy(ToolPolicy.allowList("web.search")
        .and(ToolPolicy.denyList("shell.execute")))
    .build();
```

**状态策略（State Policy）**：保护敏感状态键不被写入

```java
AgentGraph.builder()
    .statePolicy(StatePolicy.denyWriteKeys("payment.confirmed", "user.ssn"))
```

**审批门（Approval Gate）**：在高风险操作前暂停，等待人工确认

```java
AgentGraph.builder()
    .approvalGate(ApprovalGate.requireFor("payment.transfer"))
```

**预算策略（Budget Policy）**：分层控制成本

```java
BudgetPolicy.hierarchical(
    BudgetLimits.run(2.00),  // 单次运行上限
    BudgetLimits.node(0.50), // 单个节点上限
    estimator, 
    meter
)
```

这些治理机制都是可选的，默认零开销，只有在显式启用时才生效。

---

## 技术架构与模块设计

AgentFlow4J 采用模块化设计，核心模块包括：

| 模块 | 用途 |
|------|------|
| `agentflow4j-core` | 最小化 API（Agent、AgentContext、StateKey、AgentResult） |
| `agentflow4j-graph` | AgentGraph、重试/熔断/预算策略、检查点契约 |
| `agentflow4j-squad` | CoordinatorAgent、ExecutorAgent、ReActAgent、ParallelAgent |
| `agentflow4j-checkpoint` | JDBC 和 Redis 检查点存储、Jackson 序列化 |
| `agentflow4j-resilience4j` | 基于 Resilience4j 的熔断策略适配器 |
| `agentflow4j-playground` | 可嵌入的 Web UI，用于与 Agent Bean 交互 |
| `agentflow4j-cli-agents` | 将 Claude Code / Codex / Gemini CLI 作为图节点 |
| `agentflow4j-test` | MockAgent、TestGraph，支持无 LLM 的单元测试 |

这种模块化设计让开发者可以根据需要选择依赖，避免引入不必要的功能。

---

## 快速上手：30 秒体验

项目提供了开箱即用的示例，无需配置 API 密钥即可运行：

```bash
git clone https://github.com/datallmhub/agentflow4j.git
cd agentflow4j
mvn install -DskipTests -q
mvn -pl agentflow4j-samples exec:java
```

这会运行 `SupportTriageDemo`：一个客户支持工单处理工作流，展示工单如何在 Agent 图中流转（分类 → 专家处理 → 策略检查 → 回复）。

离线状态下使用确定性存根（stub），设置 `MISTRAL_API_KEY` 环境变量后则会调用真实的 Mistral API。

---

## 与 Spring AI 的关系

AgentFlow4J 构建在 Spring AI 之上，两者是互补关系：

| Spring AI | AgentFlow4J |
|-----------|-------------|
| 提供基础原语（ChatClient、工具） | 提供结构化运行时（AgentGraph、CoordinatorAgent） |
| 需要手动编排 | 基于图的执行引擎 |
| 无持久化状态 | 类型化共享状态 + 检查点 |
| 重试逻辑需自行实现 | 内置重试 + 熔断 |
| 不支持恢复 | 支持中断和恢复 |
| Agent 完全受信任 | 受控执行（工具、状态、成本、审批） |

如果你只是偶尔调用一次 `ChatClient`，Spring AI 已经足够。但如果你的 Agent 需要多次 LLM 调用、有分支或循环、故障很重要、或多个 Agent 需要协调，AgentFlow4J 提供了必要的运行时支持。

---

## 应用场景

AgentFlow4J 适用于多种企业级场景：

### 复杂审批工作流

例如采购申请需要经过：部门经理审批 → 财务审核 → 合规检查 → 最终批准。每个步骤都可以是一个 Agent，根据文档内容做出决策。

### 多步骤数据分析

数据科学家可以构建工作流：数据清洗 Agent → 特征工程 Agent → 模型选择 Agent → 结果解释 Agent，每个步骤都有明确的输入输出和检查点。

### 客户服务自动化

客服场景通常需要多个专业 Agent 协作：意图识别 → 知识库检索 → 解决方案生成 → 满意度确认，AgentFlow4J 可以协调这一复杂流程。

### 代码审查助手

将 Claude Code、Codex 或 Gemini CLI 作为图节点，构建自动化的代码审查工作流：静态分析 → 安全扫描 → 风格检查 → 性能建议。

---

## 生态与路线图

AgentFlow4J 目前处于活跃开发阶段，版本规划如下：

| 版本 | 状态 | 重点 |
|------|------|------|
| 0.5 | 已发布 | 子图、并行扇出、取消、类型化输出、重试/熔断 |
| 0.6 | 已发布 | 治理层（工具策略、状态策略、审批门、预算策略） |
| 0.7 | 规划中 | 分布式执行、事件溯源、更多存储后端 |

项目采用 Apache 2.0 许可证，通过 JitPack 分发，支持 Maven 和 Gradle 集成。

---

## 总结

AgentFlow4J 为 Java 企业级应用带来了缺失的多 Agent 编排能力。它的价值不仅在于提供了另一种选择，更在于其**生产优先**的设计理念：

1. **结构化运行时**：将多 Agent 执行视为一等公民，而非事后补丁
2. **弹性内置**：重试、熔断、检查点无需额外实现
3. **治理优先**：工具、状态、成本、审批的可控性
4. **渐进采用**：从简单的 Squad API 开始，按需迁移到 Graph API

对于正在构建 LLM 驱动应用的 Java 团队，AgentFlow4J 是一个值得认真评估的框架。它填补了 Spring AI 在编排层面的空白，同时保持了与 Spring 生态的深度集成。