AgentScope Java 入门到进阶指南_Java

一、什么是 agentscope java？

agentscope java 是一个面向智能体的编程框架，用于构建基于大语言模型(llm)的应用。它提供了构建智能体所需的一切功能：react 推理、工具调用、记忆管理、多智能体协作等，让你能够快速开发生产级的 ai 智能体应用。

二、环境准备

1. 系统要求

jdk 17 或更高版本
maven 或 gradle 构建工具

2. 添加依赖

在你的 pom.xml 中添加以下依赖：

<dependency>
    <groupid>io.agentscope</groupid>
    <artifactid>agentscope</artifactid>
    <version>1.0.1</version>
</dependency>

三、快速入门：创建第一个智能体

1. 最简单的智能体示例

下面是一个基础的智能体示例，它可以响应用户的问候：

import io.agentscope.core.reactagent;
import io.agentscope.core.message.msg;
import io.agentscope.core.model.dashscopechatmodel;
public class firstagentexample {
    public static void main(string[] args) {
        // 获取api密钥（实际开发中建议使用环境变量）
        string apikey = system.getenv("dashscope_api_key");
        // 创建智能体
        reactagent agent = reactagent.builder()
            .name("myfirstagent")
            .sysprompt("你是一个友好的ai助手，总是用简洁的语言回答问题。")
            .model(dashscopechatmodel.builder()
                .apikey(apikey)
                .modelname("qwen-plus")
                .build())
            .build();
            // 发送消息并获取响应
        msg usermessage = msg.builder()
                .name("user")  // 设置发送者名称
                .role(msgrole.user)  // 指定角色为用户
                .content(textblock.builder()
                        .text("你好，我叫小明，很高兴认识你！")  // 设置消息内容
                        .build())
                .build();    
        // 发送消息并获取响应
        msg response = agent.call(usermessage).block();
        // 输出响应
        assert response != null;
        system.out.println("智能体回复：" + response.gettextcontent());
    }
}

2. 代码解释

reactagent.builder()：使用建造者模式创建智能体
name()：设置智能体名称
sysprompt()：设置系统提示，定义智能体的角色和行为
model()：配置底层llm模型，这里使用了阿里云的dashscope服务
agent.call()：发送消息给智能体并获取响应

四、基础功能：智能体与工具

1. 创建自定义工具

工具是智能体与外部世界交互的桥梁。下面创建一个简单的计算器工具：

import io.agentscope.core.tool.tool;
import io.agentscope.core.tool.toolparam;
import reactor.core.publisher.mono;
public class calculatortool {
    @tool(name = "calculator", description = "进行数学计算，支持加减乘除")
    public mono<string> calculate(
        @toolparam(name = "expression", description = "数学表达式，如1+2*3") string expression
    ) {
        try {
            // 简单的表达式计算逻辑
            double result = evaluateexpression(expression);
            return mono.just(expression + " = " + result);
        } catch (exception e) {
            return mono.just("计算错误: " + e.getmessage());
        }
    }
    private double evaluateexpression(string expr) {
        // 实际项目中可以使用更完善的表达式解析库
        expr = expr.replaceall("\\s+", "");
        // 简化实现，仅处理加减乘除
        // ... 实现计算逻辑 ...
        return 0; // 实际计算结果
    }
}

2. 在智能体中使用工具

import io.agentscope.core.reactagent;
import io.agentscope.core.tool.toolkit;
public class agentwithtoolexample {
    public static void main(string[] args) {
        string apikey = system.getenv("dashscope_api_key");
        // 创建工具集并注册工具
        toolkit toolkit = new toolkit();
        toolkit.registertool(new calculatortool());
        // 创建带工具的智能体
        reactagent agent = reactagent.builder()
            .name("calculatoragent")
            .sysprompt("你是一个计算器助手，当需要进行数学计算时，使用calculator工具。")
            .model(dashscopechatmodel.builder()
                .apikey(apikey)
                .modelname("qwen-plus")
                .build())
            .toolkit(toolkit) // 配置工具集
            .build();
       msg usermessage = msg.builder()
                .name("user")  // 设置发送者名称
                .role(msgrole.user)  // 指定角色为用户
                .content(textblock.builder()
                        .text("请计算：(25 + 75) * 3 / 2")  // 设置消息内容
                        .build())
                .build();
        // 测试计算功能
        msg response = agent.call(usermessage).block();
        assert response != null;
        system.out.println("计算结果：" + response.gettextcontent());
    }
}

五、进阶功能：多智能体协作

1. 顺序管道（sequential pipeline）

顺序管道让多个智能体按顺序处理任务，前一个智能体的输出作为后一个的输入：

