把业务接口变成工具

工具让智能体调用业务系统中的受控操作。一个工具对应一个明确职责，使用封闭的输入输出结构，不把任意 URL、SQL 或脚本执行权限交给模型。

接入步骤

1. 在后台写公开业务类，用 @AgentTool 标注，并作为 Spring Bean；Starter 封装回调。
2. 配置平台可访问的回调 origin、独立密钥与业务账本。
3. 在智能体声明中加入精确版本引用；Starter 合并注解工具和 RegistrationManifest。
4. 开发预检后同步；生产显式发布。
5. 用真实授权用户验证工具结果和失败路径。

先跟着教程添加一个 READ 工具，再查Java / Kotlin 注解签名。以下 JSON 解释底层字段，Spring 接入不需要自行生成 Schema 或手写注册 HTTP。

示例定义

{
  "description":"按订单号查询当前用户有权访问的订单状态",
  "endpoint":"https://business.example.com/agent/order-lookup",
  "secretRef":"TOOLS_API_KEY",
  "effect":"READ",
  "roles":["USER","APP_ADMIN"],
  "inputSchema":{"type":"object","properties":{"orderId":{"type":"string","minLength":1}},"required":["orderId"],"additionalProperties":false},
  "outputSchema":{"type":"object","properties":{"status":{"type":"string"}},"required":["status"],"additionalProperties":false}
}

回调返回 {"status":"已发货"}，不要外包为 {data:{...}}，除非 outputSchema 明确这样定义。

选择操作类型

effect	使用场景	执行要求
READ	查询数据	仍须校验用户和租户可见范围
COMPUTE	不持久写入的计算	控制输入和计算成本
WRITE	修改业务状态	持久幂等和业务事务校验
DANGEROUS	需要用户确认的重要操作	平台先保存确认记录，批准后调用

WRITE 不等于自动人工审批；需要确认的操作必须标记 DANGEROUS。前端展示待确认参数，不能修改已经保存的调用参数。

幂等与未知结果

平台传递 callId 和同值 Idempotency-Key，不自动重试业务写请求。回调保存已执行结果，重复同调用返回原结果；超时或连接中断并不能证明业务没有执行。

Java CallbackHandler 提供持久账本基础，使用方法见工具回调。它不替代业务数据库事务或跨实例幂等设计。

健康租约

远程能力可设置 leaseRequired:true，由后端实例定期续租。至少一个租约有效才允许运行，TTL 为 10–300 秒。租约不修改 endpoint，也不提供服务发现；多个后端实例由你配置的负载均衡处理。