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

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

一、核心集成思路

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

框架/组件	核心职责
agentscope java	智能体（agent）生命周期管理、多智能体协作、工具调用、上下文（context）管理
spring ai alibaba	阿里云大模型（通义千问/百炼）标准化调用、workflow 声明式编排、spring 生态适配
java2ai graph core	工作流节点标准化定义、执行引擎适配、可视化编排规范（参考）

2. 集成核心逻辑

以 “agentscope 为智能体核心 + spring ai alibaba 为工作流引擎” 为核心，通过三层适配实现能力融合：

模型层复用：agentscope 复用 spring ai alibaba 的 dashscope 客户端，统一大模型调用；
工作流层封装：将 spring ai alibaba workflow 封装为 agentscope 可调用的“工具/服务”；
执行层适配：对齐异步模型（reactor/completablefuture）、生命周期（spring/agentscope）、上下文数据格式。

二、前置工程配置

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

五、总结

核心集成要点

依赖层：复用 spring ai alibaba 的 dashscope 客户端，避免重复配置模型密钥；
工具层：将 spring ai workflow 封装为 agentscope 标准工具，符合智能体调用规范；
执行层：对齐异步模型、上下文数据、异常处理，确保二者协同稳定；
工程层：复用 spring 生态的可观测性、持久化、微服务能力，降低运维成本。

关键参考资源

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/

到此这篇关于agentscope java 集成 spring ai alibaba workflow 完整指南的文章就介绍到这了,更多相关agentscope java 集成 spring ai alibaba workflow内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！

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

2026年04月21日 • Java •我要评论