第三章 工具程序与 @Tool 注解：让 Agent 自主决定调用哪个 Java 方法

什么是工具

痛点：很多新手在建立智能体时只会写提示词。却不知道如何让它真正动手执行查询、计算或文件操作，导致程序只能停留在理论层面。

工具是 Agent 与外部世界交互的能力。通过给 Agent 配备工具。它可以：

• 查询数据库
• 调用 API
• 执行计算
• 读写文件
• 搜索网络

Agent 在推理过程中会自主决定是否需要调用工具，还有调用哪个工具。按理说，

@Tool 注解

痛点：不清楚如何把普通的 Java 方法暴露给 LLM。往往要自己写大量桥接代码，既繁琐又易出错。其实，

使用 @Tool 注解将 Java 方法注册为 Agent 可调用的工具：

import io.agentscope.core.tool.Tool;import io.agentscope.core.tool.ToolParam;public class MyTools {
@Tool
public String getCurrentTime(
@ToolParam
String timezone) {
// 实现逻辑
return "Current time in " + timezone + ": -- ::";}
}

关键点这方面。

• @Tool 的 name 属性是工具的唯一标识，Agent 调用时使用此名称。
• @Tool 的 description 属性描述工具的功能，Agent 根据此描述决定何时调用。
• @ToolParam 标注在方法参数上，描述参数的含义。
• 方法的返回值会作为工具的执行结果返回给 Agent。
• 完全兼容 .x 的 @Tool/@ToolParam 注解与 Toolkit.registerTool 注册方式。老实说，HarnessAgent 在工作区模式下还支持通过 workspace/tools.json 声明 MCP server 和工具白名单——详见第十五章。

注册工具

痛点：PaaS 环境里常常忘记把自定义工具加入 Toolkit，导致 Agent 提问时“找不到对应函数”。下面演示正确的注册方式，

Toolkit toolkit = new Toolkit;toolkit.registerTool);

import io.agentscope.core.ReActAgent;老实说，import io.agentscope.core.tool.Toolkit;// 纯 ReActAgent 场景
ReActAgent agent = ReActAgent.builder
.name
.sysPrompt
.model
.toolkit
.build;// 或 HarnessAgent 场景
HarnessAgent agent = HarnessAgent.builder
.name
.sysPrompt
.model
.workspace)
.toolkit // 工具集可以和工作区并存
.build;

完整示例的观点是，带工具的 Agent

package com.example;import io.agentscope.core.ReActAgent;import io.agentscope.core.agent.RuntimeContext;import io.agentscope.core.formatter.openai.OpenAIChatFormatter;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;public class ToolCallingExample {
public static void main {
String apiKey = System.getenv;// 创建工具集并注册工具
Toolkit toolkit = new Toolkit;toolkit.registerTool);ReActAgent agent = ReActAgent.builder
.name
.sysPrompt(
"你是一个可以使用工具的助手。" +
"在需要时使用工具来准确回答问题。" +
"每次使用工具时请解释你在做什么。")
.model
.apiKey
.modelName
.baseUrl
.stream
.formatter)
.build)
.toolkit
.build;// 测试工具调用
String reply = agent.call,RuntimeContext.empty)
.block
.getTextContent;System.out.println;}
/**
* 工具类：每个带 @Tool 注解的方法都会被注册为一个工具
*/
public static class SimpleTools {
@Tool(name = "get_current_time",description = "获取指定时区的当前时间")
public String getCurrentTime(
@ToolParam(name = "timezone"。description = "时区名称，例如 'Asia/Shanghai'、'America/New_York'")
String timezone) {
try {
ZoneId zoneId = ZoneId.of;LocalDateTime now = LocalDateTime.now;话说回来，DateTimeFormatter formatter = DateTimeFormatter.ofPattern;return String.format);} catch {
return "Error: Invalid timezone. Try 'Asia/Shanghai' or 'America/New_York'";}
}
@Tool(name = "calculate",description = "计算简单的数学表达式")
public String calculate(
@ToolParam(name = "expression"。description = "要计算的数学表达式，例如 '1+2','4*5'")
String expression) {
try {
expression = expression.replaceAll;double result;
if ) {
String parts = expression.split;result = Double.parseDouble + Double.parseDouble;} else if ) {
String parts = expression.split;result = Double.parseDouble - Double.parseDouble;} else if ) {
String parts = expression.split;说起来，result = Double.parseDouble * Double.parseDouble;} else if ) {
String parts = expression.split;说起来，result = Double.parseDouble / Double.parseDouble;} else {
return "Error: Unsupported operation. Use +。-,*,or /"，}
return String.format;} catch {
return "Error: Invalid expression. Example: '1+2'";不过，}
}
@Tool(name = "search",description = "在网络上搜索信息")
public String search(
@ToolParam
String query) {
// 这里模拟搜索结果。实际项目中可以接入真实搜索 API
return "Search results for '" + query + "'\
"
+ ". Result about " + query + "\
"
+ ". More information on " + query;}
}
}

