6. 添加工具与知识

这是可选扩展。 先确认第 5 步普通聊天成功。本步把助手从“只能回答文字”变成“可以查询业务数据、引用内部资料”。两种能力可以分别接入。

1. 先准备独立回调

后台 SDK 会为工具和知识启动回调服务；平台需要能访问它。教程第 1 步已经给平台配置了 http://127.0.0.1:8099 和 TUTORIAL_CALLBACK_KEY，并限定 tutorial 应用使用该密钥。

在后台 application.yml 的 已有 sparktide 节点中追加以下字段，不要新增第二个同名顶层节点：

  public-base-url: http://127.0.0.1:8099
  bind-address: 127.0.0.1
  callback-port: 8099
  callback-token: ${TUTORIAL_CALLBACK_KEY}
  secret-ref: TUTORIAL_CALLBACK_KEY
  ledger-directory: ./data/ledger

8091 给浏览器访问业务 API；8099 给底座调用后台能力，二者用途不同。容器 / 多机部署使用底座能访问的地址，详见工具回调。

2. 添加一个只读设备查询工具

创建 src/main/java/tutorial/DeviceTool.java：

package tutorial;
import dev.sparktide.sdk.AgentTool;
import dev.sparktide.sdk.ToolContext;
import org.springframework.stereotype.Component;

@Component
@AgentTool(name="device-status", description="查询示例设备的运行状态")
public class DeviceTool {
    public record Input(String deviceId) {}
    public record Output(String deviceId, String state) {}
    public Output execute(Input input, ToolContext context) {
        if (!"tutorial-tenant".equals(context.tenantId()))
            throw new IllegalArgumentException("Tenant denied");
        if (!"pump-01".equals(input.deviceId()))
            throw new IllegalArgumentException("Unknown device");
        return new Output(input.deviceId(), "RUNNING");
    }
}

这是教学用内存数据；实际项目替换为按当前用户和租户授权的业务查询。默认 effect=READ；写操作设为 WRITE，需要平台确认的操作设为 DANGEROUS，只有 DANGEROUS 自动等待确认。

3. 添加一个知识 Provider

创建 src/main/java/tutorial/RunbookKnowledge.java：

package tutorial;
import dev.sparktide.sdk.*;
import org.springframework.stereotype.Component;
import java.util.List;

@Component
@AgentKnowledge(name="runbook", description="示例泵设备运维手册")
public class RunbookKnowledge implements KnowledgeProvider {
    public KnowledgeResult retrieve(KnowledgeQuery query, KnowledgeContext context) {
        if (!"tutorial-tenant".equals(context.tenantId()))
            return new KnowledgeResult(List.of());
        return new KnowledgeResult(List.of(new KnowledgeDocument(
            "pump-guide", "运行状态正常时，每日记录入口压力与轴承温度。",
            "泵日常检查", "", "")));
    }
}

这里只演示协议与租户边界，实际返回当前用户可访问的检索片段。接已有知识系统读外部知识与权限过滤；上传文件和托管资料读知识入门。

4. 引用能力并发布新智能体版本

工具 / 知识注解的版本默认 1.0.0。在 ModelConfiguration 中保留提供商、模型、绑定与 profile 的 v="1.0.0"，只替换 agent 声明：

ModelDeclarations.agent("main", "1.1.0",
    "你是设备助手。设备状态必须查询工具；运维建议检索手册并给出引用。",
    "profile", "1.0.0",
    List.of(new ReleaseBundle.Entry("device-status", "1.0.0")),
    List.of(new ReleaseBundle.Entry("runbook", "1.0.0")))

由于原默认入口已存在，教程启动保持 default-agent.version: 1.0.0，不尝试在自动同步中覆盖已有默认入口。重启后台将原子发布新增工具、知识和 main/1.1.0。

在独立发布终端 tutorial/backend 中加载业务管理凭据，调用示例封装的 SDK 命令切换默认入口：

& '..\scripts\use-env.ps1' '..\.local\business.env'
.\gradlew.bat selectAgent -PagentVersion=1.1.0

命令读取当前应用修订，并通过 PlatformClient.defaultAgent 显式切换；发生修订冲突时停止检查，不盲目重试。然后将后台 YAML 的 default-agent.version 改为 1.1.0，使后续启动与新入口一致。

回到原 ChatPanel，新建会话，输入“查询 pump-01 的状态，给出日常检查建议”。前端无需改 API 方法或重新封装任何接口。回退时同一命令指定仍已发布的 1.0.0，并恢复 YAML 默认版本；原工具和知识版本保留。

检查点

工具回调得到 pump-01 / RUNNING；检索回调得到手册片段；事件中有工具与引用信息。模型决定实际调用顺序，业务中需使用真实模型验证提示词和引用质量。首次对话无工具时成功，并不证明这一步的工具调用能力可用。

Java / Kotlin 注解差异、业务对象注入、错误和幂等规则见注解工具与知识自动注册。