AgentScopeJava集成SpringAIAlibabaWorkflow完整指南

结合 agentscope-ai/agentscope-ja va、alibaba/spring-ai-alibaba 及 ja va2ai 生态中 Graph Core 工作流规范，我们梳理出一套可直接落地的集成方案。这套方案覆盖了从核心思路到工程实践的完整链路，旨在充分发挥 AgentScope 的智能体特性与 Spring AI 工作流的编排能力。

一、核心集成思路

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

2. 集成核心逻辑

整个集成的核心逻辑可以概括为：以 AgentScope 为智能体核心，以 Spring AI Alibaba 为工作流引擎。具体实现则需要通过三层适配来完成能力融合：

1. 模型层复用：让 AgentScope 直接复用 Spring AI Alibaba 的 DashScope 客户端，统一大模型调用入口，避免重复配置；
2. 工作流层封装：将 Spring AI Alibaba Workflow 封装成 AgentScope 能够识别和调用的“工具”或“服务”；
3. 执行层适配：对齐异步模型（Reactor/CompletableFuture）、生命周期（Spring/AgentScope）以及上下文数据的格式，确保流程顺畅。

二、前置工程配置

1. 依赖整合（Ma ven pom.xml）

项目需要兼容 JDK 17+ 和 Spring Boot 3.2+。以下是核心依赖配置，版本请以官方最新为准：

    org.springframework.boot
    spring-boot-starter-parent
    3.2.5
    


    
    
        com.alibaba
        spring-ai-alibaba-dashscope-spring-boot-starter
        0.1.0
    
    
        com.alibaba
        spring-ai-alibaba-workflow-core
        0.1.0
    
    
    
        io.agentscope
        agentscope-core
        0.1.0
    
    
        io.agentscope
        agentscope-spring-boot-starter
        0.1.0 
    
    
    
        com.ja va2ai
        graph-core
        1.0.0
    
    
    
        org.springframework.boot
        spring-boot-starter-web
    
    
        org.springframework.boot
        spring-boot-starter-validation
    

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. Ja va2AI Graph Core 配置（可选）
ja va2ai:
  graph:
    core:
      node-package: com.yourpackage.agent.workflow.node # 工作流节点扫描包

三、核心代码实现

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

首先，参考 Ja va2AI 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 工具

定义好工作流之后，下一步就是将其封装成 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 工具注册进去，从而实现“智能体决策，工作流执行”的协作模式：

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 层暴露一个接口，打通从用户请求到智能体响应的完整链路：

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 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 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. 上下文数据互通

智能体的上下文和工作流的上下文需要打通，这样才能实现状态共享和数据传递：

// Workflow 工具中注入 Agent 上下文
public String execute(String medicalRecord, @RequestAttribute("agentContext") Map 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 执行添加异常捕获，是保障智能体稳定性的必要措施：

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 智能体指标

五、总结

核心集成要点

1. 依赖层：复用 Spring AI Alibaba 的 DashScope 客户端是关键，避免了模型密钥的重复配置；
2. 工具层：将 Spring AI Workflow 封装为 AgentScope 的标准工具，这是智能体调用工作流的桥梁；
3. 执行层：对齐异步模型、上下文数据和异常处理机制，是确保二者稳定协同的技术保障；
4. 工程层：充分利用 Spring 生态已有的可观测性、持久化和微服务能力，能显著降低后续的运维成本。

关键参考资源

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