04.AgentScope Java 2.0 工具系统架构:@Tool、Toolkit、ToolGroup 三层设计详解

一灰灰blogAgentScope Java新手村核心概念与快速起步工具系统AgentScopeJavaTool注解工具系统约 3961 字大约 13 分钟

没有工具的 Agent 只能"纸上谈兵"——配上工具,它才能真正动手干活。

4.AgentScope Java 2.0 工具系统实战:@Tool 与 @ToolParam 注解全解

前几篇文章我们把 AgentScope Java 2.0 的环境搭起来了,也拆解了 ReActAgent 的推理循环。但无论推理循环设计得多优雅,如果 Agent 只有"脑子"没有"手脚",能做的事情终究有限。

一般来讲,LLM 本身是没法直接操作外部系统的——它不能查数据库、不能调 API、不能读写文件。这就是 Tool(工具)系统要解决的问题:把任意 Java 方法包装成 LLM 可调用的工具,让 Agent 在推理过程中自主决定调用时机。

这篇文章我们从实战角度,完整梳理 AgentScope Java 2.0 中工具系统的使用姿势,内容包括:

  • @Tool / @ToolParam 注解定义工具
  • Toolkit 注册和管理工具
  • 内置工具与自定义工具
  • 工具组(ToolGroup)与元工具(Meta Tool)
  • 上下文注入与 MCP / Skill

一、Tool 系统的三层架构

在动手写代码之前,先搞清楚 AgentScope 中工具系统的三个核心概念:

概念说明
Tool任意实现 AgentTool 接口(通常继承 ToolBase)或在普通类的方法上标注 @Tool 注解的对象。后者也叫 reflective function tool
Toolkit容器,负责注册 tool、MCP 客户端与 skill,向模型暴露它们的 JSON Schema,并把每次工具调用分发到对应的 tool 对象
Tool Group一组带名称的 tool / MCP / skill 集合,可整体激活或停用。Agent 通过内置 meta tool 在运行时切换 group

简单来讲,Toolkit 就像 Spring 的 ApplicationContext,@Tool 方法就像 @Bean,而 ToolGroup 就像 profile——按需激活。接下来直奔主题。

二、@Tool 注解——最轻量的工具定义方式

1. 注解属性一览

AgentScope 2.0 的 @Tool 注解支持以下属性:

属性类型说明
nameString工具名(默认取方法名)
descriptionString面向 Agent 的描述
readOnlyboolean是否只读(默认 false)
concurrencySafeboolean是否可并发调用(默认 false)
stateInjectedboolean是否注入 AgentState 参数(默认 false)
converterClass<? extends ToolResultConverter>自定义返回值转换器

使用姿势如下,先写一个简单的工具类:

import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;

public class SimpleTools {

    @Tool(
            name = "get_current_time",
            description = "获取指定时区的当前日期和时间",
            readOnly = true,
            concurrencySafe = true)
    public String getCurrentTime(
            @ToolParam(name = "timezone", description = "IANA 时区名称,例如 Asia/Shanghai、America/New_York")
                    String timezone) {
        return LocalDateTime.now(ZoneId.of(timezone))
                .format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
    }

    @Tool(
            name = "calculate",
            description = "计算简单的数学表达式",
            readOnly = true,
            concurrencySafe = true)
    public String calculate(
            @ToolParam(name = "expression", description = "数学表达式,例如 123 + 456、10 * 20")
                    String expression) {
        // 注意:生产环境不建议直接用 ScriptEngine,这里仅为演示
        return expression + " = " + eval(expression);
    }

    private double eval(String expr) {
        // 简单实现,生产环境请用表达式引擎
        String trimmed = expr.replaceAll("\\s+", "");
        if (trimmed.contains("+")) {
            String[] parts = trimmed.split("\\+");
            return Double.parseDouble(parts[0]) + Double.parseDouble(parts[1]);
        }
        if (trimmed.contains("*")) {
            String[] parts = trimmed.split("\\*");
            return Double.parseDouble(parts[0]) * Double.parseDouble(parts[1]);
        }
        return Double.parseDouble(trimmed);
    }
}

重点关注:

  • name 是工具的唯一标识,Agent 调用时使用此名称,建议用 snake_case
  • description 是 Agent 判断何时调用此工具的关键依据,越清晰越好
  • readOnly = true 表示工具不会产生副作用,权限系统会自动放行

