Java多Agent工程架构实战：基于Graph工作流的企业级协作模板

很多关于 Agent 的教程都有一个通病：它们只停留在演示模型的层面，却难以直接应用到真实的系统构建中。你是否经常看到这样的例子？

• 单个 Agent，所有业务逻辑都堆砌在一个冗长的 Prompt 里。
• 缺乏有效的状态管理，上下文生命周期混乱。
• 采用简单的链式 Pipeline，一个环节失败就导致整个流程崩溃。
• 难以扩展、无法编排、缺少监控。

然而，在企业级的真实场景中，Agent 需要应对的挑战要复杂得多：

• 复杂的业务流程：例如审批、风控、售后处理或数据分析流程。
• 多个职责角色：需要分析、决策、执行、校验等多个 Agent 分工协作。
• 系统级要求：流程必须可回滚、可观测、并且能够灵活扩展。

这说明，企业级 Agent 不仅仅是 Prompt 工程，而是一个“可编排的智能系统”。

一、整体架构：企业级多 Agent + Graph 工作流

我们先从顶层设计开始，给出一个全局的、可落地的架构视图。

1.1 架构核心思想

Agent 负责“能力”
Graph 负责“流程”
Spring Boot 负责“工程化”

1.2 架构图（逻辑视图）

┌──────────────┐
│  Client/API  │
└──────┬───────┘
       │
┌──────▼────────┐
│ Agent Orchestr│  ← Graph 工作流引擎
└──────┬────────┘
       │
 ┌─────▼─────┐      ┌────────────┐
 │ Analyzer  │ ---> │ Planner    │
 └─────┬─────┘      └─────┬──────┘
       │                  │
 ┌─────▼─────┐      ┌─────▼──────┐
 │ Executor  │ <--- │ Validator  │
 └───────────┘      └────────────┘

在这个架构中，每个 Agent 都遵循单一职责原则：

• 只负责一项明确的能力。
• 可以被独立替换或扩展。
• 无需感知全局的业务流程，只需专注自身任务。

二、工程模板设计（企业级的关键）

清晰的项目结构是工程化的基石，它能有效分离关注点，便于团队协作和后续演进。

2.1 推荐的企业级工程结构

agent-system/
├── agent-api/              # 对外接口层
├── agent-core/             # Agent 核心抽象层
│   ├── Agent.java
│   ├── AgentContext.java
│   ├── AgentResult.java
│   └── BaseAgent.java
├── agent-graph/            # Graph 工作流引擎
│   ├── Node.java
│   ├── Edge.java
│   ├── Graph.java
│   └── GraphExecutor.java
├── agent-impl/             # 具体 Agent 实现
│   ├── AnalyzeAgent.java
│   ├── PlanAgent.java
│   ├── ExecuteAgent.java
│   └── ValidateAgent.java
└── application/            # Spring Boot 启动层

这套结构的核心价值在于职责分离：Agent ≠ Workflow ≠ Application，每层边界清晰，极大地提升了系统的可维护性和可演进性。

三、Agent 核心抽象设计

企业级应用必须建立稳定的核心抽象，这是系统健壮性的基础。

3.1 Agent 接口定义

public interface Agent {
    String name();
    AgentResult execute(AgentContext context);
}

3.2 上下文对象 (Agent 之间的“共享语言”)

public class AgentContext {
    private Map<String, Object> data = new ConcurrentHashMap<>();
    public void put(String key, Object value) {
        data.put(key, value);
    }
    public <T> T get(String key, Class<T> clazz) {
        return clazz.cast(data.get(key));
    }
}

关键点：企业级的多 Agent 协作必须依赖一个统一的 Context 对象。它是 Agent 之间传递数据和状态的媒介，没有它，协作无从谈起。

四、Graph 工作流模型（核心进阶）

为什么简单的 Pipeline 不足以应对企业场景？我们通过一个对比来揭示 Graph 工作流的优势。

Pipeline	Graph
单向线性执行	支持条件分支与动态路由
失败即中断，不可回退	支持失败重试与流程回滚
节点间强耦合	节点解耦，易于替换和测试
不适合复杂业务流程	企业级复杂流程的首选模型

