AgentScope Java 集成 Spring AI Alibaba Workflow 完整指南

AgentScope Java 集成 Spring AI Alibaba Workflow 完整指南

结合 agentscope-ai/agentscope-java、alibaba/spring-ai-alibaba 及 java2ai 生态中 Graph Core 工作流规范，以下是可落地的集成方案，涵盖核心思路、工程配置、代码实现、最佳实践四部分，兼顾 AgentScope 智能体特性与 Spring AI 工作流的工程化能力。

一、核心集成思路

1. 能力边界划分（关键前提）

2. 集成核心逻辑

以 “AgentScope 为智能体核心 + Spring AI Alibaba 为工作流引擎” 为核心，通过三层适配实现能力融合：

二、前置工程配置

1. 依赖整合（Maven pom.xml）

需兼容 JDK 17+、Spring Boot 3.2+，核心依赖如下（版本以官方最新为准）：

<!– Spring Boot 核心（支撑 Spring AI） –>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.2.5</version>
<relativePath/>
</parent>

<dependencies>
<!– 1. Spring AI Alibaba 核心（含 Workflow + DashScope 客户端） –>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>spring-ai-alibaba-dashscope-spring-boot-starter</artifactId>
<version>0.1.0</version>
</dependency>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>spring-ai-alibaba-workflow-core</artifactId>
<version>0.1.0</version>
</dependency>

<!– 2. AgentScope Java 核心 –>
<dependency>
<groupId>io.agentscope</groupId>
<artifactId>agentscope-core</artifactId>
<version>0.1.0</version>
</dependency>
<dependency>
<groupId>io.agentscope</groupId>
<artifactId>agentscope-spring-boot-starter</artifactId>
<version>0.1.0</version> <!– 简化 Spring 集成 –>
</dependency>

<!– 3. Java2AI Graph Core（可选，标准化工作流节点） –>
<dependency>
<groupId>com.java2ai</groupId>
<artifactId>graph-core</artifactId>
<version>1.0.0</version>
</dependency>

<!– 4. 基础依赖 –>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
</dependencies>

2. 配置文件（application.yml）

统一模型密钥、工作流引擎、AgentScope 配置：

# 1. Spring AI Alibaba 配置
spring:
ai:
# 阿里云 DashScope 配置（通义千问）
dashscope:
api-key: ${DASHSCOPE_API_KEY:你的阿里云API密钥}
chat:
options:
model: qwen–turbo
temperature: 0.7
# Spring AI Workflow 配置
workflow:
executor:
thread-pool-size: 8
persistence:
enabled: true # 开启工作流持久化（可选）

# 2. AgentScope 配置（复用 Spring AI 的模型密钥）
agentscope:
core:
agent:
default-context-size: 1000 # 智能体默认上下文大小
model:
dashscope:
api-key: ${spring.ai.dashscope.api–key}
model-name: ${spring.ai.dashscope.chat.options.model}
spring:
integration:
enabled: true # 开启 AgentScope 与 Spring 集成

# 3. Java2AI Graph Core 配置（可选）
java2ai:
graph:
core:
node-package: com.yourpackage.agent.workflow.node # 工作流节点扫描包

三、核心代码实现

步骤 1：定义 Spring AI Alibaba Workflow 模板

参考 Java2AI Graph Core 节点规范，定义标准化的 AI 工作流（以医疗场景“病历分析”为例）：

package com.yourpackage.workflow;

import com.alibaba.spring.ai.workflow.annotation.Workflow;
import com.alibaba.spring.ai.workflow.annotation.WorkflowNode;
import com.alibaba.spring.ai.workflow.executor.WorkflowContext;
import org.springframework.ai.dashscope.DashScopeChatClient;
import org.springframework.stereotype.Component;

