AgentScope Java新手村系列（13）工具分组

第十三章 工具分组：workspace/tools.json toolFilter，按角色配置化限定工具

13.1 工具分组的两种方式

2.0 提供两套"工具分组"机制，可以单独用，也可以组合：

方式	配置位置	适用场景
Java 端 Toolkit	HarnessAgent.builder().toolkit(toolkit)	代码定义工具，编译即固定
Java 端 toolsConfig	HarnessAgent.builder().toolsConfig(config)	程序化 allow/deny，无需 JSON 文件
workspace tools.json	workspace/tools.json	运行时可改，多环境差异化

13.2 第一个 tools.json

{ "tools": [{ "name": "query_order","class": "demo.tools.OrderTool","description": "查订单"},{ "name": "query_logistics","class": "demo.tools.LogisticsTool","description": "查物流"},{ "name": "refund_order","class": "demo.tools.RefundTool","description": "退款"}]}

HarnessAgent.builder().workspace(...) 启动时会自动扫描 workspace/tools.json 并把工具注册进 agent。但不传 classpath 时默认关闭——需要显式开：

HarnessAgent agent = HarnessAgent.builder()....workspace(Path.of("./workspace")).loadWorkspaceTools(true)// 2.0 新增.build();

13.3 角色级 toolFilter：allow / deny

一个 tools.json 可以同时定义工具列表和可见性规则：

{ "tools": [{"name": "query_order", "class": "demo.tools.OrderTool" },{"name": "query_logistics", "class": "demo.tools.LogisticsTool" },{"name": "refund_order","class": "demo.tools.RefundTool" }],"toolFilter": { "allow": ["query_order", "query_logistics"],"deny":["refund_order"]}}

行为：

allow 白名单模式：只放行名字精确匹配的工具；其他一律不可见 deny 黑名单模式：名字匹配的工具被移除；其他都可见 allow 和 deny 同时存在：deny 优先（先 allow 再 deny） 注意：使用精确工具名匹配，不支持通配符

HarnessAgent 启动时按 toolFilter 把工具列表过滤后再交给 LLM——LLM 看不到的工具连描述都不会出现在 prompt 里，避免"模型想调却调不到"。

13.4 给 subagent 单独配置 tools.json

每个 subagent 可以在 workspace/subagents/.md 里声明自己的工具集：

# customer_service.mdid: customer_servicedescription: 客服 agent；只能查订单和物流，不能退款toolsFile: customer_service.tools.jsonsysPrompt: |你是客服，只能查订单和物流，不能直接退款。如需退款，转人工。

workspace/subagents/customer_service.tools.json：

{ "tools": [{"name": "query_order", "class": "demo.tools.OrderTool" },{"name": "query_logistics", "class": "demo.tools.LogisticsTool" }],"toolFilter": { "deny": ["refund_order"]}}

13.5 在 Java 端过滤

不写 JSON 也行——直接用 ToolsConfig 对象：

ToolsConfig config = new ToolsConfig();config.setAllow(List.of("query_order", "query_logistics"));config.setDeny(List.of("refund_order"));HarnessAgent agent = HarnessAgent.builder()....toolsConfig(config).build();

ToolsConfig 与 tools.json 里的 toolFilter 字段语义完全一致。

13.6 工具权限的"四层防线"

生产环境推荐工具分组 Permission 双保险：

第 1 层：工具注册（class 必须在 classpath）第 2 层：toolFilter（allow / deny 精确匹配）第 3 层：Permission rule（运行时再校验一次）第 4 层：Middleware onModelCall / onActing（埋点 / 限流）

例：想让"退款"工具运行时必须经过人审批：

PermissionContextState perms = PermissionContextState.builder().mode(PermissionMode.ACCEPT_EDITS).addAskRule("refund_order",new PermissionRule("refund_order", null, PermissionBehavior.ASK, "userSettings")).build();HarnessAgent agent = HarnessAgent.builder().permissionContext(perms).build();

即使 LLM 想调 refund_order，Permission 也会拦下来问用户。

13.7 完整可运行示例

这个例子在演示什么？

import io.agentscope.core.tool.Tool;import io.agentscope.core.tool.Toolkit;import io.agentscope.harness.agent.tools.ToolsConfig;import io.agentscope.harness.HarnessAgent;import java.util.List;public class Chapter13_ToolFilter { // 业务工具类：@Tool 注解标记方法名即工具名public static class OrderTools { @Tool(name = "query_order", description = "查询订单状态和详情")public String queryOrder(String orderId) { return "订单 " orderId "：已发货。";}}public static class LogisticsTools { @Tool(name = "query_logistics", description = "查询物流轨迹")public String queryLogistics(String trackingId) { return "物流 " trackingId "：快件在北京分拣中心。";}}public static class RefundTools { @Tool(name = "refund_order", description = "处理订单退款")public String refundOrder(String orderId) { return "订单 " orderId " 退款已处理。";}}public static void main(String[] args) { // 1. 全部工具注册到同一个 ToolkitToolkit baseToolkit = new Toolkit();baseToolkit.registerTool(new OrderTools());baseToolkit.registerTool(new LogisticsTools());baseToolkit.registerTool(new RefundTools());// 2. 客服 agent：deny "refund_order" — 看不到退款工具ToolsConfig csConfig = new ToolsConfig();csConfig.setDeny(List.of("refund_order"));HarnessAgent customerService = HarnessAgent.builder().name("customer_service").sysPrompt("你是客服，只能查订单和物流。不能退款，如需退款请转人工。").model(model()).workspace(Path.of("./workspace")).toolkit(baseToolkit).toolsConfig(csConfig).build();// 3. 财务 agent：allow "refund_order" — 只能看到退款工具ToolsConfig finConfig = new ToolsConfig();finConfig.setAllow(List.of("refund_order"));HarnessAgent finance = HarnessAgent.builder().name("finance").sysPrompt("你是财务，只处理退款。").model(model()).workspace(Path.of("./workspace")).toolkit(baseToolkit).toolsConfig(finConfig).build();// 问客服"订单 123 的状态"——能答// 问客服"退款"——会说"请转人工"// 问财务"订单 123 的状态"——看不到 query 工具// 问财务"退款"——正常处理}}

13.8 本章小结

workspace/tools.json 让工具配置离开 Java 代码，运行时可改。 toolFilter 用 allow / deny 精确工具名限定角色可调工具。 subagent 可声明自己的 toolsFile 单独配工具集。 工具权限推荐四层防线：注册 → toolFilter → Permission → Middleware。