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

> "我们希望"客服 agent"只能查订单和物流，"财务 agent"只能用支付相关工具。1.x 时代我们在 Java 端写一堆条件判断；2.0 用 `workspace/tools.json` + `toolFilter` 把这套规则**配置化**：新增一个角色只需要在 JSON 里加一段，不需要改 Java 代码。"
>
> 本章你将学到：如何写 `workspace/tools.json`、如何用 `toolFilter` 限定工具集、如何让 subagent 继承主 agent 的工具 / 屏蔽危险工具。

## 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` | 运行时可改，多环境差异化 |

> **生产建议**：基础工具集放 Java 端（`Toolkit`），角色级过滤放 `toolsConfig`（Java 端）或 `tools.json`（文件端）。

## 13.2 第一个 `tools.json`

```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 时默认关闭**——需要显式开：

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

> 工具类的 class 必须在 classpath 里能找到（通过反射 `Class.forName(...)` 实例化），所以 `demo.tools.OrderTool` 这种业务类要保证在 agent 进程的 classpath 上。

## 13.3 角色级 `toolFilter`：allow / deny

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

```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/<id>.md` 里声明自己的工具集：

```markdown
# customer_service.md
id: customer_service
description: 客服 agent；只能查订单和物流，不能退款
toolsFile: customer_service.tools.json
sysPrompt: |
  你是客服，只能查订单和物流，不能直接退款。
  如需退款，转人工。
```

`workspace/subagents/customer_service.tools.json`：

```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` 对象：

```java
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 双保险：

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

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

```java
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 完整可运行示例

**这个例子在演示什么？**

> 我们注册 3 个工具：`query_order`（查订单）、`query_logistics`（查物流）、`refund_order`（退款）。然后创建两个 agent：
>
> - **客服 agent**：`deny` 屏蔽 `refund_order` → 只能查订单和物流，不能退款
> - **财务 agent**：`allow` 只放行 `refund_order` → 只能退款，看不到查询工具
>
> 同一套工具，两个角色两个视野。新增角色只需要改 `ToolsConfig`，不改 Java 代码。

```java
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. 全部工具注册到同一个 Toolkit
        Toolkit 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 工具
        // 问财务"退款"——正常处理
    }
}
```

> **关键**：`ToolsConfig` 的 `allow`/`deny` 在 `HarnessAgent.build()` 里被 `ToolFilter.apply()` 执行——从 `Toolkit` 中**物理删除**对应工具。LLM 的 prompt 里根本不会出现被屏蔽工具的描述，不存在"知道但不能用"的半吊子状态。

## 13.8 本章小结

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



"我们希望"客服 agent"只能查订单和物流，"财务 agent"只能用支付相关工具。1.x 时代我们在 Java 端写一堆条件判断；2.0 用 workspace/tools.json + toolFilter 把这套规则配置化：新增一个角色只需要在 JSON 里加一段，不需要改 Java 代码。"

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

工具分组 — Toolkit 注册全量工具，ToolsConfig 按 allow/deny 精确匹配过滤，同一套工具两个角色两个视野。

编程语言

开发工具

后端

本文介绍如何通过workspace/tools.json和toolFilter实现角色化工具权限控制，让客服只能查订单物流，财务仅能处理退款。详细讲解JSON配置、工具过滤规则、子代理继承机制，并推荐生产环境四层权限防线，实现安全灵活的工具管理。

代码解释

JSON

Java

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【AgentScope Java新手村系列】（13）工具分组-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