运行后效果：

1. 说到推理，需要获取北京时间。
2. A​gent 决定调用 #get_current_time# 工具，参数为 "Asia/Shanghai".
3. L​LM 接收到执行结果后将其组织成自然语言返回给使用者。按理说，

工具的返回类型

痛点：L​LM 对返回值类型不敏感。导致开发者经常手动转换 JSON、字符串等。框架已经帮你做好自动映射。怎么说呢，

The following return types are supported automatically:

// 直接返回字符串
@Tool
public String echo{
return "Echo: "+input;}
// 返回对象
@Tool
public Map getUser{
return Map.of;怎么说呢，}
// 返回 void
@Tool
public void log{
System.out.println;}
// 异步返回 Mono
@Tool
public Mono asyncTask{
return Mono.fromCallable -> ToolResultBlock.text);}

工具分组 & 元工具

痛点：M​any tools → prompt 超长、模型上下文受限；老实说，缺少分组机制让管理变得混乱。

You can group tools to keep prompts concise and let LLM activate/deactivate groups at runtime.

Toolkit toolkit = new Toolkit;// 注册到不同分组
toolkit.registration
.tool)
.group
.apply;toolkit.registration
.tool)
.group
.apply;不过，// 创建分组
toolkit.createToolGroup;toolkit.createToolGroup;// 注册元工具，让 Agent 能自行切换分组
toolkit.registerMetaTool;

The meta‑tool exposed to LLM is called #reset_equipped_tools#`. By invoking it,model can enable or disable specific groups,which greatly reduces amount of tool metadata sent in each request.

子 Agent 作为工具

.x 的 .registration.subAgent 在 仍可用。但新代码请用子 agent 程序 把子 agent spec 写到  workspace/subagents/.md ，主 agent 就能在推理时通过 agent_spawn  委派 —— 这是 Harness 的内置能力，不需要“把 agent 当工具注册”。详见第七章，

痛点： 想把专业领域模型当作“插件”来调⽤却不知该怎么包装；旧版 “sub‑agent as tool” 写法冗余且易出错。不过，

下面是兼容写法：

 ///.x : 把专家 Agent 注册为主 Agent 的工 具
Toolkit mainToolkit= new Toolkit;mainToolkit.registration
.subAgent -> expertA gent )
.apply;

从推荐写法来看，

 # workspace/subagents/data-analyst.md
---
description: 数据分析专家。当使用者要做统计分析、可视化、数据清洗时使用。说到model，openai:gpt-4o-mini
---
你是一个数据分析专家。请按以下流程工作：
1️⃣ 先用 read_file / grep_files 收集数据。其实，2️⃣ 做必要的统计与可视化。3️⃣ 给出业务结论，

主 agent 在推理时直接使用：

 agent_spawn agent_id="data-analyst" task="对2024年销售数据进行趋势分析"

框架会自动加载子 agent 并将其输出封装为 TOOL_RESULT 块回传给主 agent。

工具描述的关键性

> 痛点 ： LLM 根据模糊描述很容易选错或根本不选，用错误或冗余的信息浪费了 token 和算力。

• 明确功能边界 ： 说明该 tool 能做什么不能做什么。​​ ​
• 包含使用场景 ： 什么时候应该调用这个 tool。​​ ​​
• 参数说明清晰 ： 每个参数含义、格式、取值范围。其实，​​ ​

/ / 错误示例 / /    @ Tool     publicString doStuff{ …} ​​ ​​ / / 正确示例 / / @ Tool( name="get_wear",description= "获取指定城市当前天气信息。返回温度、湿度和天气状况。按理说，当使用者询问某地天气时使用此 tool。\" ) publicString getWear( @ ToolParam String city){ …按理说，} ​ ​ ​ ​ ​ ​ ​​​ ​​ ​​ ​ ​ ​​ ​ ​​​ ​​​ ​​​ ​ ​ ​ ​ ​ ​​​ ​​

实现细节小结 🚀

• * 建议先从最主要几 个 常 用 工具 入 手*。逐步 避免一次性声明太 多，导致 LLM 上下文溢出。• 保持 description 简洁且语义明确，便于模型快速匹配；• 利用 tool group 与 meta‑tool 来动态控制可见性；按理说，• 通过 workspace/tools.json 或 Middleware 完成细粒度权限控制；

End of answer

---