AgentKit Studio
概念

托管运行时

托管运行时是跑在云端的常驻运行环境。它由一份清单声明描述,能力面刻意保守,身份来自受信任的平台跳而非请求体。

托管运行时(managed runtime)是跑在云端的常驻运行环境。它由一份清单声明(manifest)描述,不打包模型、不复制 Studio 存储,身份由受信任的平台跳重建而不是从请求体读取。

本地会话随宿主进程退出而中断;托管运行时 7×24 常驻。但「常驻」不等于「能力更全」——托管面的能力声明是一份保守的子集,这一页把边界讲清。

为什么需要独立的运行时形态

维度本地运行托管运行时
生命周期跟随宿主进程常驻,由平台调度
定义来源本地 Agent 存储 + 本地构建一份 YAML 清单声明
身份来源本地 Agent 记录平台注入的环境变量 + 受信任请求头
会话存储本机磁盘本机磁盘(同一 Agent 版本内有效)
能力面完整保守子集,见下文

托管运行时不做本地 Build,也不生成 ZIP 运行包。它把一份挂载好的声明投影成已有的 DSH 准入契约,原生会话存储仍然权威。

清单声明

清单格式是 agentengine.dsh-manifest/v1,最大 900 KiB。只接受八个字段:name、description、framework、artifact_type、runtime、model、prompt、resources。多一个字段直接判 MANAGED_MANIFEST_FIELD_UNSUPPORTED。

规则约束
编码必须是合法 UTF-8 的 YAML 1.2
键必须是字符串,且不允许重复键
别名禁止 YAML 别名(maxAliasCount: 0)
根节点必须是映射,不能是数组或标量
runtime只能有 name 和 version 两个键
artifact_type必须是 ManagedRuntime
三者一致framework、runtime.name 必须等于所选运行时;runtime.version 必须等于所选版本
长度name ≤ 240、model ≤ 512、description ≤ 4096、prompt ≤ 900 KiB
控制字符除 prompt 外,任何字段都不能含控制字符

三者不一致返回 MANAGED_RUNTIME_IDENTITY_MISMATCH——这是「声明描述的运行时」与「平台实际选择启动的运行时」不符,不允许自动纠正。其他清单错误码:MANAGED_MANIFEST_INVALID、MANAGED_MANIFEST_TOO_LARGE、MANAGED_RUNTIME_IDENTITY_INVALID。

resources 字段走托管资源契约,五类资源的形状与互斥规则见资源与绑定。

身份:由受信任跳重建

托管运行时的身份不由请求体决定。四个受信任请求头必须齐全,缺一个返回 RUNTIME_TRUSTED_IDENTITY_REQUIRED(401):

请求头含义
x-agentengine-identity-namespace身份命名空间
x-agentengine-business-tenant-id业务租户
x-agentengine-subject-type主体类型(≤ 32 字符)
x-agentengine-subject-id主体标识(≤ 128 字符)

四个值按固定顺序排序后压缩成 JSON,取 SHA-256 摘要,得到 aeu_ 加摘要的用户标识。任何超长或含控制字符的值返回 RUNTIME_TRUSTED_IDENTITY_INVALID。

身份不能从请求体伪造

平台跳已经完成了认证。托管运行时不再读请求体里的租户或主体字段——否则任何能发请求的人都能声明自己是任意租户。

宿主侧输入

输入约束失败码
平台 AgentId 与 VersionId必须明确提供,匹配标识符规则MANAGED_HOST_IDENTITY_INVALID
声明输入与运行包不能同时指定 portable Build 或运行包MANAGED_HOST_INPUT_CONFLICT
模型入口必须是无内嵌凭证、无查询串、无片段的 HTTP(S) 地址MANAGED_HOST_MODEL_INVALID
模型凭证必须由平台注入MANAGED_HOST_MODEL_CREDENTIAL_MISSING
Codex 接口类型responses 或 chat-completionsMANAGED_HOST_MODEL_INVALID

模型入口指向一个 OpenAI 兼容端点,凭证名固定为 AGENTKIT_MODEL_API_KEY。运行时不缓存、不落盘任何模型密钥。

能力面:一份保守声明

托管运行时对外暴露的能力是显式的,未实现的动作一律标记为不可用,而不是静默失败或返回空结果:

动作支持说明
submit_interaction✅ 原生宿主把每次审批持有为 Interaction 记录,通过该动作结算
cancel✅ 原生取消运行
stop_run✅停止当前运行
pause / resume❌managed_surface_not_implemented
steer / inject❌同上
checkpoint / durable_restore❌无检查点
goal / loop / plan❌同上
resume_run❌只有停止,没有续跑
background_run❌只支持前台运行

其他被声明出来的能力:

项值
托管对话格式responses,地址 /agentengine/api/v1/RunAgent,版本 v1
取消 / 中断取消支持,中断不支持
历史读取ksadk.history/v2,会话契约版本 2,支持 epoch 与快照
审批策略模式 ask / risk,默认 risk,允许运行时覆盖
持久化后端dsh-native-disk
跨 Pod 共享否
生效范围同一 Agent 版本
活跃运行恢复否(历史可读,未完成的运行不自动续跑)
附件 / 工作区文件均不支持
内核会话事件不支持

「持久化生效范围是同一 Agent 版本」是一条容易忽略的约束:跨版本读不到会话历史。

执行策略

托管运行时的执行策略来自部署声明,有明确的两层:

项默认上限
权限模式workspace-writedanger-full-access

对外暴露的「允许的权限模式」是到上限为止的子集(含上限本身)。请求的模式如果超出上限,会被夹到上限值而不是报错,见三种运行时。

部署状态机

部署有 19 个状态。它们分成三类:轮询态(9 个,界面持续刷新)、需要关注态(7 个,需要人处理)、其余为终态或稳定态。

状态中文状态中文状态中文
PREPARED待提交UPLOADING上传运行包UPLOAD_UNKNOWN上传结果待核对
UPLOADED已上传CREATING创建中CREATE_UNKNOWN创建结果待核对
PROVISIONING准备实例CONFIGURING配置访问令牌TOKEN_PENDING等待配置生效
STARTING启动中UPDATING切换版本UPDATE_UNKNOWN更新结果待核对
READY就绪AVAILABLE_UPDATING入口可用 · 平台更新中ACTION_REQUIRED需要处理
FAILED失败DELETING删除中DELETE_UNKNOWN删除结果待核对
DELETED已删除

三个 *_UNKNOWN 状态(上传、创建、更新、删除)是结果未知,不是失败。它们的语义是「请求已发出但没有拿到确定回执」,处理方式是核对而不是重试。TOKEN_PENDING 同时属于轮询态与需要关注态——它在等平台配置生效。

硬规则

  1. 清单不做自动纠正。三者不一致就是错误,不会「按平台选择的值覆盖声明」。
  2. 身份只来自受信任请求头,请求体里的身份字段一律不读。
  3. 未实现的动作必须显式标记不可用,不能返回空结果冒充成功。
  4. 持久化不跨 Agent 版本,也不跨 Pod。
  5. 托管部署只接受两个运行时:DSH 原生与 Codex。

相关任务

相关参考

你要查的东西去哪一页
19 个状态的完整枚举与轮询集合部署状态机
MANAGED_*、RUNTIME_* 错误码错误码
托管注入的环境变量清单环境变量
生命周期与回滚细节托管运行时生命周期

本页导航