skills - RestApiSkill 对接海量 WebAPI

RestApiSkill 是 Solon AI 生态中连接“大模型意图”与“传统 REST 服务”的智能桥梁。它能够自动解析 OpenAPI (Swagger) 定义，并将其转化为 AI 智能体（Agent）可理解、可调用的结构化技能。

此技能，可以很好的激活海量现有 WebApi

相关依赖包： solon-ai-skill-restapi

1、核心特性

• 多源 API 整合：支持从多个不同的 Swagger 节点（http 或 classpath）并行加载接口。
• 三阶段动态发现：内置阈值切换机制，自动解决接口过多导致的 Token 溢出问题。
• 全自动代理：AI 仅需下达意图，由网关自动完成 Path 替换、Query/Body 序列化及 Header 注入。
• 上下文保护：内置响应结果截断（默认 8000 字符），防止庞大的业务数据撑爆 AI 上下文。

2、应用示例

通过以下配置，你可以让智能体瞬间具备操作多个微服务系统的能力：

// 1. 初始化 Skill
RestApiSkill apiSkill = new RestApiSkill()
        .dynamicThreshold(5)  // 超过 5 个接口开启清单模式
        .searchThreshold(50)  // 超过 50 个接口开启搜索模式
        .maxContextLength(10000) // 结果截断长度
        .defaultAuthenticator((http, tool) -> {
             http.header("Authorization", "Bearer your-token"); // 全局认证配置
        });

// 2. 挂载多个业务模块的 API (支持 http 或 本地资源)
apiSkill.addApi("http://order-service:8081/v3/api-docs", "http://order-service:8081");
apiSkill.addApi("classpath:swagger/user-api.json", "http://user-service:8082");

// 3. 构建智能体
ReActAgent agent = ReActAgent.of(LlmUtil.getChatModel())
        .role("高级业务助理")
        .instruction("请优先使用提供的业务 API 解决问题，不要猜测接口参数。")
        .defaultSkillAdd(apiSkill)
        .build();

// 4. 自然语言触发（Agent 会自动选择 search_apis -> get_api_detail -> call_api 流程）
agent.prompt("查询张三名下的所有订单，并告诉我最近一笔的物流状态。");

3、三阶段动态发现机制

为了平衡“易用性”与“Token 成本”，RestApiSkill 会根据接口总数自动切换模式：

4、内置管理工具说明

AI 在处理任务时，会根据当前模式自动调用以下内部工具：

• search_apis(keyword)：在海量 API 库中通过多关键词（空格分隔）模糊搜索匹配的接口。
• get_api_detail(api_name)：获取指定接口的参数 Schema（含 Header, Path, Query, Body）及返回值定义。
• call_api(...)：执行调用。支持复杂的路径参数替换（如 /user/{id}）及多部分（Multipart）提交。

5、注意事项

• 接口唯一性：不同数据源加载的接口，其 OperationId (API 名称) 不能重复，网关会将其统一转为小写存储。
• 路径占位符：确保 Swagger 定义中的路径参数使用 {name} 格式，网关会自动完成 URLEncoder 编码替换。
• 过时接口：代码会自动忽略 Swagger 中标记为 @Deprecated 的接口，保持 Agent 技能树的整洁。