AgentScope Java 智能体框架入门与进阶

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) { /* 实现与前面类似 */ }
    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);
            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();
            
        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);
        
        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());
            }
        }
    }
}

七、调试与监控

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")
            .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 用户代理（通过 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();
                if (msg == null || "exit".equalsIgnoreCase(msg.getTextContent())) {
                    break;
                }
                msg = agent.call(msg).block();
            }
        } finally {
            // 5. 关闭 Studio 连接
            StudioManager.shutdown();
        }
    }
}

八、总结与进阶学习

通过本教程，你已经了解了 AgentScope Java 的核心功能：

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

进阶学习资源

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

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

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