/**
* 基于 Spring AI Alibaba 定义的病历分析工作流
* 节点1：提取病历关键信息 → 节点2：校验数据完整性 → 节点3：生成分析报告
*/
@Workflow(name = "medical-record-analysis", description = "医疗病历分析工作流")
@Component
public class MedicalRecordAnalysisWorkflow {

private final DashScopeChatClient dashScopeChatClient;

public MedicalRecordAnalysisWorkflow(DashScopeChatClient dashScopeChatClient) {
this.dashScopeChatClient = dashScopeChatClient;
}

/**
* 节点1：提取病历关键信息（大模型调用）
*/
@WorkflowNode(name = "extract-info", order = 1, requiredParams = "medicalRecord")
public String extractMedicalInfo(WorkflowContext context) {
String medicalRecord = context.getParam("medicalRecord", String.class);
String prompt = """
提取以下病历的关键信息（患者姓名、症状、检查结果、诊断结论）：
%s
要求：结构化输出，简洁明了
""".formatted(medicalRecord);

// 调用 Spring AI Alibaba 的 DashScope 客户端
return dashScopeChatClient.call(prompt).getResult().getOutput().getContent();
}

/**
* 节点2：校验数据完整性（工具调用）
*/
@WorkflowNode(name = "validate-data", order = 2, dependOn = "extract-info")
public String validateData(WorkflowContext context) {
String extractedInfo = context.getResult("extract-info", String.class);
// 自定义校验逻辑（可复用 AgentScope 工具）
boolean isComplete = extractedInfo.contains("检查结果") && extractedInfo.contains("诊断结论");
return isComplete ? "数据完整" : "缺少检查结果/诊断结论，数据不完整";
}

/**
* 节点3：生成分析报告（结果聚合）
*/
@WorkflowNode(name = "generate-report", order = 3, dependOn = "validate-data")
public String generateReport(WorkflowContext context) {
String extractedInfo = context.getResult("extract-info", String.class);
String validateResult = context.getResult("validate-data", String.class);

String prompt = """
基于以下信息生成医疗分析报告：
1. 提取的病历信息：%s
2. 数据校验结果：%s
要求：专业、简洁，符合医疗规范
""".formatted(extractedInfo, validateResult);

return dashScopeChatClient.call(prompt).getResult().getOutput().getContent();
}
}

步骤 2：封装 Workflow 为 AgentScope 工具

将 Spring AI Workflow 封装为 AgentScope 可调用的“工具”，符合 AgentScope 工具规范：

package com.yourpackage.agent.tool;

import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;
import com.alibaba.spring.ai.workflow.executor.WorkflowExecutor;
import com.alibaba.spring.ai.workflow.model.WorkflowExecutionResult;
import org.springframework.stereotype.Component;

/**
* AgentScope 工具：调用 Spring AI Alibaba Workflow
*/
@Component
@Tool(name = "medical_record_workflow_tool", description = "执行医疗病历分析工作流")
public class MedicalRecordWorkflowTool {

private final WorkflowExecutor workflowExecutor;

public MedicalRecordWorkflowTool(WorkflowExecutor workflowExecutor) {
this.workflowExecutor = workflowExecutor;
}

/**
* 工具执行方法（AgentScope 调用入口）
* @param medicalRecord 病历文本
* @return 工作流执行结果（分析报告）
*/
public String execute(
@ToolParam(name = "medicalRecord", description = "待分析的病历文本", required = true)
String medicalRecord
) {
// 执行 Spring AI Workflow
WorkflowExecutionResult result = workflowExecutor.execute(
"medical-record-analysis", // 工作流名称
param -> param.put("medicalRecord", medicalRecord)
);

// 返回最终节点结果
return result.getNodeResult("generate-report", String.class);
}
}

步骤 3：AgentScope 智能体集成 Workflow 工具

创建 ReAct 智能体，将 Workflow 工具注册到 Agent 中，实现“智能体决策 + 工作流执行”：

package com.yourpackage.agent;

import io.agentscope.core.agent.ReActAgent;
import io.agentscope.core.model.dashscope.DashScopeChatModel;
import io.agentscope.core.tool.Toolkit;
import io.agentscope.spring.annotation.Agent;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;

/**
* AgentScope 智能体：集成 Spring AI Workflow 工具
*/
@Agent
public class MedicalAnalysisAgent {

@Autowired
private MedicalRecordWorkflowTool medicalRecordWorkflowTool;

@Autowired
private DashScopeChatModel dashScopeChatModel;

/**
* 创建 ReAct 智能体（核心）
*/
@Bean
public ReActAgent createMedicalAnalysisAgent() {
// 1. 初始化工具包，注册 Workflow 工具
Toolkit toolkit = Toolkit.createDefault();
toolkit.registration()
.tool(medicalRecordWorkflowTool::execute)
.group("workflow_tools")
.apply();

// 2. 构建 ReAct 智能体
return ReActAgent.builder()
.id("medical-analysis-agent")
.name("MedicalAnalysisAgent")
.model(dashScopeChatModel) // 复用 Spring AI 的 DashScope 模型
.toolkit(toolkit) // 注册 Workflow 工具
.sysPrompt("""
你是医疗病历分析智能体，用户输入病历文本后，必须调用「medical_record_workflow_tool」工具执行分析，
并返回最终的分析报告，禁止直接生成结果。
""")
.build();
}
}

