AgentScope Java 项目入门 Builder 深度解读

第一部分：AgentScope Java 项目入门

一、项目定位

AgentScope Java 是阿里巴巴开源的 AI 智能体编程框架（Apache-2.0，JDK 17+），用于构建基于大语言模型（LLM）的生产级应用。可以类比为 Java 版的 LangChain + CrewAI，但更面向企业级生产环境。

Maven 坐标：io.agentscope:agentscope:2.0.0-SNAPSHOT

二、模块全景

项目是多模块 Maven 工程，共 6 个顶层模块：

三、核心概念（5 个关键抽象）

理解这 5 个抽象就掌握了框架骨架：

四、ReAct 循环 ——Agent 的核心工作方式

1. 用户输入 → Agent 推理（LLM 决定用什么工具）→ 执行工具 → 观察结果 → 再推理 → … → 最终回复

ReActAgent是这个循环的核心实现，关键参数：

• maxIters— 最大推理轮数（防止无限循环）
• toolkit— 注册的工具集
• middleware— 中间件链（2.0 新特性，替代 Hook）

五、最小可运行示例

ReActAgent agent = ReActAgent.builder() .name("Assistant") .sysPrompt("你是一个有帮助的 AI 助手。") .model(DashScopeChatModel.builder() .apiKey(System.getenv("DASHSCOPE_API_KEY")) .modelName("qwen-max") .build()) .build(); // 同步调用 Msg response = agent.call(Msg.builder() .textContent("你好！") .build()).block(); System.out.println(response.getTextContent());

六、工具定义（最常用功能）

用注解定义工具，框架自动生成 JSON Schema 给 LLM：

public class MyTools { @Tool(description = "查询天气信息") public String getWeather( @ToolParam(name = "city", description = "城市名称") String city ) { return city + "今天晴, 25℃"; } } // 注册到 Agent Toolkit toolkit = new Toolkit(); toolkit.registerTool(new MyTools()); ReActAgent agent = ReActAgent.builder() .name("WeatherAgent") .toolkit(toolkit) .model(model) .build();

七、关键设计特点

八、核心架构（agentscope-core 包结构）

基础路径：agentscope-core/src/main/java/io/agentscope/core/

九、扩展模块一览（agentscope-extensions）

十、关键类速查表

十一、重要编码禁忌

十二、推荐的入门路径

1. 先读SKILL.md（项目根目录）— 官方编码指南，1053 行，包含完整 API 用法和避坑规则
2. 跑示例agentscope-examples/下的示例应用，特别是agentscope-codingagent（带技能的编码 Agent）
3. 理解核心：读ReActAgent.java源码，理解 ReAct 循环的实现
4. 尝试扩展：看agentscope-extensions/中感兴趣的扩展（如 MCP、RAG、长期记忆）