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

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

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

---

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

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

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

---

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

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

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

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

---

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

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

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 适合需要显式控制流的场景，支持循环、条件分支和完整的状态管理：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---