注解工具接入

本页阅读位置

完成第一轮对话后，按当前业务需求深入。Spring 常规声明优先使用 RegistrationManifest 与注解；本页的底层 register / publish 或直连方法供协议细化与兼容集成参考。

Java 业务类

@AgentTool(name="query-device", description="查询监测设备信息")
public class QueryDeviceTool {
    private final DeviceService devices;
    public QueryDeviceTool(DeviceService devices) { this.devices = devices; }
    public record Input(String id) {}
    public record Output(String id, String name) {}
    public Output execute(Input input, ToolContext context) {
        return devices.getAuthorized(input.id(), context.userId(), context.tenantId());
    }
}

使用业务容器已创建的实例，不要再次 new 一个缺少依赖的工具。类必须公开且只有一个公开 execute 方法，可接受 Input 或 Input, ToolContext。输入输出使用 Java record，类型约束遵循 RecordSchema。不支持的类型、重载、静态入口会在适配时失败。

注册与绑定

var tool = AnnotatedTool.from(queryDeviceBean,
    URI.create("https://business.example.com/agent/tools"), "BUSINESS_CALLBACK_KEY");
tool.bind(callbackHandler);
tool.register(appAdminClient).toCompletableFuture().join();
appAdminClient.publish("tools", tool.name(), tool.version()).toCompletableFuture().join();

callbackHandler 是既有 CallbackHandler，仍需挂载到业务 HTTP 服务并使用持久目录。secretRef 是平台侧环境密钥名称，回调服务读取对应的真实密钥。部署者需配置 origin 白名单、secret origin 与所属应用授权；不要把示例域名当成已部署服务。

register 只创建草稿，publish 显式发布。发布后再把该工具的准确版本加入 Agent allowedTools；注解不会自动授予 Agent 权限。name 要符合平台小写连字符命名，示例使用 query-device；原设想 queryDevice 目前不是合法平台标识。version 默认 1.0.0，定义变更必须创建新版本。

Kotlin 挂起业务

@JvmRecord data class QueryDeviceInput(val id: String)
@JvmRecord data class DeviceView(val id: String, val name: String)

@AgentTool(name = "query-device", description = "查询监测设备信息")
class QueryDeviceTool(private val devices: DeviceService) {
    suspend fun execute(input: QueryDeviceInput, context: ToolContext): DeviceView =
        devices.getAuthorized(input.id, context.userId(), context.tenantId())
}

val tool = annotatedTool(queryDeviceBean, URI("https://business.example.com/agent/tools"), "BUSINESS_CALLBACK_KEY")
tool.bind(callbackHandler)
tool.register(appAdminClient).awaitResult()
appAdminClient.publish("tools", tool.name(), tool.version()).awaitResult()

导入 dev.sparktide.sdk.* 和 dev.sparktide.sdk.kotlin.*。输入输出支持普通 data class 和 @JvmRecord，包含默认参数、可空字段省略与嵌套数据类。suspend 适配在业务 HTTP 回调线程等待，遵守平台 deadline；没有 deadline 时等待上限为 60 秒。协程取消不能撤销已提交的外部业务操作。

身份、权限和失败结果

ToolContext 的 userId、tenantId 来自已认证的平台回调，不从用户传入 Context 获取。业务服务仍须校验设备或文档的实际访问权限。默认 effect 为 READ；修改业务数据必须声明 WRITE 或 DANGEROUS，禁止把写操作标为只读来绕过审批。roles 默认 USER、APP_ADMIN，可以收紧。

回调复用持久幂等账本。业务异常或超时后不自动重新执行；由业务系统查明结果，再按平台工具执行账本流程核对。保留相同账本路径，不要通过清空账本解除未知状态。

容器扫描、普通 Kotlin data class 和注解知识 Provider 的配置见 知识提供器与自动注册。

文档来源与验证记录

日期：2026-09-29；状态：已实现并通过 HTTP 回调测试；责任人：项目维护者。来源：AgentTool、AnnotatedTool、AnnotatedTools 和 CallbackHandler。