4.1 Graph 节点定义

public class Node {
    private String id;
    private Agent agent;
    private List<String> nextNodes;
}

4.2 Graph 执行器（核心）

public class GraphExecutor {
    private Map<String, Node> nodeMap;
    public void execute(String startNodeId, AgentContext context) {
        Node current = nodeMap.get(startNodeId);
        while (current != null) {
            AgentResult result = current.getAgent().execute(context);
            if (!result.isSuccess()) {
                throw new RuntimeException("Agent failed: " + current.getId());
            }
            String nextId = result.nextNode();
            current = nextId == null ? null : nodeMap.get(nextId);
        }
    }
}

至此，我们已经实现了一个具备动态流转、Agent 解耦和流程可配置的基础 Graph 引擎。这为构建复杂的 Java 企业应用提供了坚实的框架基础。

五、多 Agent 协作实战示例

我们以一个 智能售后工单处理 的真实业务场景为例，演示多 Agent 如何协作。

5.1 Agent 职责拆分

Agent	职责
AnalyzeAgent	分析用户问题与意图
PlanAgent	生成具体的处理方案
ExecuteAgent	执行方案中的动作
ValidateAgent	校验执行结果

5.2 AnalyzeAgent 实现

@Component
public class AnalyzeAgent extends BaseAgent {
    @Override
    public AgentResult execute(AgentContext context) {
        String question = context.get("question", String.class);
        // 实际业务中，这里会调用 LLM 或规则引擎分析意图
        context.put("intent", "refund");
        return AgentResult.next("plan");
    }
}

5.3 PlanAgent 实现

@Component
public class PlanAgent extends BaseAgent {
    @Override
    public AgentResult execute(AgentContext context) {
        // 根据分析结果制定处理计划
        context.put("plan", "check order -> verify -> refund");
        return AgentResult.next("execute");
    }
}

5.4 ExecuteAgent 与 ValidateAgent 示意

@Override
public AgentResult execute(AgentContext context) {
    // 执行业务逻辑，如调用退款接口
    return AgentResult.next("validate");
}

六、Agent 生命周期与状态管理

在企业场景中，Agent 的执行并非总是一帆风顺。它可能失败、可能被人工干预打断、可能需要重试，甚至可能跨多个请求执行。因此，为 Agent 定义明确的生命周期和状态是生产就绪的必然要求。

6.1 Agent 生命周期模型

CREATED
  ↓
READY
  ↓
RUNNING
  ↓
SUCCESS / FAILED / INTERRUPTED

6.2 状态枚举定义

public enum AgentStatus {
    CREATED,
    READY,
    RUNNING,
    SUCCESS,
    FAILED,
    INTERRUPTED
}

6.3 增强的 Agent 执行结果

public class AgentResult {
    private boolean success;
    private String nextNode;
    private String message;
    private AgentStatus status;
    public static AgentResult success(String next) {
        return new AgentResult(true, next, "OK", AgentStatus.SUCCESS);
    }
    public static AgentResult fail(String msg) {
        return new AgentResult(false, null, msg, AgentStatus.FAILED);
    }
}

七、Graph 执行引擎增强：失败、重试与回滚

一个健壮的企业级 Graph 引擎绝不能“一败涂地”。它必须能够优雅地处理失败，并提供重试、兜底等机制。

7.1 Graph 执行上下文

public class GraphExecutionContext {
    private String currentNode;
    private Map<String, Integer> retryCount = new HashMap<>();
}

7.2 支持重试的节点执行器

public void executeNode(Node node, AgentContext context, GraphExecutionContext execCtx) {
    try {
        AgentResult result = node.getAgent().execute(context);
        execCtx.setCurrentNode(result.getNextNode());
    } catch (Exception e) {
        int retry = execCtx.getRetryCount().getOrDefault(node.getId(), 0);
        if (retry < 3) {
            execCtx.getRetryCount().put(node.getId(), retry + 1);
            executeNode(node, context, execCtx); // 重试
        } else {
            throw new RuntimeException("Node failed after retry: " + node.getId());
        }
    }
}

实现到这一步，你的系统已经从简单的“演示原型”迈入了“生产可控”的领域。

