Solon AI 开发学习13 - chat - Tool的输入输出架构及生成类

1、Tool输出给 llm 的描述形态

这个形态下 parameters 属性是一个 jsonSchema 规范的结构。也就是工具的"输入架构"（mcp 里的叫法）

json 复制代码

{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气情况",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "根据用户提到的地点推测城市"
                }
            },
            "required": [
                "location"
            ],
            "additionalProperties": False
        },
        "strict": True
    }
}

2、Tool注册给 mcp 的描述形态

这个形态下多了 outputSchema （符合 jsonSchema 规范的输出架构）属性，且 parameters 属性变成了 inputSchema（可以与 outputSchema 呼应上）。

json 复制代码

{
    "name": "get_weather",
    "description": "获取指定城市的天气情况",
    "inputSchema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "根据用户提到的地点推测城市"
            }
        },
        "required": [
            "location"
        ],
        "additionalProperties": False
    },
    "outputSchema": {
        "type": "string"
    }
}

3、构建Tool的 outputSchema（输出架构）定义

（v3.2.2 后支持）

使用 FunctionToolDesc 描述工具时（即手动构建），通过 returnType 声明

java 复制代码

import org.noear.solon.ai.chat.tool.FunctionToolDesc;

FunctionToolDesc toolDesc = new FunctionToolDesc("get_weather")
    .description("获取指定城市的天气情况")
    .stringParamAdd("location", "根据用户提到的地点推测城市")
    .returnType(String.class)
    .doHandle(args -> {
        return "晴，24度"; // + weatherService.get(location);
    })

使用 MethodFunctionTool 描述工具时（即 @ToolMapping 注解函数构建），通过方法返回类型自动声明

java 复制代码

import org.noear.solon.annotation.Param;
import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint;

@McpServerEndpoint(sseEndpoint = "/mcp/sse")
public class Tools {
    @ToolMapping(description = "获取指定城市的天气情况")
    public String get_weather(@Param(name = "location", description = "根据用户提到的地点推测城市") String location) {
        return "晴，24度"; // + weatherService.get(location);
    }
}

如果返回的是实体结果时，还可以通过 @Param 注解增加描述

java 复制代码

import org.noear.solon.annotation.Param;
import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint;

public class UserInfo {
    @Param(description = "用户名")
    private String name;

    @Param(description = "年龄")
    private Integer age;

    @Param(description = "性别。0表示女，1表示男")
    private Integer gender;
}

@McpServerEndpoint(sseEndpoint = "/mcp/sse")
public class Tools {
    @Inject
    UserService userService;

    @ToolMapping(description = "获取用户信息")
    public UserInfo getUserInfo(@Param(description = "用户ID") Long userId) {
        return userService.getUser(userId);
    }
}

4、Tool 的 JsonSchema 生成类 ToolSchemaUtil

现有的Tool架构是由 ToolSchemaUtil 提供支持

方法	描述	备注
buildInputParams	构建 tool 的输出参数描述	支持 `@Body` 实体自动分解字段
buildInputSchema	构建 tool 输入架构
buildOutputSchema	构建 tool 输出架构
isIgnoreOutputSchema	检测 tool 需要乎略的输出架构	比如单值类型

createSchema	生成一个类型的 JsonSchema	通用方法

addBodyDetector	添加主体注解探测器	第三方框架使用时，可用它扩展
addParamResolver	添加参数注解分析器	同上
addNodeDescribe	添加节点描述处理	同上