在 Solon AI 生态中，`ToolGatewaySkill` 是专门为大规模工具集（如成百上千个业务 API 或 MCP 工具）设计的网关组件。提供渐进式加载支持。

相关认赖包：[solon-ai-skill-toolgateway](/article/1395)


### 1、 为什么要使用工具网关？

当 LLM 挂载的工具过多时，会面临两个核心痛点：

* 上下文溢出：几百个工具的 JSON Schema 会迅速吃掉 Token 额度。
* 逻辑混淆：工具过多会导致模型在选择工具时准确率大幅下降。

ToolGatewaySkill 通过内置的三阶段动态路由机制，确保无论工具库多大，交付给 LLM 的上下文始终精简受控。

### 2、 核心机制：三阶段自动切换

网关会根据已添加工具的总数，自动在以下三种模式间切换：




| 模式名称 | 触发阈值 | 对 LLM 的表现 | 机制说明 |
| -------- | -------- | -------- | -------- |
| FULL (全量)     | 数量 `<= 8`     | 直接调用     |  像普通技能一样，所有工具定义直接平铺在上下文。  |
| DYNAMIC (清单)     | `8 <` 数量 `<= 80`     | 清单选定     |  上下文只展示工具名和简要描述。AI 需先通过 get_tool_detail 查参数。  |
| SEARCH (搜索)     | 数量 `> 80`     | 强制检索     |  清单也被折叠。AI 必须先调用 search_tools 才能发现可用工具。  |



### 3、应用示例

你可以将现有的业务工具、MCP 客户端或自定义技能直接注册到网关中。

```java
// 1. 初始化网关并添加工具（支持单工具或工具提供者）
ToolGatewaySkill gatewaySkill = new ToolGatewaySkill()
        .dynamicThreshold(10) // 可选：自定义平铺阈值
        .searchThreshold(100); // 可选：自定义搜索阈值

gatewaySkill.addTool(mcpClient); // 挂载 MCP 协议工具
gatewaySkill.addTool(dbToolProvider); // 挂载数据库工具

// 2. 构建 ReAct 智能体
ReActAgent agent = ReActAgent.of(chatModel) //或 ChatModel 等...
        .role("数据分析专家")
        .instruction("你负责分析业务系统数据。若无法直接看到工具，请先搜索。")
        .defaultSkillAdd(gatewaySkill)
        .build();

// 3. 执行任务
// 如果工具很多，Agent 会自动执行：search_tools -> get_tool_detail -> call_tool
String response = agent.prompt("查询去年双十一期间的所有异常订单。")
       .call()
       .getContent();
```


### 4、 网关内置管理工具


当处于非 FULL 模式时，网关会向 AI 暴露以下管理工具，用于实现动态路由：

* `search_tools(keyword)`：通过关键词（支持多词空格分隔）在海量库中快速锁定目标工具。
* `get_tool_detail(tool_name)`：按需拉取特定工具的 JSON Schema 参数定义，按需消耗 Token。
* `call_tool(tool_name, tool_args)`：代理执行指令。网关负责参数映射与异常捕获，确保执行环境稳定。


### 5、 最佳实践建议

* 描述很重要：在 ToolMapping 或 MCP 定义中，务必提供清晰准确的 description，因为这是模式切换后网关搜索和清单展示的核心依据。
* 命名防冲突：网关内不允许存在同名工具（忽略大小写）。如果挂载了多个来源，建议在注册前通过前缀进行区分。
* 结合 ExpertSkill：通常建议将 ToolGatewaySkill（负责业务 API 调用）与 ExpertSkill（负责阅读项目规范）配合使用，打造具备“读规约”+“调接口”能力的完整 Agent。