八、Graph DSL：实现流程配置化

如果业务流程的每次改动都需要修改 Spring Boot 代码、重新部署，那将严重制约业务的敏捷性。企业级系统需要做到 Graph as Config。

8.1 YAML 格式的 Graph 配置示例

graph:
  start: analyze
  nodes:
    analyze:
      agent: analyzeAgent
      next: plan
    plan:
      agent: planAgent
      next: execute
    execute:
      agent: executeAgent
      next: validate
    validate:
      agent: validateAgent

8.2 Graph 配置加载器

public class GraphLoader {
    public Graph load(InputStream yaml) {
        // 解析 YAML -> Node -> Graph
        return graph;
    }
}

通过配置化，系统实现了清晰的架构分层：流程即配置，Agent 即插件，Graph 即编排层。这种设计对于构建可扩展的 后端架构 至关重要。

九、Agent 注册与动态路由

当系统中有成百上千个 Agent 时，如何管理和查找它们？一个集中的注册中心是必不可少的。

9.1 Agent 注册表

@Component
public class AgentRegistry {
    private final Map<String, Agent> agentMap = new HashMap<>();
    @Autowired
    public AgentRegistry(List<Agent> agents) {
        agents.forEach(a -> agentMap.put(a.name(), a));
    }
    public Agent get(String name) {
        return agentMap.get(name);
    }
}

9.2 动态路由示例

public AgentResult execute(AgentContext context) {
    String intent = context.get("intent", String.class);
    if ("refund".equals(intent)) {
        return AgentResult.success("refundFlow");
    }
    return AgentResult.success("manualFlow"); // 路由到其他流程
}

核心认知：多 Agent 协作的本质是 “基于上下文的路由决策” ，而非简单的“顺序执行”。

十、可观测性：让 Agent 执行过程透明化

不可观测的系统如同黑盒，无法运维。你必须记录关键的执行痕迹。

10.1 至少需要记录的信息

• Graph ID 和 Node ID
• Agent 名称
• 执行开始与结束时间
• 执行结果状态（成功/失败）
• Input 和 Output 的关键信息（需脱敏）

10.2 执行日志示例

log.info("[Graph:{}][Node:{}][Agent:{}] status={}, cost={}ms",
        graphId, nodeId, agent.name(), result.getStatus(), cost);

这些日志可以进一步接入 Prometheus、OpenTelemetry 或 SkyWalking 等监控体系，构建完整的可观测性栈。

十一、与 Spring AI / LangChain4j 的整合定位

这里需要建立一个重要认知：Spring AI 或 LangChain4j 本身并不是企业级的 Agent 编排框架。它们在架构中的正确位置如下：

LLM / Tool (由 Spring AI/LangChain4j 提供)
   ↓
Agent (基于本文设计的能力单元)
   ↓
Graph / Workflow (本文的流程编排层)
   ↓
业务系统

你可以利用 Spring AI 来便捷地集成大模型能力，或用 LangChain4j 的工具调用，但顶层的 Agent 抽象和工作流编排，应该由你掌控的、更贴合业务的基础框架来实现。不要被任何现有框架限制了你的架构边界。

十二、企业真实落地场景

场景	Agent 与 Graph 工作流的价值体现
智能客服	多轮意图识别后，动态路由到查询、业务办理、人工交接等流程
运维诊断	分析日志 → 定位根因 → 生成修复建议 → 自动执行
风控审核	规则引擎、模型评分、人工复核等多节点协同决策
数据分析	拆解问题 → 自动查询多数据源 → 生成解读报告

总结

Agent 是封装能力的单元，Graph 是描述流程的语言，而 Spring Boot 提供了工程化的稳固底座。

本文所探讨的设计方案，其优势在于：

• 不依赖特定模型：底层大模型可替换。
• 不绑定特定框架：核心抽象自主可控。
• 可横向扩展：易于增加新的 Agent 和复杂流程。
• 可长期维护：清晰的架构分层和配置化设计。

这，才是面向生产的、真正的 Java 企业级 Agent 实战。希望这套工程思想和模板能为你在 云栈社区 的技术实践中提供有价值的参考。