AgentScope Java 实战：构建 LLM 智能体与多智能体协作

关键点：ReActAgent.builder() 用建造者模式创建智能体，sysPrompt 定角色，model 接模型。实际项目里 API key 应该放环境变量，不要写死在代码里。

给智能体配上工具

工具让智能体能做具体的事，比如计算数学表达式。先写一个带 @Tool 注解的类：

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

多智能体协作

单个智能体只能做一件事，复杂任务需要多个智能体配合。AgentScope 提供了两种管道：顺序管道和并行管道。

顺序管道

让智能体按顺序处理，前一个输出成为后一个输入。像翻译→摘要→情感分析这样的流水线：

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

任务规划与记忆

有时任务需要多步执行，光靠一轮对话不够。AgentScope 的 PlanNotebook 能让智能体先分解任务、制定计划，再一步步用工具执行。

先准备一个文件操作工具类：

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

把工具和 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();

        String task = "分析当前项目并生成报告";
        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());
    }
}

检索增强生成（RAG）

想让智能体基于自己的文档回答问题，RAG 是标配。AgentScope 内置了从文档读取、分块、向量化到存储的整套流程，用起来很省事。

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 是一个多智能体框架，支持同步和异步通信，提供统一的接口用于构建和管理多智能体应用。框架支持多种智能体类型，包括 ReActAgent 等实现了推理与行动循环的智能体。",
            "RAG（检索增强生成）技术通过从知识库中检索相关信息来增强语言模型的生成能力，帮助模型获取最新信息并减少幻觉。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());
            }
        }
    }
}

这里用的是阿里云 text-embedding-v3 做嵌入，内存向量存储。生产环境可以换成 Milvus 之类的外部数据库。

调试与监控

开发时少不了观察智能体的思考链路。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) {
        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();
        }
    }
}

Studio 默认跑在 localhost:5173，启动后打开浏览器就能看到交互界面。

进阶方向

这套框架已经很完整了，但还有很多可以折腾的地方：把外部 API 封成工具、设计更复杂的多智能体协作流程、用真实业务文档替换知识库。官方文档和 examples 仓库是很好的起点：

• 官方文档
• 示例代码库
• Studio 可视化调试工具