import io.agentscope.core.pipeline.sequentialpipeline;
import io.agentscope.core.reactagent;
import io.agentscope.core.message.msg;
public class sequentialpipelineexample {
    public static void main(string[] args) {
        string apikey = system.getenv("dashscope_api_key");
        // 创建三个不同功能的智能体
        reactagent translator = createtranslator(apikey);
        reactagent summarizer = createsummarizer(apikey);
        reactagent sentimentanalyzer = createsentimentanalyzer(apikey);
        // 构建顺序管道
        sequentialpipeline pipeline = sequentialpipeline.builder()
            .addagent(translator)
            .addagent(summarizer)
            .addagent(sentimentanalyzer)
            .build();
        // 输入文本
        string inputtext = "artificial intelligence has revolutionized the technology industry...";
        msg usermessage = msg.builder()
        .name("user")  // 设置发送者名称
        .role(msgrole.user)  // 指定角色为用户
        .content(textblock.builder()
                .text(inputtext)  // 设置消息内容
                .build())
        .build();
        // 执行管道
        msg result = pipeline.execute(usermessage).block();
        // 输出最终结果
        system.out.println("最终分析结果：" + result.gettextcontent());
    }
    // 创建翻译智能体
    private static reactagent createtranslator(string apikey) {
        return reactagent.builder()
            .name("translator")
            .sysprompt("将输入的英文文本准确翻译成中文，只输出翻译结果。")
            .model(dashscopechatmodel.builder()
                .apikey(apikey)
                .modelname("qwen-plus")
                .build())
            .build();
    }
    // 创建摘要智能体
    private static reactagent createsummarizer(string apikey) {
        return reactagent.builder()
            .name("summarizer")
            .sysprompt("将输入文本总结为2-3句话，保留核心信息。")
            .model(dashscopechatmodel.builder()
                .apikey(apikey)
                .modelname("qwen-plus")
                .build())
            .build();
    }
    // 创建情感分析智能体
    private static reactagent createsentimentanalyzer(string apikey) {
        return reactagent.builder()
            .name("sentimentanalyzer")
            .sysprompt("分析输入文本的情感倾向，分为积极、消极、中性或混合。")
            .model(dashscopechatmodel.builder()
                .apikey(apikey)
                .modelname("qwen-plus")
                .build())
            .build();
    }
}

2. 并行管道（fanout pipeline）

并行管道让多个智能体同时处理同一输入，适用于需要多视角分析的场景：

import io.agentscope.core.pipeline.fanoutpipeline;
import io.agentscope.core.reactagent;
import io.agentscope.core.message.msg;
import java.util.list;
public class fanoutpipelineexample {
    public static void main(string[] args) {
        string apikey = system.getenv("dashscope_api_key");
        // 创建三个专家智能体
        reactagent techexpert = createtechexpert(apikey);
        reactagent uxexpert = createuxexpert(apikey);
        reactagent bizanalyst = createbusinessanalyst(apikey);
        // 构建并行管道
        fanoutpipeline pipeline = fanoutpipeline.builder()
            .addagent(techexpert)
            .addagent(uxexpert)
            .addagent(bizanalyst)
            .concurrent() // 并行执行
            .build();
        // 产品创意
        string productidea = "一个使用ai分析日常照片并自动生成个性化视频日记的移动应用...";
        msg usermessage = msg.builder()
                .name("user")  // 设置发送者名称
                .role(msgrole.user)  // 指定角色为用户
                .content(textblock.builder()
                        .text(productidea)  // 设置消息内容
                        .build())
                .build();
        // 执行管道
        list<msg> results = pipeline.execute(usermessage).block();
        // 输出结果
        for (msg result : results) {
            system.out.println("=== " + result.getname() + " 分析 ===");
            system.out.println(result.gettextcontent() + "\n");
        }
    }
    // 创建技术专家智能体
    private static reactagent createtechexpert(string apikey) {
        // 实现与前面类似
        // ...
    }
    // 创建ux专家智能体
    private static reactagent createuxexpert(string apikey) {
        // 实现与前面类似
        // ...
    }
    // 创建业务分析师智能体
    private static reactagent createbusinessanalyst(string apikey) {
        // 实现与前面类似
        // ...
    }
}

六、高级功能：计划与记忆

1. 使用 plannotebook 进行任务规划

filetool：操作文件的工具

/**
 * 这是一个文件工具类，用于处理文件相关的功能
 */
