harness - OpenAPI 业务接口接入

马具可以把现有的 HTTP 业务接口（OpenAPI 文档）接入为 Agent 可调用的工具，让 Agent 直接调用你的业务系统。接入以 docUrl（OpenAPI 文档地址）为唯一标识，支持 OpenAPI v2 / v3 文档。

1、开启 OpenAPI 工具权限

OpenAPI 接入属于私域工具（工具名为 openapi），使用前需要给 Agent 授权：

// 方式一：通过枚举授权
HarnessEngine engine = HarnessEngine.of("work", ".soloncode/")
        .sessionProvider(sessionProvider)
        .toolsAdd(ToolPermission.TOOL_RESTAPI)     // 开启 restapi 工具权限（枚举名）
        .build();

// 方式二：运行时动态授权
engine.allowTool("openapi");                      // 使用实际工具名

注：ToolPermission.TOOL_RESTAPI 的枚举名为 restapi，但在 AgentFactory 的工具注册中实际匹配的工具名为 openapi。使用 ** 通配符展开时自动包含 openapi。如需手动指定工具名，请使用 openapi。

2、构建期静态注册

HarnessEngine engine = HarnessEngine.of("work", ".soloncode/")
        .sessionProvider(sessionProvider)
        .toolsAdd(ToolPermission.TOOL_RESTAPI)        // 开启工具权限
        .apiServerAdd("orders", new ApiSource().then(s -> {
            s.setDocUrl("https://api.example.com/v3/api-docs");  // OpenAPI 文档地址（唯一标识）
            s.setApiBaseUrl("https://api.example.com");          // 接口基地址
        }))
        .build();

ApiSource 也可用标准 setter 逐项设置：

ApiSource source = new ApiSource();
source.setDocUrl("https://api.example.com/v3/api-docs");
source.setApiBaseUrl("https://api.example.com");
source.addHeaderVar("Authorization", "Bearer ${token}");   // 透传请求头
source.addAllowedTool("getOrder");                          // 只暴露指定接口

3、ApiSource 字段说明

接口工具的暴露由 allowedTools / disallowedTools 共同裁剪：先取白名单（为空则全取），再剔除黑名单。

4、运行时动态管理

engine.addApiServer(apiSource);          // 添加（以 docUrl 为标识）
engine.getApiServer(docUrl);             // 获取 ApiSourceClient
engine.refreshApiServer(docUrl);         // 刷新（权限/文档变更后）
engine.removeApiServer(docUrl);          // 移除
engine.getApiServers();                  // 全部 API 源

ApiSourceClient 可查看该源解析出的接口工具：

ApiSourceClient client = engine.getApiServer(docUrl);
client.getTools();             // 全部接口工具
client.getToolsActivated();    // 经白/黑名单裁剪后实际生效的工具

5、说明

• 工具权限：OpenAPI 接入需授予 TOOL_RESTAPI（枚举名 restapi），实际注册到 Agent 的工具名为 openapi。授权方式见 《harness - 配置参考》。
• OpenAPI 工具由 OpenApiGatewayTalent 统一网关管理，重试次数由 apiRetries（默认 3）控制。
• 动态注册都会同步到引擎配置中，并即时对后续会话生效。
• MCP 接入见 《harness - MCP 服务接入》，LSP 接入见 《harness - LSP 服务接入》。