2. @ToolParam 参数注解

@ToolParam 用于描述方法参数,只有两个属性:

属性类型说明
nameString参数名(必须指定,因为 Java 默认不保留参数名)
descriptionString参数描述
requiredboolean是否必须,默认为true

注意:@ToolParam 的 name 必须指定,这是 AgentScope 的一个硬性要求——Java 编译时默认不保留方法参数名,框架没法通过反射拿到,所以必须显式告诉 Agent 这个参数叫什么。

3. 注册到 Toolkit

工具类写好了,接下来创建一个 Toolkit 实例,把工具对象注册进去:

import io.agentscope.core.tool.Toolkit;

Toolkit toolkit = new Toolkit();
toolkit.registerTool(new SimpleTools());

当只调用 registerTool(Object) 时,被注册对象上所有 @Tool 方法都进入特殊的内置 "basic" 组——该组始终激活。

三、对接 ReActAgent——让 Agent 用上工具

1. 构建带工具的 Agent

import io.agentscope.core.ReActAgent;
import io.agentscope.core.tool.Toolkit;

// 创建模型(以 OpenAI 兼容接口为例)
OpenAIChatModel model = OpenAIChatModel.builder()
        .apiKey(System.getenv("DEEPSEEK_API_KEY"))
        .baseUrl("https://api.deepseek.com")
        .model("deepseek-chat")
        .build();

// 创建 Toolkit 并注册工具
Toolkit toolkit = new Toolkit();
toolkit.registerTool(new SimpleTools());

// 构建 Agent
ReActAgent agent = ReActAgent.builder()
        .name("assistant")
        .sysPrompt("你是一个可以使用工具的智能助手。")
        .model(model)
        .toolkit(toolkit)
        .build();

说明:ReActAgent 内置了完整的 ReAct 推理循环——收到用户消息 → 思考是否需要调用工具 → 如果需要则生成工具调用参数 → 执行工具 → 观察结果 → 继续思考或给出最终回答。这个循环我们在上一篇文章中已经详细拆解过,不再赘述。

2. 测试验证

import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import java.util.List;

// 发起对话
String response = agent.call(
        List.of(new UserMessage("现在北京时间几点?")),
        RuntimeContext.empty())
        .block();

System.out.println(response);

输出结果如下:

当前北京时间:2026-07-23T14:15:30

Agent 识别到"北京时间"对应时区 Asia/Shanghai,自动调用了 get_current_time 工具,拿到结果后生成回答。

再试一个需要推理的:

String response2 = agent.call(
        List.of(new UserMessage("12345 + 67890 等于多少?")),
        RuntimeContext.empty())
        .block();

System.out.println(response2);

实测结果如下:

12345 + 67890 = 80235

LLM 识别到需要数学计算,自动调用了 calculate 工具,拿到结果后返回。整个过程不需要我们写一行 JSON Schema 或者解析逻辑。

3. 完整可运行示例

贴一个完整的 main 方法,方便小伙伴直接复制测试:

package com.example;

import io.agentscope.core.ReActAgent;
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.core.model.OpenAIChatModel;
import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;
import io.agentscope.core.tool.Toolkit;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.util.List;

public class ToolCallingExample {

    public static class MyTools {
        @Tool(name = "get_current_time",
              description = "获取指定时区的当前时间",
              readOnly = true,
              concurrencySafe = true)
        public String getCurrentTime(
                @ToolParam(name = "timezone",
                           description = "IANA 时区名称,例如 Asia/Shanghai")
                        String timezone) {
            return LocalDateTime.now(ZoneId.of(timezone))
                    .format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
        }
    }

    public static void main(String[] args) {
        OpenAIChatModel model = OpenAIChatModel.builder()
                .apiKey(System.getenv("DEEPSEEK_API_KEY"))
                .baseUrl("https://api.deepseek.com")
                .model("deepseek-chat")
                .build();

        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(new MyTools());

        ReActAgent agent = ReActAgent.builder()
                .name("assistant")
                .sysPrompt("你是一个可以使用工具的智能助手。")
                .model(model)
                .toolkit(toolkit)
                .build();

        String response = agent.call(
                List.of(new UserMessage("伦敦现在几点了?")),
                RuntimeContext.empty())
                .block();

        System.out.println(response);
    }
}

