Skip to content

Latest commit

 

History

History
62 lines (50 loc) · 3.45 KB

java-tools.md

File metadata and controls

62 lines (50 loc) · 3.45 KB

开发 Java @AiTool

Java Tool 开发

注解语义

注解字段 默认值 语义
@AiTool.name 方法名 稳定本地名;默认发布全名为 local.<name>
description 空 给模型的描述
readOnly false 是否只读
destructive false 是否具有破坏性
idempotent false 是否承诺幂等;不改变默认不重试
requireConfirmation false Browser HITL 提示;服务端不强制
permissions 空数组 交给宿主 ToolAccessPolicy 解释
@AiParam.value 空 参数描述
@AiParam.name 编译期形参名 建议始终显式填写
@AiParam.required false 只有显式 true 才进入 JSON Schema required

宿主若没有启用 Java 编译参数 -parameters,又省略 @AiParam.name,启动时会失败。正式接入应显式写 name。

示例

@Component
public class DeviceTools {

    @AiTool(
            name = "device_restart",
            description = "重启指定设备",
            destructive = true,
            idempotent = false,
            requireConfirmation = true,
            permissions = {"device:restart"})
    public DeviceView restart(
            @AiParam(name = "serial", value = "设备序列号", required = true)
            String serial,
            AiRequestContext context) {
        return deviceService.restart(
                serial,
                context.getUser().getUserId());
    }
}

上述注解最终发布为 local.device_restart。AiRequestContext 由服务器注入,不进入模型 inputSchema。不要把 userId、tenantId、roles 或 permissions 声明成模型参数。

Schema 边界

默认反射生成器支持 Java 基础类型、String、Enum、数组/集合、Map 和普通对象的有限 JSON Schema。未知类型、无法解析参数名、循环 Schema、重复 Tool 名、非法参数或额外参数会明确失败。生成的对象 Schema 使用 additionalProperties=false。

调用和重试

  • Starter 通过 Spring Bean/代理调用 Tool,保留 AOP、事务和方法安全语义;
  • Tool 默认不自动重试,即使标记 idempotent;
  • 失败分类只有两个通道:业务方法显式返回 ToolCallResult.ofError(...)(或返回值被规范化为 isError=true 的结果)是模型可继续推理的业务失败,HTTP 仍为 200;方法抛出的任何异常 都是未预期失败,完整详情只写服务端日志,对外以脱敏的 ToolExecutionException (500 TOOL_FAILED)终止本轮,后续模型调用为零。不要依赖“抛异常也算业务失败”的旧语义;
  • Browser ToolCallResult 必须精确包含字符串 toolCallId、字符串 content 和布尔 isError,且调用 ID 与请求一致;null ID、额外字段或宽松类型均按 MODEL_PROTOCOL_ERROR 终止;
  • Tool Adapter、Interceptor 或执行器 throw/Promise rejection 表示未预期基础设施或编程失败,会终止 Execution;需要交给模型理解的预期业务失败,必须在 Adapter/Interceptor 中显式转换为 ToolCallResult;
  • requireConfirmation 只是 Browser 交互层,不能替代服务端授权。