AgentScope Java 框架安装与使用指南

创建 Agent

import io.agentscope.core.ReActAgent;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.message.Msg;

// Create an agent with inline model configuration
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) {
        // Prepare tools
        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(new SimpleTools());

        // Create agent
        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();

        // Send message
        Msg msg = Msg.builder()
            .textContent("Hello Jarvis, what time is it now?")
            .build();
        Msg response = jarvis.call(msg).block();
        System.out.println(response.getTextContent());
    }
}

// Tool class
class SimpleTools {
    @Tool(name = "get_time", description = "Get current time")
    public String getTime(
        @ToolParam(name = "zone", description = "Timezone, e.g., Beijing") String zone) {
        return java.time.LocalDateTime.now()
            .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
    }
}

更多详情参考：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 # Required: Entry file with YAML frontmatter and instructions
├── references/ # Optional: Detailed reference documentation
│   ├── api-doc.md
│   └── best-practices.md
├── examples/ # Optional: Working examples
│   └── example1.java
└── scripts/ # Optional: Executable scripts
    └── process.py

README 结构

---
name: skill-name # Required: Skill name (lowercase letters, numbers, underscores)
description: This skill should be used when... # Required: Trigger description, explaining when to use
---
# Skill Name
## Feature Overview
[Detailed description of the skill's functionality]
## Usage Instructions
[Usage steps and best practices]
## Available Resources
- references/api-doc.md: API reference documentation
- scripts/process.py: Data processing script

功能探索

熟悉基础后，可以探索以下功能：

模型集成

• 模型集成 - 配置不同的 LLM 提供商
• 多模态 - 视觉和多模态能力

工具与知识

• 工具系统 - 使用基于注解的注册创建和使用工具
• MCP - Model Context Protocol 支持高级工具集成
• RAG - 检索增强生成以增强知识响应
• 结构化输出 - 具有自动校正的类型安全输出解析

行为控制

• Hook 系统 - 使用事件钩子监控和自定义智能体行为
• 内存管理 - 管理对话历史和长期记忆
• 规划 - 复杂多步任务的规划管理
• 智能体配置 - 高级智能体配置选项

多智能体系统

• Pipeline - 使用顺序和并行执行构建多智能体工作流
• MsgHub - 多智能体通信的消息中心
• A2A 协议 - Agent2Agent 协议支持
• 状态管理 - 跨会话持久化和恢复智能体状态

可观测性与调试

• AgentScope Studio - 可视化调试和监控

AI 辅助开发

AgentScope 为 Cursor、Windsurf 和 GitHub Copilot 等 AI 代码助手提供了 LLM 友好的指南。此指南帮助 AI 助手理解 AgentScope Java 的 API、模式和最佳实践以生成准确代码。

Cursor 快速设置：

1. 打开 Cursor Settings -> Features -> Docs
2. 点击'+ Add new Doc'
3. 添加 URL：https://raw.githubusercontent.com/agentscope-ai/agentscope-java/main/docs/llm/agentscope-llm-guide.md

有关其他 AI IDE 的详细设置说明和最佳实践，请参阅 使用 AgentScope Java 与 AI 代码助手。