四、内置工具开箱即用

AgentScope 提供了一些内置工具,注册就能用。

1. TodoTools——任务列表管理

用于维护当前会话的结构化任务列表:

import io.agentscope.core.tool.builtin.TodoTools;

Toolkit toolkit = new Toolkit();
toolkit.registerTool(new TodoTools());

注册后 Agent 就具备了维护 TODO 列表的能力,可以创建任务、标记完成、列出任务等。

2. 文件工具——读写文件

import io.agentscope.core.tool.file.ReadFileTool;
import io.agentscope.core.tool.file.WriteFileTool;

Toolkit toolkit = new Toolkit();

// 安全模式:限制文件访问范围
toolkit.registerTool(new ReadFileTool("/safe/workspace"));
toolkit.registerTool(new WriteFileTool("/safe/workspace"));
工具方法说明
view_text_file按行范围查看文件
list_directory列出目录下的文件和文件夹
write_text_file创建/覆盖/替换文件内容
insert_text_file在指定行插入内容

3. Shell 命令工具

import io.agentscope.core.tool.coding.ShellCommandTool;

// 带命令白名单和回调批准机制
toolkit.registerTool(new ShellCommandTool(allowedCommands, approvalCallback));

注意:Shell 命令工具涉及系统安全,记得配置白名单和回调审批,不能裸奔。

五、进阶玩法

1. 工具组(ToolGroup)——按需激活

当工具数量增多时,把所有工具都暴露给 LLM 会导致上下文噪音,影响模型的选择准确性。工具组让 Agent 按需激活特定工具集合:

import io.agentscope.core.tool.ToolGroup;
import io.agentscope.core.tool.ToolGroupScope;

Toolkit toolkit = new Toolkit();
toolkit.registerTool(new BasicTools());

// 创建数据库工具组,默认不激活
ToolGroup database = new ToolGroup(
        "database",
        "数据库操作工具集",
        ToolGroupScope.SESSION,
        false);  // 初始不激活
database.addTool("db_query");
database.addTool("db_migrate");
toolkit.registerTool(new DatabaseTools());
toolkit.registerToolGroup(database);

// 创建部署工具组,默认不激活
ToolGroup deployment = new ToolGroup(
        "deployment",
        "部署服务工具集",
        ToolGroupScope.SESSION,
        false);
deployment.addTool("deploy");
deployment.addTool("rollback");
toolkit.registerTool(new DeploymentTools());
toolkit.registerToolGroup(deployment);

// 启用 meta tool,让 Agent 自主切换工具组
ReActAgent agent = ReActAgent.builder()
        .name("router")
        .toolkit(toolkit)
        .enableMetaTool(true)
        .build();

核心逻辑:

  • "basic" 组始终激活,不受 meta tool 影响
  • enableMetaTool(true) 会自动注册 reset_tools 元工具
  • Agent 调用 reset_tools 时整体覆盖激活集合,未显式置为 true 的组都会被停用

Warning:Meta tool 的输入表示所有组的最终状态而非增量。任何未显式置为 true 的组都会被停用,无论之前的状态如何。

2. 上下文注入——给工具传递业务参数

很多时候工具需要一些业务上下文(比如当前用户信息、租户 ID),但这些信息不应该暴露给 LLM。AgentScope 通过 RuntimeContext 和自动注入来解决这个问题:

// 1. 定义业务上下文类(普通 POJO)
public record UserContext(String username, String locale) {}

// 2. 定义工具,无 @ToolParam 的参数会被框架自动注入
public class PersonalizedTools {

    @Tool(name = "greet", description = "用自定义问候语问候用户")
    public String greet(
            @ToolParam(name = "greeting", description = "问候语,例如 '你好'")
                    String greeting,              // 由 LLM 提供
            UserContext userCtx) {                 // 由框架自动注入
        return greeting + "," + (userCtx == null ? "未知用户" : userCtx.username()) + "!";
    }
}

// 3. 调用时传入上下文
RuntimeContext ctx = RuntimeContext.builder()
        .put(UserContext.class, new UserContext("一灰灰", "zh"))
        .userId("yihuihui")
        .build();

String response = agent.call(List.of(new UserMessage("问候我")), ctx).block();

