| 注解字段 | 默认值 | 语义 |
|---|---|---|
@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 声明成模型参数。
默认反射生成器支持 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 与请求一致;nullID、额外字段或宽松类型均按MODEL_PROTOCOL_ERROR终止; - Tool Adapter、Interceptor 或执行器 throw/Promise rejection 表示未预期基础设施或编程失败,会终止 Execution;需要交给模型理解的预期业务失败,必须在 Adapter/Interceptor 中显式转换为
ToolCallResult; requireConfirmation只是 Browser 交互层,不能替代服务端授权。