public class filetool {
    /**
     * 读取文件内容
     */
    @tool(name = "readfile", description = "读取指定文件的内容")
    public string readfile(@toolparam(name = "filepath", description = "文件路径") string filepath) {
        try {
            path path = paths.get(filepath);
            // 使用bufferedreader进行缓冲读取，提高大文件读取效率
            stringbuilder content = new stringbuilder();
            try (bufferedreader reader = files.newbufferedreader(path, standardcharsets.utf_8)) {
                string line;
                while ((line = reader.readline()) != null) {
                    content.append(line).append(system.lineseparator());
                }
            }
            return content.tostring();
        } catch (ioexception e) {
            return "读取文件失败: " + e.getmessage();
        }
    }
    /**
     * 写入文件内容
     */
    @tool(name = "writefile", description = "写入文件内容")
    public string writefile(@toolparam(name = "filepath", description = "文件路径") string filepath,
                            @toolparam(name = "content", description = "文件内容") string content) {
        try {
            path path = paths.get(filepath);
            // 确保父目录存在
            if (path.getparent() != null && !files.exists(path.getparent())) {
                files.createdirectories(path.getparent());
            }
            // 使用bufferedwriter进行缓冲写入，提高写入效率
            try (bufferedwriter writer = files.newbufferedwriter(path, standardcharsets.utf_8, 
                    standardopenoption.create, standardopenoption.write, standardopenoption.truncate_existing)) {
                writer.write(content);
            }
            return "文件写入成功";
        } catch (ioexception e) {
            return "写入文件失败: " + e.getmessage();
        }
    }
}

plannotebook 帮助智能体分解复杂任务并跟踪执行进度：

import io.agentscope.core.reactagent;
import io.agentscope.core.plan.plannotebook;
import io.agentscope.core.tool.toolkit;
public class plannotebookexample {
    public static void main(string[] args) {
        string apikey = system.getenv("dashscope_api_key");
        // 创建工具集
        toolkit toolkit = new toolkit();
        toolkit.registertool(new filetool());
        // 创建计划笔记本
        plannotebook plannotebook = plannotebook.builder().build();
        // 创建带计划能力的智能体
        reactagent agent = reactagent.builder()
            .name("planneragent")
            .sysprompt("你是一个有条理的助手，对于多步骤任务，先创建计划再执行。")
            .model(dashscopechatmodel.builder()
                .apikey(apikey)
                .modelname("qwen-plus")
                .build())
            .toolkit(toolkit)
            .plannotebook(plannotebook) // 配置计划笔记本
            .build();
        // 发送多步骤任务
        msg usermessage = msg.builder()
                .name("user")  // 设置发送者名称
                .role(msgrole.user)  // 指定角色为用户
                .content(textblock.builder()
                        .text(task)  // 设置消息内容
                        .build())
                .build();
        msg response = agent.call(usermessage).block();
        system.out.println("任务结果：" + response.gettextcontent());
    }
}

2. 检索增强生成（rag）

rag 技术让智能体能够利用外部知识库回答问题：

package org.example.agentscope.test;
import io.agentscope.core.reactagent;
import io.agentscope.core.message.msg;
import io.agentscope.core.message.msgrole;
import io.agentscope.core.message.textblock;
import io.agentscope.core.model.dashscopechatmodel;
import io.agentscope.core.rag.knowledge;
import io.agentscope.core.rag.ragmode;
import io.agentscope.core.rag.knowledge.simpleknowledge;
import io.agentscope.core.embedding.dashscope.dashscopetextembedding;
import io.agentscope.core.rag.store.inmemorystore;  
import io.agentscope.core.rag.model.document;
import io.agentscope.core.rag.reader.readerinput;
import io.agentscope.core.rag.reader.splitstrategy;
import io.agentscope.core.rag.reader.textreader;
import java.util.list;
public class ragexample {
    public static void main(string[] args) {
        string apikey = system.getenv("dashscope_api_key");
        // 创建嵌入模型
        var embeddingmodel = dashscopetextembedding.builder()
            .apikey(apikey)
            .modelname("text-embedding-v3")
            .dimensions(1024)
            .build();
        // 创建向量存储
        var vectorstore = inmemorystore.builder().dimensions(1024).build();
        // 创建知识库
        knowledge knowledge = simpleknowledge.builder()
            .embeddingmodel(embeddingmodel)
            .embeddingstore(vectorstore)
            .build();
        // 向知识库添加文档
        adddocumentstoknowledge(knowledge);
        // 创建带rag能力的智能体
        reactagent agent = reactagent.builder()
            .name("ragagent")
            .sysprompt("你是一个知识丰富的助手，使用提供的知识库回答问题。")
            .model(dashscopechatmodel.builder()
                .apikey(apikey)
                .modelname("qwen-max")
                .build())
            .knowledge(knowledge) // 配置知识库
            .ragmode(ragmode.agentic) // 智能体自主决定何时检索
            .build();
        // 测试rag功能
        // 快速创建用户消息
        msg usermsg = msg.builder()
                .role(msgrole.user)  // 明确指定角色为用户
                .content(textblock.builder()
                        .text("agentscope有哪些核心功能？")  // 设置消息内容
                        .build())
                .build();
        msg response = agent.call(usermsg).block();
        system.out.println("回答：" + response.gettextcontent());
    }
    private static void adddocumentstoknowledge(knowledge knowledge) {
        // 1. 创建文本阅读器（设置分块参数：最大长度512，按段落分割，重叠长度50）
        textreader reader = new textreader(512, splitstrategy.paragraph, 50);
        // 2. 准备示例文档内容（可替换为实际文档）
        string[] documenttexts = {
                "agentscope 是一个多智能体框架，支持同步和异步通信，" +
                        "提供统一的接口用于构建和管理多智能体应用。框架支持多种智能体类型，" +
                        "包括 reactagent 等实现了推理与行动循环的智能体。",
                "rag（检索增强生成）技术通过从知识库中检索相关信息来增强语言模型的生成能力，" +
                        "帮助模型获取最新信息并减少幻觉。agentscope 中的 rag 模块支持多种向量存储，" +
                        "包括内存存储和外部向量数据库。"
        };
        // 3. 处理并添加每个文档到知识库
        for (string text : documenttexts) {
            try {
                // 将文本转换为阅读器输入
                readerinput input = readerinput.fromstring(text);
                // 读取并分块文档（block() 用于同步获取结果）
                list<document> documents = reader.read(input).block();
                if (documents != null && !documents.isempty()) {
                    // 向知识库添加文档（block() 用于同步等待完成）
                    knowledge.adddocuments(documents).block();
                    system.out.println("成功添加文档：" + text.substring(0, math.min(50, text.length())) + "...");
                }
            } catch (exception e) {
                system.err.println("添加文档失败：" + e.getmessage());
            }
        }
    }
}

