业务权限与可信上下文

本页阅读位置

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

选择接入方式

已有账号、组织和数据权限由你的业务服务管理。平台验证用户凭据，把真实应用、用户、租户和角色发送给业务权限服务；模型与页面 Context 均不能提供授权。为受保护 Agent、工具、知识或界面能力配置 permissions，例如 ["device:read"]。未配置权限名称的能力保留现有入口、角色和引用限制。

权限服务支持三个独立动作，不能一律返回 true。

动作	调用时机	应检查的内容
DISCOVER	向模型展示能力前，以及按名称解析聊天入口时	主体是否可见该能力
EXECUTE	真正调用前，危险确认后再次调用	必要权限、业务资源、参数对应的数据范围
READ_HISTORY	后续模型调用、输出、读取文本事件和继续会话前	是否仍可使用该能力产生的结果

每次独立查询，不缓存放行结果。服务故障或超时拒绝受保护能力，隐藏无权展示的能力；无权限服务配置的受保护 Agent 不能运行。操作人从审计记录中的 permission.* 查询平台 decisionId、业务 providerDecisionId、资源版本和 Run/Trace。

注册业务 Provider

使用后台 SDK 的可选 Spring Boot Starter，提供 Java 接口 Bean。Starter 使用独立回调凭据挂载服务，不会自动启用应用权限配置；由应用管理员检查地址、来源和密钥授权后绑定。

Java

@Bean
PermissionProvider agentPermissions(BusinessPermissionService service) {
    return request -> new PermissionDecision(
        service.check(
            request.identity().appId(), request.identity().userId(),
            request.identity().tenantId(), request.resource(), request.action(),
            request.requiredPermissions(), request.arguments()),
        java.util.UUID.randomUUID().toString(), "业务策略决策");
}

@Bean
AgentContextProvider agentContext(BusinessDirectory directory) {
    return identity -> new TrustedContext(
        java.util.Map.of("department", directory.departmentOf(identity.userId())),
        "business-directory", directory.revision());
}

Kotlin

import dev.sparktide.sdk.kotlin.PermissionProvider
import dev.sparktide.sdk.kotlin.AgentContextProvider
import dev.sparktide.sdk.kotlin.asJavaProvider

val permissionBean = PermissionProvider { request ->
    businessPolicy.decide(request) // 返回 PermissionDecision
}.asJavaProvider()

val contextBean = AgentContextProvider { identity ->
    businessDirectory.context(identity) // 返回 TrustedContext
}.asJavaProvider()

示例中的 BusinessPermissionService 与 BusinessDirectory 是你的业务服务，应验证用户、组织、资源和数据权限；requiredPermissions 必须全部满足。arguments 与 untrustedContext 是不可信输入，不能用其中的 subjectId 或 permissions 替代 identity。业务工具和知识检索仍需在最终业务操作处检查数据权限。

工具注解可以直接声明权限：

@AgentTool(name = "query-device", description = "查询监测设备", permissions = {"device:read"})
public class QueryDeviceTool {
    // execute 使用业务服务读取，并在业务服务中检查当前用户对设备的权限。
}

@AgentKnowledge 同样支持 permissions。普通 Kotlin data class、suspend 方法与注入后的业务实例接入方式见知识提供器和自动注册教程。

Kotlin 标签展示 suspend Provider 转为 Starter 可发现的 Java Bean；工具注解示例与普通 Kotlin data class、suspend 方法的约束仍按对应教程使用。

每种 Provider 只允许一个 Bean；容器的业务安全代理正常保留。没有 Starter 时可用 BusinessProviderCallbacks.permission(appId, credentialSupplier, provider) 和 .context(...) 挂载到自己的 HTTP 服务器，并限制到精确路径。

绑定到平台

1. 在业务 Starter 中配置 publicBaseUrl、callbackToken、secretRef 与持久账本目录。默认地址路径为 ${publicBaseUrl}/permission 和 ${publicBaseUrl}/context。
2. 平台运维配置来源、允许的密钥名称、密钥所属应用与实际环境变量，例如 HTTPS 业务域名和 CALLBACK_KEY=monitor。平台管理令牌不能当作业务回调令牌。
3. 打开应用概览 → 业务权限与上下文，启用服务并填写地址、密钥引用、超时及变更原因。可信上下文还需封闭 JSON Schema。
4. 在能力配置中填写业务权限名称，检查草稿并发布。权限名称属于版本定义，修改已发布能力需创建新版本。

也可以调用应用更新接口或 SDK：

client.configureBusinessProviders(
    java.util.Map.of("endpoint", "https://business.example.com/agent/permission",
        "secretRef", "CALLBACK_KEY", "timeoutMs", 2000),
    null, // 不修改可信上下文配置
    "绑定现有业务授权服务", currentRevision);

null 表示不修改该配置，空对象表示停用；管理员更新需携带当前 revision 与原因。timeoutMs 为 100–10000，默认 2000。所有地址遵守平台来源白名单、HTTPS 和密钥应用授权。

可信上下文合同

权限与上下文请求公共字段是 protocolVersion=1.0、appId、subjectId、tenantId、role、runId、traceId、deadline。上下文服务只接收这些认证字段；返回 {context,source,revision}。业务数据须符合应用配置的 Schema，最大 16 KiB；source/revision 各为 1–128 字符。禁止使用根 appId、subjectId、tenantId、role、permissions 作为可信上下文字段。

示例 Schema：

{"type":"object","properties":{"department":{"type":"string","maxLength":128}},"required":["department"],"additionalProperties":false}

可信上下文仅是业务数据，不能改变身份、Tool 权限或入口策略。客户端 context 独立标为不可信，两者不会互相覆盖。回调 ToolContext.trustedContext()、KnowledgeContext.trustedContext() 可读取 {context,source,revision} 包装，业务必须继续校验数据访问权限。

权限请求还包含 resource（kind/id/version）、action、requiredPermissions、arguments、untrustedContext。响应为 allowed 布尔、非空 decisionId（最多 128 字符）、可选 reason（最多 1024 字符）。Callback 身份与 deadline 校验失败拒绝，返回异常详情不会转交用户。

撤权、升级和核验

已使用的受保护能力保留到 Run 和会话；撤权后历史查询与后续模型使用需重新授权。修改权限或上下文服务配置会使整个应用的旧会话及在途任务失效，用户需要新建会话。部署升级无新表迁移；回退前暂停依赖新权限的应用，旧程序不能执行新约束。

授权与网络执行之间存在竞态，已发送给外部模型的数据无法追回；最终业务服务的权限检查不可省略。本地测试验证筛选、撤权、故障、认证回调和 Schema；真实业务策略正确性需用你的业务系统验收。

历史授权保留每次执行的资源版本与原始参数，不仅检查权限名称。READ_HISTORY 使用原参数重新检查设备、项目等数据范围；不同参数分别保留。单会话最多 256 个不同授权来源，达到上限返回 BUDGET_EXCEEDED，需新建会话；旧来源采用保守保留策略，可能早于消息清理发生撤权失效。

文档来源与验证记录

状态：已确认；日期：2026-09-30；责任人：SparkTide 维护者；关联任务：G03、B05、R01；来源：BusinessAccess、ExecutionEngine、BusinessProviderCallbacks 与行为测试。