skills - ToolGatewaySkill 对接海量 Tool（或 MCP）

在 Solon AI 生态中，ToolGatewaySkill 是专门为大规模工具集（如成百上千个业务 API 或 MCP 工具）设计的网关组件。

相关认赖包：solon-ai-skill-toolgateway

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

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

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

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

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

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

3、应用示例

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

// 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。