chat - 工具（Tool）接口与属性

v3.2.0 后，原 Function 概念改为 Tool 概念。新的调整，与 MCP 里的工具可以更好的对应起来。

Tool call（或 Function call）能够让大语言模型在生成时，“按需”调用外部的工具，进而连接外部的数据和系统。通过定义一组函数作为模型可访问的工具（也叫函数工具），并根据对话历史在适当的时候使用它们。然后在应用端执行这些函数，并将结果反馈给模型。

可以实现最新的数据状态（比如，联网查询时实天气）或者指令交互（比如，做运维操作）。是 AI 交互系统的基础技术。

相关接口：

1、工具的主要属性与处理方法

（1）inputSchema / outputSchema 规范要求

原则上，支持任意参数类型（jsonSchema 能描述的类型）。尽量，使用基础类型和数据实体类型组合描述；像 Socket、Session 这类的不适合。

（2）关于 returnDirect （直接返回）的作用

默认状态时，Tool 处理的结果是交给大模型，大模型加工后再返回。通过 returnDirect 可以跳过大模型直接返回。

• returnDirect=false（默认）

user -> llm -> tool -> llm -> user

• returnDirect=true

user -> llm -> tool -> user

MCP 协议目前不支持这个特性透传。但当 server 和 client 都是 solon-ai-mcp 时，可支持此特性透传。

2、FunctionTool （函数工具）接口参考

工具，目前主要是指函数工具 FunctionTool（未来可能有不同类型的工具）。接口需要声明工具的类型和名字，描述，输入架构（由输入参数的名字、描述、类型，组合构成），及以处理方法。

//工具接口（未来可能会有别的类型）
public interface Tool {
    //工具类型
    String type();
}

//函数工具接口
public interface FunctionTool extends Tool {
    //工具类型
    default String type() {
        return "function";
    }

    //名字
    String name();

    //标题
     String title() ;

    //描述
    String description();

    //带有元信息的描述（用于注入到模型）
    default String descriptionAndMeta() { ... }

    //元信息
    default Map<String, Object> meta() { ... }

    default void metaPut(String key, Object value) {  }

    //是否直接返回给调用者
    boolean returnDirect();

    //输入架构
    String inputSchema();

    //输出架构
    default String outputSchema() { ... }

    //处理
    String handle(Map<String, Object> args) throws Throwable;

    //异步处理
    default CompletableFuture<String> handleAsync(Map<String, Object> args) { ... }
}

3、ToolMapping 工具映射注解参考

开发时，也可以使用注解简化工具声明（不需要 Bean 容器驱动）：

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ToolMapping {
    //名字
    String name() default "";

    //标题
    String title() default "";

    //描述
    String description();

    //元数据（json）
    String meta() default "{}";

    //是否直接返回给调用者
    boolean returnDirect() default false;

    //结果转换器
    Class<? extends ToolCallResultConverter> resultConverter() default ToolCallResultConverterDefault.class;
}