类型化聊天与执行核对

兼容客户端参考

本页包含旧 AgentClient / PlatformClient 调用方式，适合已有集成、非 Spring 程序和迁移对照。常规浏览器接入使用 createChatClient 与后台标准 /api/ai，第一次接入见完整教程。

SDK 示例

Java

var request = ChatRequest.builder("查询当前设备")
    .agent("monitor-agent", "1.0.0")
    .context(Map.of("deviceId", "device-123"))
    .idempotencyKey("device-query-123")
    .build();
var run = client.chat(request).toCompletableFuture().join();

Kotlin

import dev.sparktide.sdk.kotlin.chat

val run = client.chat {
    message("查询当前设备")
    agent("monitor-agent", "1.0.0")
    context { "deviceId" to "device-123" }
    idempotencyKey("device-query-123")
}

Java 示例说明：

省略 agent 使用应用默认入口；显式选择必须提供准确版本。可用 conversation 续接会话，用 uiCapabilities 申明渲染器。请求创建时复制 Context，支持 JSON 对象、数组、字符串、布尔、数值与 null；拒绝任意业务对象。正文不能承载可信身份。每个请求默认生成幂等键；重试时复用同一请求或显式使用同一键。

Kotlin 示例说明：

SDK 的 context 接收器实际收集 "key" to value，无需构造 Map。不要把该 DSL 的 infix 操作与普通 Kotlin 丢弃 Pair 的代码混用。返回的是已接受的 Run，等待终态仍使用已有任务等待 API。

需要按当前业务用户调用时，使用 client.forUser { resolvedToken }，或 Kotlin 的 chatAs(currentUser, credential = { tokenResolver(it) }) { ... }。tokenResolver 必须由业务服务从已认证用户解析出平台可验证的凭据，不能把 userId 写入 Context 冒充身份。

应用管理与业务核对

updateApplication(name, status, reason, revision) 使用管理凭据更新应用。停用/归档需要原因；revision 来自最新 application()。toolExecutions(runId) 返回工具账本，reconcileExecution(id, status, reason, evidence, revision) 核对 UNKNOWN 结果。先在业务系统确认结果再提交 SUCCEEDED 或 FAILED，不要凭超时推断失败；核对不会重放业务调用，也不改变 Run 终态。普通用户无权核对。

验证与兼容

运行仓库 gradlew.bat clean build。聊天测试覆盖请求快照、用户凭据与幂等头、非法参数和 Kotlin Context 收集。HTTP 接口保持 V1；新增方法要求平台提供 2026-09-29 的应用状态与工具账本扩展。旧聊天重载仍可用。注解扫描、业务 KnowledgeProvider 与自动注册 Starter 不由本文声称已完成。

绑定真实业务用户

AgentClient<U> 从受信的 UserCredentialProvider<U> 解析用户凭据。解析器必须验证对象对应当前认证会话，不能按客户端任意输入的用户标识签发令牌。用户对象不会进入 HTTP Context，平台继续校验令牌应用、主体、租户、有效期与权限。

import dev.sparktide.sdk.AgentClient
import dev.sparktide.sdk.UserCredentialProvider
import dev.sparktide.sdk.kotlin.chat

val agentClient = AgentClient(platformClient, UserCredentialProvider<CurrentUser> { current ->
    require(current == authenticatedSession.currentUser())
    userCredentialStore.forAuthenticatedSession(authenticatedSession)
})

val run = agentClient.chat {
    agent("monitor-agent")
    user(currentUser)
    message("分析当前监测设备")
    context { "deviceId" to currentDevice }
}

按名称的 agent 会先用用户凭据调用入口解析接口，取得精确版本再创建任务。默认 Agent 使用应用绑定版本；其他入口选最新已发布版本，并检查入口及 DISCOVER 授权。内部或隐藏入口返回 404，不返回系统提示词或管理定义。需要完全固定版本时用 agent("monitor-agent", "1.0.0")。

Java 使用 agentClient.chat(currentUser, ChatRequest.builder("分析设备").agent("monitor-agent", "1.0.0").build())。对象不是真实会话主体、缺失用户或无用户凭据时拒绝发送；解析器拒绝伪造身份的责任仍属于业务认证边界。

文档来源与验证记录

日期：2026-09-29；状态：已实现；责任人：项目维护者；来源：ChatRequest、ChatDsl、PlatformClient 及平台 OpenAPI。适用 0.1.0-SNAPSHOT。