本文介绍 Spring AI Alibaba 的 Graph Workflow 图工作流机制，通过 State、Node、Edge 三大组件实现复杂 AI 任务的多步骤编排。内容涵盖状态管理策略 KeyStrategy 的作用与内置类型，对比了普通边、条件边与并行边的路由逻辑，并提供了智能客服路由实战案例。此外，还分析了 Graph Workflow 与 ReactAgent 的关系及适用场景，支持通过代码导出可视化图表，适用于需要自定义流程、多 Agent 协作及状态持久化的工程化落地场景。
Graph Workflow（图工作流） 是一种基于有向图（DAG）的流程编排机制。
说到工作流，很多人第一反应会是：都叫'图'了，那不就是可视化拖拽拼装吗？这里先明确一点：Spring AI Alibaba 的 Graph Workflow 并不是可视化拖拽平台。它和 n8n、Zapier、飞书多维表格自动化这类低代码工具，定位完全不同。
| 特性 | 可视化拖拽平台 | Spring AI Graph Workflow |
|---|---|---|
| 定义方式 | 🖱️ UI 拖拽 | 💻 Java 代码 |
| 适用人群 | 业务人员、零代码用户 | 开发者 |
| 灵活性 | 受平台能力限制 | 完全可编程，自由度拉满 |
| 调试 | 平台日志查看 | 代码级调试 |
| 版本控制 | 平台内管理 | Git 友好 |
| 可视化 | ✅ 原生支持 | ✅ 可导出 Mermaid/PlantUML 图 |
二者在底层逻辑上其实是相通的，本质都是有向图（DAG），都由节点（Node）和边（Edge）构成，支持条件分支、循环逻辑，也都会管理任务的状态流转。
但它们的设计思路截然不同：Spring AI Graph 没有提供拖拽式 UI，也不主打零代码，而是以代码为核心，更适合复杂 AI 应用的工程化落地。同时它又保留了可视化能力，能通过代码直接生成流程图，在可编程性与可读性之间做到了很好的平衡。
State 是什么？
Map<String, Object>// State 示例
Map<String, Object> state = Map.of(
"user_query", "北京今天天气怎么样？",
"intent", "weather_query",
"result", "北京今天晴，15°C",
"messages", List.of("msg1", "msg2")
);
Node 是什么？
// Node 的本质
// State → Node → State
// 实现一个 Node
public class WeatherNode implements NodeAction {
@Override
public Map<String, Object> apply(OverAllState state) throws Exception {
// 1. 读取 State
String city = (String) state.value("city").orElse("北京");
// 2. 执行业务逻辑
String weather = getWeather(city);
// 3. 返回新的 State
return Map.of("weather", weather);
}
}
Edge 是什么？
// 普通边：固定路由
workflow.addEdge("nodeA", "nodeB");
// 条件边：动态路由
workflow.addConditionalEdges("classifier", edge_async(state -> {
String intent = (String) state.value("intent").orElse("default");
return intent; // 返回下一个节点名称
}), Map.of(
"weather", "weather_node",
"news", "news_node",
"default", "default_node"
));
// 1. 定义 KeyStrategyFactory（状态更新策略）
KeyStrategyFactory keyStrategyFactory = () -> {
Map<String, KeyStrategy> strategies = new HashMap<>();
strategies.put("messages", new AppendStrategy()); // 追加
strategies.put("result", new ReplaceStrategy()); // 替换
return strategies;
};
// 2. 创建 StateGraph
StateGraph workflow = new StateGraph(keyStrategyFactory);
// 3. 添加节点
workflow.addNode("nodeA", node_async(new NodeA()));
workflow.addNode("nodeB", node_async(new NodeB()));
// 4. 添加边
workflow.addEdge(START, "nodeA");
workflow.addEdge("nodeA", "nodeB");
workflow.addEdge("nodeB", END);
// 5. 编译
CompiledGraph compiled = workflow.compile();
// 6. 执行
Map<String, Object> initialState = Map.of("input", "Hello");
OverAllState result = compiled.invoke(initialState, config).orElseThrow();
public class CustomerServiceGraph {
// 节点 1: 意图分类
public static class ClassifyNode implements NodeAction {
private final ChatClient chatClient;
@Override
public Map<String, Object> apply(OverAllState state) {
String query = (String) state.value("user_query").orElse("");
String prompt = String.format("""
分类用户意图（只返回类别）：
- technical: 技术问题
- billing: 账单问题
- general: 一般咨询
用户问题：%s
""", query);
String intent = chatClient.prompt()
.user(prompt)
.call()
.content()
.trim()
.toLowerCase();
return Map.of("intent", intent);
}
}
// 节点 2: 技术支持
public static class TechnicalSupportNode implements NodeAction {
@Override
public Map<String, Object> apply(OverAllState state) {
String query = (String) state.value("user_query").orElse();
searchTechDocs(query);
Map.of(, answer);
}
}
{
Map<String, Object> {
(String) state.value().orElse();
queryBillingSystem(query);
Map.of(, answer);
}
}
CompiledGraph {
ChatClient. ChatClient.builder(chatModel);
() -> {
Map<String, KeyStrategy> strategies = <>();
strategies.put(, ());
strategies.put(, ());
strategies.put(, ());
strategies;
};
(factory)
.addNode(, node_async( (builder.build())))
.addNode(, node_async( ()))
.addNode(, node_async( ()))
.addNode(, node_async( ()));
workflow.addEdge(START, );
workflow.addConditionalEdges(, edge_async(state -> (String) state.value().orElse()), Map.of(
, ,
, ,
,
));
workflow.addEdge(, END);
workflow.addEdge(, END);
workflow.addEdge(, END);
workflow.compile();
}
{
createGraph(chatModel);
Map<String, Object> initialState = Map.of(
,
);
RunnableConfig.builder()
.threadId()
.build();
graph.stream(initialState, config)
.doOnNext(output -> {
System.out.println( + output.node());
System.out.println( + output.state().data());
})
.blockLast();
}
}
KeyStrategy（键策略） 是 Graph Workflow 中用于控制状态更新行为的核心机制。
// KeyStrategy 的本质是一个函数
public interface KeyStrategy {
Object apply(Object oldValue, Object newValue);
}
作用：当节点返回新的状态数据时，KeyStrategy 决定如何将新值与旧值合并。
KeyStrategyFactory 是一个工厂接口，用于为 State 中的每个键指定更新策略。
public interface KeyStrategyFactory {
Map<String, KeyStrategy> getStrategies();
}
// 使用示例
KeyStrategyFactory factory = () -> {
Map<String, KeyStrategy> strategies = new HashMap<>();
strategies.put("messages", new AppendStrategy()); // messages 使用追加策略
strategies.put("result", new ReplaceStrategy()); // result 使用替换策略
strategies.put("counter", new CustomStrategy()); // counter 使用自定义策略
return strategies;
};
问题场景：当多个节点修改同一个 State 键时，如何合并？
KeyStrategy 就是用来解决这个问题的！
用途：直接用新值替换旧值（最常用）
strategies.put("result", new ReplaceStrategy());
// 行为示例：
// oldValue: "old result"
// newValue: "new result"
// 返回："new result" ← 直接替换
// 适用场景：
// - 单一结果值（result、answer、status）
// - 配置项（config、settings）
// - 标识符（id、type、intent）
用途：将新值追加到列表中
strategies.put("messages", new AppendStrategy());
// 行为示例：
// oldValue: ["msg1", "msg2"]
// newValue: "msg3"
// 返回：["msg1", "msg2", "msg3"] ← 追加到列表
// 如果 oldValue 不是列表：
// oldValue: "msg1"
// newValue: "msg2"
// 返回：["msg1", "msg2"] ← 自动转换为列表
// 适用场景：
// - 消息历史（messages、history）
// - 日志记录（logs、events）
// - 收集结果（results、findings）
用途：实现自己的合并逻辑
// 示例 1: 累加策略（数值累加）
strategies.put("counter", (oldValue, newValue) -> {
int old = oldValue != null ? (int) oldValue : 0;
int add = (int) newValue;
return old + add;
});
// 使用：
// oldValue: 5
// newValue: 3
// 返回：8
// 示例 2: Map 合并策略
strategies.put("metadata", (oldValue, newValue) -> {
Map<String, Object> old = (Map<String, Object>) oldValue;
Map<String, Object> newMap = (Map<String, Object>) newValue;
Map<String, Object> merged = new HashMap<>(old);
merged.putAll(newMap); // 新值覆盖旧值
return merged;
});
// 使用：
// oldValue: {"key1": "value1", "key2": "value2"}
// newValue: {"key2": "new_value2", "key3": "value3"}
// 返回：{"key1": "value1", "key2": "new_value2", "key3": "value3"}
// 示例 3: 去重追加策略
strategies.put("tags", (oldValue, newValue) -> {
Set<String> tags = new HashSet<>((List<String>) oldValue);
tags.add((String) newValue);
return new ArrayList<>(tags);
});
public class MyKeyStrategyFactory implements KeyStrategyFactory {
@Override
public Map<String, KeyStrategy> getStrategies() {
Map<String, KeyStrategy> strategies = new HashMap<>();
// 1. 单一值使用替换策略
strategies.put("user_query", new ReplaceStrategy());
strategies.put("intent", new ReplaceStrategy());
strategies.put("result", new ReplaceStrategy());
strategies.put("status", new ReplaceStrategy());
// 2. 列表使用追加策略
strategies.put("messages", new AppendStrategy());
strategies.put("history", new AppendStrategy());
strategies.put("logs", new AppendStrategy());
// 3. 数值使用累加策略
strategies.put("token_count", (oldValue, newValue) -> {
int old = oldValue != null ? (int) oldValue : 0;
return old + (int) newValue;
});
// 4. Map 使用合并策略
strategies.put("metadata", (oldValue, newValue) -> {
if (oldValue == ) newValue;
Map<String, Object> merged = <>((Map) oldValue);
merged.putAll((Map) newValue);
merged;
});
strategies;
}
}
( ());
KeyStrategyFactory factory = () -> {
Map<String, KeyStrategy> strategies = new HashMap<>();
// 1. 明确每个键的用途
strategies.put("user_input", new ReplaceStrategy()); // 用户输入
strategies.put("conversation", new AppendStrategy()); // 对话历史
strategies.put("final_answer", new ReplaceStrategy()); // 最终答案
// 2. 为所有可能的键都定义策略
strategies.put("error", new ReplaceStrategy());
strategies.put("metadata", new ReplaceStrategy());
return strategies;
};
KeyStrategyFactory factory = () -> {
Map<String, KeyStrategy> strategies = new HashMap<>();
// ❌ 只定义部分键（其他键会使用默认策略，可能导致意外行为）
strategies.put("messages", new AppendStrategy());
// ❌ 策略选择不当
strategies.put("result", new AppendStrategy()); // result 应该用 ReplaceStrategy
return strategies;
};
如果某个键没有定义 KeyStrategy，会怎样？
// 默认行为：使用 ReplaceStrategy
// 即：新值直接替换旧值
建议：为所有可能出现的键都显式定义策略，避免依赖默认行为。
// 单个边
workflow.addEdge("nodeA", "nodeB");
// 从 START 到节点
workflow.addEdge(START, "nodeA");
// 从节点到 END
workflow.addEdge("nodeZ", END);
workflow.addConditionalEdges(
"classifier", // 源节点
edge_async(state -> {
// 条件函数
String type = (String) state.value("type").orElse("default");
// 根据 State 决定下一个节点
if ("urgent".equals(type)) {
return "urgent_handler";
} else if ("normal".equals(type)) {
return "normal_handler";
} else {
return "default_handler";
}
}),
Map.of(
// 路由映射
"urgent_handler", "urgent_handler",
"normal_handler", "normal_handler",
"default_handler", "default_handler"
)
);
// A 完成后，B1/B2/B3 并行执行
workflow.addEdge("A", List.of("B1", "B2", "B3"));
// B1/B2/B3 都完成后，执行 C
workflow.addEdge(List.of("B1", "B2", "B3"), "C");
虽然 Graph Workflow 是代码定义的，但可以导出为可视化图表！
// 导出为 Mermaid 图
GraphRepresentation mermaid = workflow.getGraph(
GraphRepresentation.Type.MERMAID,
"Customer Service Workflow"
);
System.out.println(mermaid.getContent());
// 输出：
// graph TD
// __START__ --> classify
// classify --> technical
// classify --> billing
// classify --> general
// technical --> __END__
// billing --> __END__
// general --> __END__
将输出的 Mermaid 代码粘贴到支持 Mermaid 的平台（如 GitHub、Notion），即可看到可视化图表！
ReactAgent 本质上就是一个预定义的 StateGraph！
// ReactAgent 内部实际上是这样的 Graph：
StateGraph reactGraph = new StateGraph()
.addNode("llm_node", llmNode) // 调用 LLM
.addNode("tool_node", toolNode) // 执行工具
.addEdge(START, "llm_node")
.addConditionalEdges("llm_node", edge_async(state -> {
// 如果需要调用工具，路由到 tool_node
// 否则结束
return needsTools(state) ? "tool_node" : END;
}), Map.of("tool_node", "tool_node", END, END))
.addEdge("tool_node", "llm_node"); // 工具执行后回到 LLM
| 场景 | 使用 | 原因 |
|---|---|---|
| 标准的 ReAct 循环 | ReactAgent | 开箱即用 |
| 自定义复杂流程 | StateGraph | 完全控制 |
| 多个 Agent 协作 | StateGraph | 灵活编排 |
| 需要人工介入 | StateGraph | 支持中断点 |
| 并行执行任务 | StateGraph | 支持并行边 |
| 特性 | Graph Workflow | ReactAgent |
|---|---|---|
| 核心能力 | 自定义流程编排 | 标准 ReAct 循环 |
| 适用场景 | 复杂流程、多 Agent 协作 | 标准工具调用 |
| 可组合性 | ✅ ReactAgent 基于它实现 | ✅ 可以作为 Graph 的节点 |
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online