Spring AI Alibaba Graph Studio 入门指南：可视化Agent编排与调试平台
本文面向Java开发者，系统介绍Spring AI Alibaba Graph Studio的核心概念、安装配置、使用流程及与Graph引擎的关系，帮助你快速上手这个可视化Agent开发与调试平台。
一、Graph Studio 是什么
1.1 一句话定义
Spring AI Alibaba Graph Studio 是 Spring AI Alibaba 生态中的可视化Agent开发、调试、评估与部署平台。它提供了可视化聊天窗口，让开发者能够直观地看到Agent的推理过程与工具执行细节。
1.2 解决什么问题
在使用 Spring AI Alibaba Graph 进行Agent开发时，开发者面临一个核心痛点：工作流的执行过程是"黑盒" 。定义好节点和边之后，虽然可以通过日志观察执行情况，但无法直观地看到：
- 当前执行到哪个节点
- 状态（State）在各个节点间如何流转
- Agent的推理链和工具调用细节
- 多Agent协作时的交接过程
Graph Studio 正是为解决这个问题而生的------它将编码后的Agent工作流"可视化"，让开发者能够像调试普通程序一样调试AI Agent。
1.3 在 Spring AI Alibaba 生态中的位置
┌─────────────────────────────────────────────────────────────┐
│ Spring AI Alibaba 生态 │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Graph Core │ │ Agent │ │ Studio │ │
│ │ (状态图引擎) │ │ Framework │ │ (可视化平台) │ │
│ │ │ │ (ReactAgent) │ │ │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └─────────────────┴─────────────────┘ │
│ │ │
│ Spring Boot Starters │
│ (接入Spring生态) │
└─────────────────────────────────────────────────────────────┘Graph Studio 是构建在 Graph Core 之上的上层工具------Graph Core 提供状态图引擎（StateGraph、CompiledGraph、节点、边），Graph Studio 则提供可视化界面来观察和调试这些图的执行过程。
注：
博客：
https://blog.csdn.net/badao_liumang_qizhi
二、核心功能
2.1 可视化聊天窗口
Graph Studio 的核心功能是提供一个可视化聊天窗口。在这个窗口中，你可以与构建好的Agent进行对话，同时看到：
| 观察维度 | 说明 |
|---|---|
| 推理过程 | Agent的每一步思考（Reasoning） |
| 工具调用 | 调用了哪些工具、传入了什么参数、返回了什么结果 |
| 状态流转 | State在节点间如何变化 |
| 执行路径 | 工作流经过了哪些节点、哪些条件分支 |
2.2 在线构建Agent
Graph Studio 支持页面在线构建智能体，无需编写代码即可完成Agent的初步配置。
2.3 Dify 迁移脚手架
Graph Studio 提供了从 Dify 转化到 Spring AI Alibaba 工程的脚手架------如果你已经在 Dify 上搭建了工作流，可以通过这个工具快速迁移到 Spring AI Alibaba 的代码工程中。
2.4 AG-UI 可视化调试
Graph Studio 集成了 AG-UI 的可视化调试工具，助力把控智能体调用的全生命链路。
三、快速上手
3.1 引入依赖
Graph Studio 作为 Spring AI Alibaba 生态的一部分，可以通过 BOM 统一管理版本：
xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-bom</artifactId>
<version>1.1.2.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>然后引入 Studio 模块：
xml
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-studio</artifactId>
</dependency>3.2 配置模型
在使用 Studio 之前，需要配置一个可用的 ChatModel。以阿里云百炼（DashScope）为例：
yaml
# application.yml
spring:
ai:
dashscope:
api-key: ${AI_DASHSCOPE_API_KEY}3.3 定义一个 StateGraph
Graph Studio 需要有一个可执行的图（CompiledGraph）作为调试对象。以下是一个简化的客户评价分类系统示例：
java
@Configuration
public class WorkflowConfiguration {
@Bean
public StateGraph customerServiceGraph(ChatModel chatModel) {
ChatClient chatClient = ChatClient.builder(chatModel)
.defaultAdvisors(new SimpleLoggerAdvisor())
.build();
// 第一级分类器：正面/负面评价
QuestionClassifierNode feedbackClassifier = QuestionClassifierNode.builder()
.chatClient(chatClient)
.inputTextKey("input")
.outputKey("classifier_output")
.categories(List.of("positive feedback", "negative feedback"))
.build();
// 第二级分类器：负面评价细分
QuestionClassifierNode specificQuestionClassifier = QuestionClassifierNode.builder()
.chatClient(chatClient)
.inputTextKey("input")
.outputKey("classifier_output")
.categories(List.of("after-sale service", "transportation", "product quality", "others"))
.build();
// 状态策略
KeyStrategyFactory stateFactory = () -> {
Map<String, KeyStrategy> strategies = new HashMap<>();
strategies.put("input", new ReplaceStrategy());
strategies.put("classifier_output", new ReplaceStrategy());
strategies.put("solution", new ReplaceStrategy());
return strategies;
};
// 构建工作流
return new StateGraph("客户服务评价处理", stateFactory)
.addNode("feedback_classifier", node_async(feedbackClassifier))
.addNode("specific_question_classifier", node_async(specificQuestionClassifier))
.addNode("recorder", node_async(new RecordingNode()))
.addEdge(START, "feedback_classifier")
.addConditionalEdges("feedback_classifier",
edge_async(new FeedbackQuestionDispatcher()),
Map.of("positive", "recorder", "negative", "specific_question_classifier"))
.addConditionalEdges("specific_question_classifier",
edge_async(new SpecificQuestionDispatcher()),
Map.of("after-sale", "recorder", "transportation", "recorder",
"quality", "recorder", "others", "recorder"))
.addEdge("recorder", END);
}
}3.4 启动并访问 Studio
启动 Spring Boot 应用后，访问 Graph Studio 的 Web 界面（默认路径通常为 /studio 或根据配置的端口）。
在 Studio 界面中，你可以：
- 选择工作流：从下拉列表中选择已注册的 StateGraph
- 发起对话：在聊天窗口中输入问题
- 观察执行：实时查看Agent的推理过程、工具调用和状态流转
3.5 运行示例
Spring AI Alibaba 提供了完整的示例工程，可以直接运行体验：
bash
# 克隆示例仓库
git clone https://github.com/alibaba/spring-ai-alibaba
# 进入 graph-example 模块
cd spring-ai-alibaba-graph-example
# 运行 chatflow 示例（推荐的入门示例）
cd chatflow
mvn spring-boot:run启动后访问 Studio 界面进行对话调试。
四、Graph Studio 与 Graph Core 的关系
| 维度 | Graph Core | Graph Studio |
|---|---|---|
| 定位 | 状态图引擎（底层） | 可视化平台（上层） |
| 核心类 | StateGraph、CompiledGraph | Web UI、调试工具 |
| 使用方式 | Java 代码定义图 | 可视化界面观察/调试 |
| 主要用户 | Java 开发者 | Java 开发者 + 调试人员 |
| 依赖关系 | 被 Studio 依赖 | 依赖 Core 的图定义 |
简单理解：Graph Core 是"引擎"，Graph Studio 是"仪表盘"。你用 Core 构建工作流，用 Studio 观察和调试它的运行。
五、学习路径建议
根据 Spring AI Alibaba 示例工程的学习路径，建议按以下顺序学习：
| 阶段 | 学习内容 | 推荐示例 |
|---|---|---|
| 入门 | 理解 Graph 基本结构 | stream-node |
| 初级 | 多轮对话 + 意图识别 | chatflow |
| 初级 | 工具调用 | big-tool |
| 中级 | 并行处理 + 人类介入 | parallel-stream-node, human-node |
| 高级 | 多智能体 + 可观测性 | multiagent-openmanus, graph-observability-langfuse |
推荐从 chatflow 示例入手------它是最完整的示例，包含了所有核心概念（多轮对话、意图识别、主流程+子图配合、Session隔离）。
六、常见问题
Q: Graph Studio 和 LangGraph Studio 有什么区别？
A: LangGraph Studio 是 Python LangGraph 生态的可视化调试工具。Spring AI Alibaba Graph Studio 是 Java 生态的对应实现，与 Spring Boot 深度集成，支持 Spring 的依赖注入和配置管理。
Q: Graph Studio 需要单独安装吗？
A: 不需要。Graph Studio 作为 Spring AI Alibaba 生态的一部分，通过 Maven 依赖引入即可，无需单独安装。
Q: 可以调试没有使用 Graph Core 定义的 Agent 吗？
A: Graph Studio 主要针对使用 StateGraph 定义的工作流。对于其他类型的 Agent（如简单的 ReactAgent），Spring AI Alibaba 提供了基础的调试能力，但完整的可视化调试需要基于 Graph 定义。
参考资源：