步骤 4：业务入口（API 调用示例）

通过 Spring Boot Web 暴露接口，实现“前端调用 → Agent 决策 → Workflow 执行 → 结果返回”：

package com.yourpackage.controller;

import io.agentscope.core.agent.ReActAgent;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
* 业务入口：病历分析接口
*/
@RestController
@RequestMapping("/api/agent")
public class MedicalAgentController {

private final ReActAgent medicalAnalysisAgent;

public MedicalAgentController(ReActAgent medicalAnalysisAgent) {
this.medicalAnalysisAgent = medicalAnalysisAgent;
}

/**
* 智能体 + 工作流 执行接口
*/
@PostMapping("/analyze-medical-record")
public ResponseEntity<String> analyzeMedicalRecord(@RequestBody String medicalRecord) {
// 1. 智能体处理用户请求（自动决策调用 Workflow 工具）
String response = medicalAnalysisAgent.chat("分析以下病历：" + medicalRecord).getTextContent();

// 2. 返回结果
return ResponseEntity.ok(response);
}
}

四、关键适配与最佳实践

1. 异步模型对齐（核心）

AgentScope 基于 Reactor 异步编程，Spring AI Workflow 支持 CompletableFuture，需统一异步模型：

// 改造 Workflow 工具为异步执行
public CompletableFuture<String> executeAsync(String medicalRecord) {
return CompletableFuture.supplyAsync(() -> {
WorkflowExecutionResult result = workflowExecutor.execute(
"medical-record-analysis",
param -> param.put("medicalRecord", medicalRecord)
);
return result.getNodeResult("generate-report", String.class);
});
}

// AgentScope 智能体调用异步工具
toolkit.registration()
.tool(medicalRecordWorkflowTool::executeAsync)
.async(true) // 标记为异步工具
.apply();

2. 上下文数据互通

实现 AgentScope 智能体上下文与 Spring AI Workflow 上下文的双向同步：

// Workflow 工具中注入 Agent 上下文
public String execute(String medicalRecord, @RequestAttribute("agentContext") Map<String, Object> agentContext) {
WorkflowExecutionResult result = workflowExecutor.execute(
"medical-record-analysis",
param -> {
param.put("medicalRecord", medicalRecord);
param.put("agentContext", agentContext); // 传递 Agent 上下文
}
);

// 将 Workflow 结果同步回 Agent 上下文
agentContext.put("workflowResult", result.getNodeResult("generate-report", String.class));
return result.getNodeResult("generate-report", String.class);
}

3. 异常处理兜底

为 Workflow 执行添加异常捕获，确保 Agent 稳定性：

public String execute(String medicalRecord) {
try {
WorkflowExecutionResult result = workflowExecutor.execute(
"medical-record-analysis",
param -> param.put("medicalRecord", medicalRecord)
);
return result.getNodeResult("generate-report", String.class);
} catch (Exception e) {
// 兜底逻辑：AgentScope 智能体降级处理
return "病历分析失败：" + e.getMessage() + "，已触发人工审核流程";
}
}

4. 可观测性集成

复用 Spring Boot Actuator 监控 Workflow 与 Agent 状态：

# application.yml 新增
management:
endpoints:
web:
exposure:
include: health, metrics, workflows, agents
metrics:
enable: true
endpoint:
workflows:
enabled: true # 暴露 Workflow 执行指标
agents:
enabled: true # 暴露 AgentScope 智能体指标

五、总结

核心集成要点

关键参考资源

• AgentScope Java 工具开发：https://github.com/agentscope-ai/agentscope-java/blob/main/docs/zh/tool/tool.md
• Spring AI Alibaba Workflow：https://github.com/alibaba/spring-ai-alibaba/tree/main/spring-ai-alibaba-workflow
• Java2AI Graph Core 节点规范：https://java2ai.com/docs/frameworks/graph-core/node-definition/