第 7 章：Graph Core 入门，从黑盒助手走到白盒流程

前面几章我们一直站在 ReactAgent 这一层。现在把上层包装拿掉，看看底盘：Graph Core。你会发现，工具、记忆、Hook、多智能体，很多能力最终都离不开“节点、边、状态”这套模型。

本章边界

本章只讲最小工作流：节点做事，边决定下一步，状态贯穿全程。分布式调度、复杂持久化、Admin 可视化编排先不展开。

1. 生活类比：从开车到看导航路线

开车时你只看方向盘和油门。但导航真正关心的是：从 A 到 B，中间经过哪些路口，遇到岔路怎么选。

Graph Core 就是这张路线图：

导航概念	Graph 概念	作用
路线图	StateGraph	定义流程还没开始跑
路口	Node	执行一个步骤
路	Edge	从一个步骤走到下一个步骤
分岔路	Conditional Edge	根据状态决定下一站
车上的行李	OverAllState	在节点间传递共享信息
开始导航	CompiledGraph	编译后可执行的图

2. 最小 Graph 示例

想象一个客服邮件处理流程：读邮件、分类、草拟回复。

StateGraph graph = new StateGraph("email_workflow", keyStrategyFactory);

graph.addNode("read_email", node_async(new ReadEmailNode()));
graph.addNode("classify_intent", node_async(new ClassifyIntentNode(chatClientBuilder)));
graph.addNode("draft_response", node_async(new DraftResponseNode(chatClientBuilder)));

graph.addEdge(START, "read_email");
graph.addEdge("read_email", "classify_intent");
graph.addConditionalEdges(
        "classify_intent",
        edge_async(state -> state.value("next_node").orElse("draft_response").toString()),
        Map.of("draft_response", "draft_response", "human_review", "human_review")
);

CompiledGraph app = graph.compile();

你不用先纠结每个类。先看结构：

1. addNode(...) 定义流程中有哪些步骤。
2. addEdge(...) 定义固定顺序。
3. addConditionalEdges(...) 定义分支。
4. compile() 把路线图变成能跑的流程。

3. Graph 怎么跑

这张图说明一件事：Graph 不等于“大模型链”。节点可以是普通 Java 逻辑，可以是模型调用，可以是工具调用，也可以是人工审核。

真正让流程能跑起来的是 OverAllState。它像一张共享工作台：

read_email 写入 email_content
classify_intent 读取 email_content，写入 classification 和 next_node
条件边读取 next_node，决定下一站
draft_response 读取前面结果，生成回复

4. Graph 适合解决什么问题

场景	为什么适合 Graph
多步骤任务	每一步可以拆成节点
需要条件分支	条件边能按 state 路由
需要人工审核	可以中断、保存、恢复
需要观测每一步	节点边界天然适合日志和指标
需要复用步骤	节点可以复用或组合

如果一个任务只是“一问一答”，Graph 可能显得重；但一旦出现“先分类，再查资料，再决定是否人工审核”，Graph 就开始有价值。

5. 新手容易误解什么

误解一：Graph 只是画图。

不是。图会被编译成可执行流程，节点会真实运行，状态会真实更新。

误解二：每个节点都必须调用大模型。

不是。节点可以是普通 Java 逻辑。能不用模型稳定解决的步骤，不要硬上模型。

误解三：状态就是一个普通 Map。

它看起来像 Map，但更新策略很重要。不同字段可能要替换、追加或合并，不能一股脑 putAll。

6. 本章小结

Graph Core 的心法：

节点做事，边决定下一步，状态贯穿全程。

下一章我们让 Graph 暂停下来：等待人工输入，再恢复执行。

7. 练习题

1. 给“客服邮件处理”画一张图：读邮件、分类、查资料、人工审核、生成回复。
2. 设计每个节点会读哪些 state key、写哪些 state key。
3. 找一个你熟悉的业务流程，判断它适不适合用 Graph 表达。

课后源码索引：想验证实现时再打开

你想验证的结论	源码锚点
官方 Graph 快速示例	examples/documentation/src/main/java/com/alibaba/cloud/ai/examples/documentation/graph/QuickStartExample.java，类 QuickStartExample，方法 createEmailAgentGraph(...)、createKeyStrategyFactory()，内部节点 ReadEmailNode.apply(...)、ClassifyIntentNode.apply(...)
图如何定义和编译	spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/StateGraph.java，类 StateGraph，方法 addNode(...)、addEdge(...)、addConditionalEdges(...)、compile(...)
编译后的图如何执行	spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/CompiledGraph.java，类 CompiledGraph，方法 invoke(...)、stream(...)、graphResponseStream(...)
状态如何在节点间传递	spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/OverAllState.java，类 OverAllState，方法 value(...)、data()、updateState(...)