七、调试与监控

agentscope 提供了 studio 工具用于可视化调试,但要安装studio ，详情可查看
https://github.com/agentscope-ai/agentscope-studio

import io.agentscope.core.reactagent;
import io.agentscope.core.message.msg;
import io.agentscope.core.model.dashscopechatmodel;
import io.agentscope.core.studio.studiomanager;
import io.agentscope.core.studio.studiomessagehook;
import io.agentscope.core.studio.studiouseragent;
import java.util.list;
public class studiodebugexample {
    public static void main(string[] args) {
        // 1. 初始化 studio 连接（默认端口 5173）
        studiomanager.init()
                .studiourl("http://localhost:5173")  // studio 服务地址
                .project("myfirstproject")          // 项目名称（用于分类调试记录）
                .runname("debug_run_" + system.currenttimemillis())  // 本次运行名称（建议唯一）
                .initialize()
                .block();  // 同步等待初始化完成
        try {
            // 2. 创建带 studio 钩子的智能体（自动上报消息）
            reactagent agent = reactagent.builder()
                    .name("assistant")
                    .sysprompt("你是一个调试助手")
                    .model(dashscopechatmodel.builder()  // 配置实际使用的模型
                            .apikey(system.getenv("dashscope_api_key"))
                            .modelname("qwen-plus")
                            .build())
                    .hooks(list.of(new studiomessagehook(studiomanager.getclient())))  // 绑定 studio 钩子
                    .build();
            // 3. 创建 studio 用户代理（通过 web ui 输入消息）
            studiouseragent user = studiouseragent.builder()
                    .name("user")
                    .studioclient(studiomanager.getclient())
                    .websocketclient(studiomanager.getwebsocketclient())
                    .build();
            // 4. 运行交互循环（通过 studio web ui 输入消息）
            msg msg = null;
            while (true) {
                msg = user.call(msg).block();  // 等待 web ui 输入
                if (msg == null || "exit".equalsignorecase(msg.gettextcontent())) {
                    break;  // 输入 exit 退出
                }
                msg = agent.call(msg).block();  // 智能体处理消息
            }
        } finally {
            // 5. 关闭 studio 连接
            studiomanager.shutdown();
        }
    }
}

八、总结与进阶学习

通过本教程，你已经了解了 agentscope java 的核心能：

基础智能体创建与使用
工具开发与集成
多智能体协作（顺序与并行）
任务规划与记忆管理
检索增强生成（rag）
调试与监控

进阶学习资源

尝试扩展本教程中的示例，例如：

创建更复杂的工具集成外部api
构建多智能体协作系统解决复杂问题
集成自己的知识库实现领域专家智能体

到此这篇关于agentscope java 入门到进阶的文章就介绍到这了,更多相关agentscope java 内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！

AgentScope Java 入门到进阶指南

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