AgentScope Java 智能体开发指南 | 极客日志

JavaAIjava

AgentScope Java 智能体开发指南

AgentScope Java 是一个面向智能体的编程框架，用于构建基于大语言模型的应用。本文涵盖环境配置、基础智能体创建、自定义工具开发、多智能体协作管道、任务规划及 RAG 检索增强生成等核心功能，并提供代码示例说明如何实现 ReAct 推理、工具调用、顺序与并行管道执行及 Studio 调试方法，帮助开发者快速掌握生产级 AI 智能体应用的开发流程。

Stephaine Walsh发布于 2026/3/300 浏览

一、什么是 AgentScope Java？

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

二、环境准备

1. 系统要求

JDK 17 或更高版本
Maven 或 Gradle 构建工具

2. 添加依赖

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

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope</artifactId>
    <version></version>
</dependency>

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());
    }
}

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; // 实际计算结果
    }
}

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());
    }
}

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();
    }
}

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) { /* 实现与前面类似 */ return null; }
    private static ReActAgent createUXExpert(String apiKey) { /* 实现与前面类似 */ return null; }
    private static ReActAgent createBusinessAnalyst(String apiKey) { /* 实现与前面类似 */ return null; }
}

public class FileTool {
    @Tool(name = "readFile", description = "读取指定文件的内容")
    public String readFile(@ToolParam(name = "filePath", description = "文件路径") String filePath) {
        try {
            Path path = Paths.get(filePath);
            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());
            }
            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();
        }
    }
}

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());
    }
}

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);
        ReActAgent agent = ReActAgent.builder()
                .name("RAGAgent")
                .sysPrompt("你是一个知识丰富的助手，使用提供的知识库回答问题。")
                .model(DashScopeChatModel.builder()
                        .apiKey(apiKey)
                        .modelName("qwen-max")
                        .build())
                .knowledge(knowledge)
                .ragMode(RAGMode.AGENTIC)
                .build();
        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) {
        TextReader reader = new TextReader(512, SplitStrategy.PARAGRAPH, 50);
        String[] documentTexts = {
                "AgentScope 是一个多智能体框架，支持同步和异步通信，提供统一的接口用于构建和管理多智能体应用。",
                "RAG（检索增强生成）技术通过从知识库中检索相关信息来增强语言模型的生成能力，帮助模型获取最新信息并减少幻觉。"
        };
        for (String text : documentTexts) {
            try {
                ReaderInput input = ReaderInput.fromString(text);
                List<Document> documents = reader.read(input).block();
                if (documents != null && !documents.isEmpty()) {
                    knowledge.addDocuments(documents).block();
                    System.out.println("成功添加文档：" + text.substring(0, Math.min(50, text.length())) + "...");
                }
            } catch (Exception e) {
                System.err.println("添加文档失败：" + e.getMessage());
            }
        }
    }
}

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) {
        StudioManager.init()
                .studioUrl("http://localhost:5173")
                .project("MyFirstProject")
                .runName("debug_run_" + System.currentTimeMillis())
                .initialize()
                .block();
        try {
            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())))
                    .build();
            StudioUserAgent user = StudioUserAgent.builder()
                    .name("User")
                    .studioClient(StudioManager.getClient())
                    .webSocketClient(StudioManager.getWebSocketClient())
                    .build();
            Msg msg = null;
            while (true) {
                msg = user.call(msg).block();
                if (msg == null || "exit".equalsIgnoreCase(msg.getTextContent())) {
                    break;
                }
                msg = agent.call(msg).block();
            }
        } finally {
            StudioManager.shutdown();
        }
    }
}

AgentScope Java 智能体开发指南

一、什么是 AgentScope Java？

二、环境准备

1. 系统要求

2. 添加依赖

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

1. 最简单的智能体示例

2. 代码解释

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

1. 创建自定义工具

2. 在智能体中使用工具

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

1. 顺序管道（Sequential Pipeline）

2. 并行管道（Fanout Pipeline）

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

1. 使用 PlanNotebook 进行任务规划

2. 检索增强生成（RAG）

七、调试与监控

八、总结与进阶学习

更多推荐文章

相关免费在线工具

AgentScope Java 智能体开发指南

一、什么是 AgentScope Java？

二、环境准备

1. 系统要求

2. 添加依赖

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

1. 最简单的智能体示例

2. 代码解释

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

1. 创建自定义工具

2. 在智能体中使用工具

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

1. 顺序管道（Sequential Pipeline）

2. 并行管道（Fanout Pipeline）

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

1. 使用 PlanNotebook 进行任务规划

2. 检索增强生成（RAG）

七、调试与监控

八、总结与进阶学习

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具