工具与远程服务回调

远程能力通过平台发出的 POST JSON 请求调用，endpoint 是完整地址，不自动追加路径。平台的出站白名单和密钥绑定必须先配置。

Java 类型化工具

下例把已有订单服务接到 HTTP 回调。业务 OrderService 必须根据传入用户和租户执行真实权限校验与查询，不应返回跨租户数据。

import dev.sparktide.sdk.CallbackHandler;
import dev.sparktide.sdk.RecordSchema;
import com.sun.net.httpserver.HttpServer;
import java.net.InetSocketAddress;
import java.nio.file.Path;
import java.io.IOException;
import java.util.Map;
import java.util.function.Supplier;

public final class OrderToolServer {
    public record OrderInput(String orderId) {}
    public record OrderOutput(String status) {}
    public interface OrderService {
        String statusFor(String subjectId, String tenantId, String orderId);
    }
    public static HttpServer start(OrderService orders, Supplier<String> callbackToken,
                                   Path persistentLedger, InetSocketAddress address) throws IOException {
        var handler = new CallbackHandler("customer-service", callbackToken, persistentLedger);
        handler.registerTyped("order-lookup", "1.0.0", OrderInput.class, OrderOutput.class,
            (context, input) -> new OrderOutput(orders.statusFor(
                (String) context.get("subjectId"), (String) context.get("tenantId"), input.orderId())));
        var server = HttpServer.create(address, 0);
        server.createContext("/agent/order-lookup", handler);
        server.start();
        return server; // 在业务服务停止时调用 server.stop(0)。
    }
    public static Map<String, Object> inputSchema() { return RecordSchema.of(OrderInput.class); }
    public static Map<String, Object> outputSchema() { return RecordSchema.of(OrderOutput.class); }
}

通过 register API 把上述 Schema、实际 HTTPS endpoint、effect 和 roles 注册到平台。HttpServer 由业务服务管理 TLS/网关和网络暴露，CallbackHandler 不会替你配置公网访问。

RecordSchema 支持 Java record、字符串、布尔、数字、枚举、嵌套 record、List。@SchemaOptional 表示可省略；显式 null 不支持。任意类、无限递归与 JSON 非安全整数会被拒绝。

工具请求与响应

{
  "appId":"customer-service","subjectId":"user-42","tenantId":"team-a",
  "runId":"run_example","traceId":"trace_example","toolId":"order-lookup",
  "version":"1.0.0","callId":"call_example","arguments":{"orderId":"order-1001"},
  "deadline":1893456000000
}

请求头包含 Authorization: Bearer <secretRef解析值> 和 Idempotency-Key: call_example。业务响应直接符合 outputSchema，例如 {"status":"已发货"}，不自动解包 data/result。deadline 是毫秒时间戳。

CallbackHandler 要求独立回调凭据至少 32 字符，检查应用、用户、工具版本、callId、请求大小和到期时间。业务函数仍负责订单所属用户与租户校验。

写操作与账本

账本目录使用持久磁盘，必须支持文件锁、fsync 和原子移动。处理过程先记录 STARTED，再执行，完成后保存结果。相同键和相同字节请求返回已保存结果；同键不同请求冲突；只有 STARTED 的未知结果拒绝自动重放。

多个业务实例需要共享满足锁和原子操作语义的持久存储，或用业务数据库实现分布式幂等。SDK 账本不能把远程业务事务和本地文件写入变成一个分布式事务。

远程知识服务

请求字段：appId, subjectId, tenantId, runId, traceId, query, topK。响应：

{"documents":[{"id":"policy-1","title":"退款规则","text":"可被引用的正文片段","source":"https://business.example.com/help/refund","tenantId":"team-a"}]}

先在服务端按身份检索，再返回有限文本。平台再次过滤租户并裁剪 topK。

远程模型适配

REMOTE Model 的非流请求包括 model、messages、max_completion_tokens、stream:false、可选 tools，以及平台组装的版本、调用标识、期限、用途与业务身份。返回：

{"message":{"role":"assistant","content":"根据业务数据生成的回复"},"usage":{"prompt_tokens":100,"completion_tokens":20,"total_tokens":120}}

工具调用使用 message.tool_calls，条目形如 {id,type:"function",function:{name,arguments:"JSON字符串"}}，只调用本轮提供的函数名。以上 usage 数字是格式示例，不是定价或性能指标。

REMOTE 同时支持 stream=true；完整 ModelProvider SPI、流帧、合成身份、错误与取消见远程模型提供器与流式接入。

超时、大小与重试

平台连接时限 5 秒，外部调用最多 60 秒且受根任务剩余时间限制；普通响应上限 1 MiB，模型原生 SSE 总量上限 4 MiB。禁止重定向，不自动重试。模型流必须正常结束，截断不能当作成功回复。

租约心跳

var heartbeat = new dev.sparktide.sdk.LeaseHeartbeat(
    client, "tools", "order-lookup", "1.0.0", "order-service-1", 60,
    error -> System.err.println("工具续租失败：" + error.getClass().getSimpleName()));
heartbeat.start().toCompletableFuture().join();
// 保存在业务服务生命周期中；停止服务时 heartbeat.close()。

先以 leaseRequired:true 注册能力，首次续租成功再启用相关智能体。后续每 TTL/3 续租，健康失败时停止续租并告警，不用续租掩盖业务不可用。