注入规则:没有标注 @ToolParam、不是基本类型、不在 java.* / javax.* 包下的参数,都会被框架视为"需要注入"的参数,自动从 RuntimeContext 中按类型匹配。

除了自定义 POJO,框架还支持注入以下类型:

参数类型注入来源
ToolEmitter流式中间产物 emitter
Agent当前 agent 实例
AgentState当前 call 的 per-session 状态
RuntimeContext当前 per-call 上下文
自定义 POJOruntimeContext.get(ParamType.class)

3. 继承 ToolBase——更精细的控制

当需要自定义权限策略、外部执行或更复杂的参数 schema 时,可以继承 ToolBase:

import io.agentscope.core.message.ToolResultBlock;
import io.agentscope.core.permission.PermissionDecision;
import io.agentscope.core.tool.ToolBase;
import io.agentscope.core.tool.ToolCallParam;
import io.agentscope.core.tool.ToolExecutionContext;
import reactor.core.publisher.Mono;
import java.util.List;
import java.util.Map;

public class WebSearchTool extends ToolBase {

    public WebSearchTool() {
        super(ToolBase.builder()
                .name("web_search")
                .description("搜索互联网信息")
                .inputSchema(Map.of(
                        "type", "object",
                        "properties", Map.of(
                                "query", Map.of(
                                        "type", "string",
                                        "description", "搜索关键词")),
                        "required", List.of("query")))
                .readOnly(true)
                .concurrencySafe(true));
    }

    @Override
    public Mono<PermissionDecision> checkPermissions(
            Map<String, Object> toolInput, ToolExecutionContext context) {
        return Mono.just(PermissionDecision.allow("搜索是只读操作。"));
    }

    @Override
    public Mono<ToolResultBlock> callAsync(ToolCallParam param) {
        String query = (String) param.getInput().get("query");
        // 执行搜索...
        return Mono.just(ToolResultBlock.text("搜索结果:" + query));
    }
}

这种方式的优势是可以自定义权限检查逻辑、支持外部执行(externalTool = true 实现 human-in-the-loop)、以及更灵活的参数 schema。

4. 外部执行 Tool——Human-in-the-Loop

有些敏感操作(比如删除数据、转账)需要人工确认。设置 externalTool = true 后,工具执行会委派给外部,Agent 发出 RequireExternalExecutionEvent 并暂停:

public class HumanApprovalTool extends ToolBase {

    public HumanApprovalTool() {
        super(ToolBase.builder()
                .name("human_approval")
                .description("请求人工审批敏感操作")
                .inputSchema(Map.of(
                        "type", "object",
                        "properties", Map.of(
                                "action", Map.of("type", "string"),
                                "reason", Map.of("type", "string")),
                        "required", List.of("action", "reason")))
                .externalTool(true)  // 委派给外部执行
                .build());
    }

    @Override
    public Mono<PermissionDecision> checkPermissions(
            Map<String, Object> toolInput, ToolExecutionContext context) {
        return Mono.just(PermissionDecision.allow("外部工具始终放行。"));
    }
}

六、执行配置与最佳实践

1. 工具执行超时与重试

import io.agentscope.core.model.ExecutionConfig;
import java.time.Duration;

ReActAgent agent = ReActAgent.builder()
        .name("assistant")
        .model(model)
        .toolkit(toolkit)
        .toolExecutionConfig(ExecutionConfig.builder()
                .timeout(Duration.ofSeconds(30))
                .maxRetries(2)
                .build())
        .build();

2. description 的编写技巧

作为贴心的一灰灰博主,这里给各位小伙伴分享几个 description 的编写技巧:

反面示例(Agent 根本不知道什么时候该调):

@Tool(name = "do_stuff", description = "做事情")
public String doStuff(String input) { ... }

正面示例(Agent 一眼就知道该不该调):

@Tool(name = "get_weather",
      description = "获取指定城市的当前天气信息,返回温度、湿度和天气状况。"
              + "当用户询问某个地点的天气时使用此工具。")
public String getWeather(
        @ToolParam(name = "city",
                  description = "城市英文名称,例如 Beijing、New York")
                String city) { ... }

总结三条原则:

  • 明确功能边界:说清楚工具能做什么、不能做什么
  • 包含使用场景:提示 Agent 什么情况下应该调用
  • 参数描述清晰:每个参数的含义、格式、取值范围

