04.AgentScope Java 2.0 工具系统架构:@Tool、Toolkit、ToolGroup 三层设计详解
没有工具的 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 注解支持以下属性:
| 属性 | 类型 | 说明 |
|---|---|---|
name | String | 工具名(默认取方法名) |
description | String | 面向 Agent 的描述 |
readOnly | boolean | 是否只读(默认 false) |
concurrencySafe | boolean | 是否可并发调用(默认 false) |
stateInjected | boolean | 是否注入 AgentState 参数(默认 false) |
converter | Class<? 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_casedescription是 Agent 判断何时调用此工具的关键依据,越清晰越好readOnly = true表示工具不会产生副作用,权限系统会自动放行
2. @ToolParam 参数注解
@ToolParam 用于描述方法参数,只有两个属性:
| 属性 | 类型 | 说明 |
|---|---|---|
name | String | 参数名(必须指定,因为 Java 默认不保留参数名) |
description | String | 参数描述 |
required | boolean | 是否必须,默认为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 上下文 |
| 自定义 POJO | runtimeContext.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. 项目
- 工程示例:https://github.com/liuyueyi/spring-ai-demo/agent-scope
- AgentScope Java Tool 官方文档:https://java.agentscope.io/v2/zh/docs/building-blocks/tool.html
1. 下篇预告
本文是【AgentScope Java 新手村系列】的第四篇。回顾一下系列进度:
- ✅ 第1篇:简介与环境搭建:从零搭环境,跑通第一个 Agent 对话
- ✅ 第2篇:ReActAgent 核心拆解:理解"思考→行动→观察"的推理循环
- ✅ 第3篇:你的第一个 Java Agent:Builder 模式全面解析 + 流式输出 + 思考模式
- ✅ 第4篇:工具系统(Tools)实战 —— 用
@Tool注解将任意 Java 方法注册为 Agent 工具 - 🔜 第5篇:结构化输出 —— 让 Agent 直接返回指定的 Java 类型数据
看到这里的小伙伴,有没有跃跃欲试的冲动?给 Agent 配上工具之后,能干的事情一下子多起来了。那么问题来了——工具调用返回的结果通常是字符串,如果我想让 Agent 直接返回一个 Java 对象,该怎么办?AgentScope 的结构化输出支持什么样的使用姿势? 这些问题我们下一篇再详细展开。
尽信书则不如,以上内容,纯属一家之言,因个人能力有限,难免有疏漏和错误之处,如发现 bug 或者有更好的建议,欢迎批评指正,不吝感激。
微信公众号: 一灰灰Blog —— 关注获取最新技术文章推送