AgentScope Java 简介
AgentScope Java 是一个面向智能体的编程框架,用于构建基于大语言模型(LLM)的应用程序。它提供了创建智能代理所需的一切功能:ReAct 推理、工具调用、内存管理、多智能体协作等。
智能代理,全面掌控
AgentScope 采用 ReAct(推理 - 行动)范式,使代理能够自主规划并执行复杂任务。与基于固定工作流的方法不同,ReAct 代理可动态决定工具的使用时机,实时适应需求变化。
但生产中若缺乏控制,自主性将成为隐患。AgentScope 提供全方位的运行时干预机制:
- 安全中断 - 随时暂停代理执行,完整保留上下文与工具状态,实现无数据丢失的流畅恢复
- 优雅终止 - 强制结束长时间运行或无响应的工具调用,且不破坏代理状态,支持即时恢复与重定向
- 人在回路 - 通过 Hook 系统在任何推理步骤注入修正、补充上下文或指导,确保人类对关键决策的监督权
内置工具
AgentScope 包含一系列开箱即用的工具,解决智能体开发中的常见挑战:
- 计划笔记本(PlanNotebook) - 结构化任务管理系统,将复杂目标分解为可追踪的有序步骤。智能体可创建、修改、暂停和恢复多个并行计划,确保多步骤工作流的系统性执行。
- 结构化输出(Structured Output) - 具备自校正能力的输出解析器,保障类型安全响应。当大语言模型输出偏离预期格式时,系统自动检测错误并引导模型生成有效输出,结果直接映射为 Java POJO 对象,无需手动解析。
- 长期记忆(Long-term Memory) - 支持跨会话语义检索的持久化存储。提供自动管理、智能体自主记录或混合管理模式。满足企业级多租户隔离需求,确保智能体独立服务不同用户。
- 检索增强生成(RAG) - 与企业知识库无缝集成。支持自托管嵌入检索和阿里云百炼等托管服务,使智能体应答基于权威数据源。
无缝集成
AgentScope 设计用于与现有企业基础设施集成,无需大量修改:
- MCP 协议 - 集成任何兼容 MCP 的服务器以扩展智能体能力。连接不断增长的 MCP 工具和生态系统——从文件系统、数据库到 Web 浏览器和代码解释器——而无需编写自定义集成代码。
- A2A 协议 - 通过标准服务发现启用分布式多智能体协作。将智能体能力注册到 Nacos 或类似注册中心,允许智能体像调用微服务一样自然地发现和调用彼此。
生产级特性
专为部署需求构建:
- 高性能 - 基于 Project Reactor 的反应式架构确保非阻塞执行。GraalVM 原生镜像编译实现 200ms 冷启动时间,使 AgentScope 适用于 Serverless 和自动扩缩容环境。
- 安全沙箱 - AgentScope Runtime 为不受信任的工具代码提供隔离执行环境。包括预构建的沙箱用于 GUI 自动化、文件系统操作和移动设备交互,防止未经授权访问系统资源。
- 可观测性 - 原生集成 OpenTelemetry 以实现整个智能体执行流程的分布式追踪。AgentScope Studio 提供可视化调试、实时监控和生产环境的综合日志记录。
环境要求
- JDK 17 或更高版本
- Maven 或 Gradle
快速开始
按照以下步骤开始使用 AgentScope Java:
- 安装 - 在项目中设置 AgentScope Java
- 核心概念 - 理解核心概念和架构
- 构建你的第一个智能体 - 创建工作代理
创建 Agent
import io.agentscope.core.ReActAgent;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.message.Msg;
ReActAgent agent = ReActAgent.builder()
.name("Assistant")
.sysPrompt("You are a helpful AI assistant.")
.model(DashScopeChatModel.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.modelName("qwen3-max")
.build())
.build();
Msg response = agent.call(Msg.builder()
.textContent("Hello!")
.build()).block();
System.out.println(response.getTextContent());
创建带工具的 Agent
import io.agentscope.core.ReActAgent;
import io.agentscope.core.message.Msg;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.tool.Toolkit;
import io.agentscope.core.tool.annotation.Tool;
import io.agentscope.core.tool.annotation.ToolParam;
public class QuickStart {
public static void main(String[] args) {
Toolkit toolkit = new Toolkit();
toolkit.registerTool(new SimpleTools());
ReActAgent jarvis = ReActAgent.builder()
.name("Jarvis")
.sysPrompt("You are an assistant named Jarvis.")
.model(DashScopeChatModel.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.modelName("qwen3-max")
.build())
.toolkit(toolkit)
.build();
Msg msg = Msg.builder()
.textContent("Hello Jarvis, what time is it now?")
.build();
Msg response = jarvis.call(msg).block();
System.out.println(response.getTextContent());
}
}
class SimpleTools {
@Tool(name = "get_time", description = "Get current time")
String {
java.time.LocalDateTime.now()
.format(java.time.format.DateTimeFormatter.ofPattern());
}
}
更多详情参考:AgentScope Java GitHub
Agent Skills
概述
Agent Skills 是模块化技能包,用于扩展智能体能力。每个 Skill 包含指令、元数据和可选资源(如脚本、参考文档、示例等),智能体将在相关任务中自动使用它们。
核心特性
渐进式披露机制
采用三阶段按需加载优化上下文:初始仅加载元数据(约 100 tokens/Skill)→ AI 需要时加载完整指令(<5k tokens)→ 按需访问资源文件。工具也渐进式披露,仅在 Skill 使用时激活。
工作流程: 用户查询 → AI 识别相关 Skill → 调用工具加载内容并激活绑定工具 → 按需资源访问 → 任务完成
自适应设计
进一步抽象了技能,使其发现和加载不再依赖文件系统。相反,LLM 通过工具发现和加载技能内容及资源。同时,为了保持与现有技能生态系统和资源的兼容性,技能和资源仍按文件系统结构组织。
像组织文件系统中的技能目录一样组织你的技能内容和资源!
以 Skill Structure 为例,此目录结构的技能在我们的系统中表示为:
AgentSkill skill = new AgentSkill.builder()
.name("data_analysis")
.description("Use this skill when analyzing data, calculating statistics, or generating reports")
.skillContent("# Data Analysis\n...")
.addResource("references/api-doc.md", "# API Reference\n...")
.addResource("references/best-practices.md", "# Best Practices\n...")
.addResource("examples/example1.java", "public class Example1 {\n...\n}")
.addResource("scripts/process.py", "def process(data): ...\n")
.build();
目录结构
skill-name/
├── SKILL.md
├── references/
│ ├── api-doc.md
│ └── best-practices.md
├── examples/
│ └── example1.java
└── scripts/
└── process.py
README 结构
---
name: skill-name
description: This skill should be used when...
---
[Detailed description of the skill's functionality]
[Usage steps and best practices]
- references/api-doc.md: API reference documentation
- scripts/process.py: Data processing script
功能探索
熟悉基础后,可以探索以下功能:
模型集成
- 模型集成 - 配置不同的 LLM 提供商
- 多模态 - 视觉和多模态能力
工具与知识
- 工具系统 - 使用基于注解的注册创建和使用工具
- MCP - Model Context Protocol 支持高级工具集成
- RAG - 检索增强生成以增强知识响应
- 结构化输出 - 具有自动校正的类型安全输出解析
行为控制
- Hook 系统 - 使用事件钩子监控和自定义智能体行为
- 内存管理 - 管理对话历史和长期记忆
- 规划 - 复杂多步任务的规划管理
- 智能体配置 - 高级智能体配置选项
多智能体系统
可观测性与调试
AI 辅助开发
AgentScope 为 Cursor、Windsurf 和 GitHub Copilot 等 AI 代码助手提供了 LLM 友好的指南。此指南帮助 AI 助手理解 AgentScope Java 的 API、模式和最佳实践以生成准确代码。
Cursor 快速设置:
- 打开 Cursor Settings -> Features -> Docs
- 点击'+ Add new Doc'
- 添加 URL:
https://raw.githubusercontent.com/agentscope-ai/agentscope-java/main/docs/llm/agentscope-llm-guide.md
有关其他 AI IDE 的详细设置说明和最佳实践,请参阅 使用 AgentScope Java 与 AI 代码助手。