AgentScope Java 框架实战：从基础构建到多智能体协作

代码解析：

• ReActAgent.builder()：采用建造者模式初始化智能体。
• 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. 在智能体中使用工具

将工具注册到 Toolkit 中，并在智能体配置时绑定。

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();
        System.out.println("计算结果：" + response.getTextContent());
    }
}

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

AgentScope 支持多种管道模式来编排多个智能体，实现复杂任务的分流处理。

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

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

1. 使用 PlanNotebook 进行任务规划

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("读取 config.txt 并总结内容").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) {
        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("成功添加文档...");
                }
            } catch (Exception e) {
                System.err.println("添加文档失败：" + e.getMessage());
            }
        }
    }
}

七、调试与监控

AgentScope 提供了 Studio 工具用于可视化调试。要使用此功能，需确保本地运行了 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 连接
        StudioManager.init()
            .studioUrl("http://localhost:5173")
            .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())))
                .build();

            // 3. 创建 Studio 用户代理
            StudioUserAgent user = StudioUserAgent.builder()
                .name("User")
                .studioClient(StudioManager.getClient())
                .webSocketClient(StudioManager.getWebSocketClient())
                .build();

            // 4. 运行交互循环
            Msg msg = null;
            while (true) {
                msg = user.call(msg).block();
                if (msg == null || "exit".equalsIgnoreCase(msg.getTextContent())) {
                    break;
                }
                msg = agent.call(msg).block();
            }
        } finally {
            // 5. 关闭 Studio 连接
            StudioManager.shutdown();
        }
    }
}

八、总结与进阶学习

通过本教程，你已经掌握了 AgentScope Java 的核心能力：

1. 基础智能体创建：理解如何配置模型与提示词。
2. 工具开发与集成：学会扩展智能体的外部交互能力。
3. 多智能体协作：掌握顺序与并行管道的编排方式。
4. 任务规划与记忆：利用 PlanNotebook 处理复杂工作流。
5. 检索增强生成（RAG）：结合知识库提升回答准确性。
6. 调试与监控：使用 Studio 进行可视化调试。

推荐资源：

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

后续可以尝试构建更复杂的工具链，例如集成外部 API，或者设计多智能体协作系统来解决特定领域的复杂问题。