3. @ToolParam 的 name 必须填

这个是新手最容易踩的坑——Java 编译时参数名默认不保留,所以 @ToolParam 的 name 属性必须显式指定。如果漏了,Agent 拿到的 JSON Schema 里参数名会是 arg0、arg1,模型根本不知道应该传什么。

当然如果项目开启了 -parameters 编译参数(Maven 的 <parameters>true</parameters>),框架可以反射拿到原始参数名,这时候可以不填 name。但为了代码的可读性和健壮性,建议始终显式指定。

七、MCP 与 Skill 简介

1. MCP(Model Context Protocol)

AgentScope 支持通过 MCP 接入任意兼容的工具提供方,支持 STDIO、SSE 和 Streamable HTTP 三种连接方式:

import io.agentscope.core.tool.mcp.McpClientBuilder;

// STDIO 方式接入本地工具
McpClientWrapper filesystem = McpClientBuilder.stdio()
        .name("filesystem")
        .command("npx")
        .args("-y", "@modelcontextprotocol/server-filesystem", "/my/project")
        .build();

toolkit.registerMcpClient(filesystem).block();

注册后 MCP tool 以 mcp__{server_name}__{tool_name} 命名,避免命名冲突。

2. Skill——基于 Markdown 的指令集

Skill 是 AgentScope 的特色能力——不需要写 Java 代码,用 Markdown 就能拓展 Agent 能力。每个 skill 是一个包含 SKILL.md 文件的目录,Agent 通过内置的 load_skill_through_path 工具读取指令后按步骤执行。

import io.agentscope.core.skill.repository.FileSystemSkillRepository;
import java.nio.file.Paths;

ReActAgent agent = ReActAgent.builder()
        .name("SkillAgent")
        .model(model)
        .toolkit(toolkit)
        .skillRepository(new FileSystemSkillRepository(
                Paths.get("/path/to/skills"), false))
        .build();

Skill + ToolGroup 的组合可以做到"加载 skill 时自动激活关联工具组",减少上下文噪音。这块内容比较多,后面单独开一篇细讲。

八、小结

本文从实战角度梳理了 AgentScope Java 2.0 中工具系统的使用姿势,小结一下:

  • @Tool / @ToolParam 注解是最轻量的工具定义方式,一行注解就能把任意 Java 方法变成 Agent 可调用的能力
  • Toolkit 是工具的统一容器,负责注册、分发和 Schema 生成
  • ReActAgent + Toolkit 的组合让 Agent 在推理循环中自主决定何时调用哪个工具
  • 内置工具(TodoTools、ReadFileTool、WriteFileTool、ShellCommandTool)开箱即用
  • ToolGroup + enableMetaTool(true) 实现工具的按需激活与运行时自我管理
  • RuntimeContext 注入机制让工具可以安全地拿到业务上下文,无需暴露给 LLM
  • MCP 和 Skill 进一步拓展了工具的来源和用法

九、其他

0. 项目

1. 下篇预告

本文是【AgentScope Java 新手村系列】的第四篇。回顾一下系列进度:

  • ✅ 第1篇:简介与环境搭建open in new window:从零搭环境,跑通第一个 Agent 对话
  • ✅ 第2篇:ReActAgent 核心拆解open in new window:理解"思考→行动→观察"的推理循环
  • ✅ 第3篇:你的第一个 Java Agent:Builder 模式全面解析 + 流式输出 + 思考模式
  • ✅ 第4篇:工具系统(Tools)实战 —— 用 @Tool 注解将任意 Java 方法注册为 Agent 工具
  • 🔜 第5篇:结构化输出 —— 让 Agent 直接返回指定的 Java 类型数据

看到这里的小伙伴,有没有跃跃欲试的冲动?给 Agent 配上工具之后,能干的事情一下子多起来了。那么问题来了——工具调用返回的结果通常是字符串,如果我想让 Agent 直接返回一个 Java 对象,该怎么办?AgentScope 的结构化输出支持什么样的使用姿势? 这些问题我们下一篇再详细展开。

尽信书则不如,以上内容,纯属一家之言,因个人能力有限,难免有疏漏和错误之处,如发现 bug 或者有更好的建议,欢迎批评指正,不吝感激。

微信公众号: 一灰灰Blog —— 关注获取最新技术文章推送

Loading...