AgentKit Studio
运行时与部署

托管运行时生命周期

一个托管运行时从提交到删除要经过 19 个部署状态;这张状态图说明它卡在哪、你该做什么,以及哪些能力平台还没实现。

托管运行时(managed runtime)由平台 YAML 声明驱动,Studio 不在容器里编辑 Agent,只把声明投影成一次 DSH 启动。 声明格式固定为 agentengine.dsh-manifest/v1,上限 900 KiB,只接受 8 个字段(src/managed-runtime-manifest.mjs:9-12)。

声明契约

项值依据
格式agentengine.dsh-manifest/v1src/managed-runtime-manifest.mjs:9
大小上限900 KiB(900 * 1024 字节):10、:28
允许字段name、description、framework、artifact_type、runtime、model、prompt、resources:12
framework 取值dsh-native、harness、codex:11
runtime 结构只能有 name 与 version 两个键:44
artifact_type必须是 ManagedRuntime:46
运行 Profileagentkit-runtimesrc/runtime-host-installation.mjs:12
基础 bundle@deepseek-ai/dsh-base、@deepseek-ai/dsh-web-app、@kingsoftcloud/agentkit-studio:19

声明不接受内联凭证

mcp_servers 的凭证只能通过 env_refs 引用部署环境变量,值在部署时单独注入;内联凭证、查询串、片段与反斜杠都会被拒绝(src/managed-resource-contract.mjs)。容器内对 Agent 的写操作一律返回 MANAGED_RUNTIME_READ_ONLY(src/managed-runtime-definition.mjs:79)。

主路径:从提交到就绪

先看最短的那条路。下面这张图只有七步和三处出口——日常排查 90% 的问题都能在这里定位。

部署主路径:PREPARED → UPLOADING → UPLOADED → CREATING → PROVISIONING → STARTING → READY,以及 FAILED、UPLOAD_UNKNOWN、CREATE_UNKNOWN 三处出口部署主路径:PREPARED → UPLOADING → UPLOADED → CREATING → PROVISIONING → STARTING → READY,以及 FAILED、UPLOAD_UNKNOWN、CREATE_UNKNOWN 三处出口 (dark)点击放大 · 滚轮缩放 · 拖拽平移

读图要点:一旦落到 FAILED,本次尝试就结束了——修因后重建,不能原地重试;落到 *_UNKNOWN 则说明平台没有确认结果,先核对再动作。

全状态树:19 个状态与 26 条转移

升级、回滚、删除与所有旁支都在这张图里。分组依据是「你下一步该做什么」,不是内部顺序。

19 个部署状态的全状态树:主路径 PREPARED → UPLOADING → UPLOADED,其余状态按操作意图展开,包含 READY → DELETED 的直接删除边与四个 UNKNOWN 的核对回路19 个部署状态的全状态树:主路径 PREPARED → UPLOADING → UPLOADED,其余状态按操作意图展开,包含 READY → DELETED 的直接删除边与四个 UNKNOWN 的核对回路 (dark)点击放大 · 滚轮缩放 · 拖拽平移

四个 *_UNKNOWN 的含义固定:平台没有确认结果,它既不是失败也不是成功,唯一动作是先核对再决定;把它当失败重试,会重复提交一次付费操作。

下面是同一台状态机的精确转移列表,用于对照代码:

依据:src/studio-deployments.mjs:268-430、src/client/state/deployment.mjs:1。状态名与代码中的字符串完全一致,不要翻译它们——它们会出现在 API 响应里。

每个状态你能做什么

状态界面名含义你能做什么自动轮询
PREPARED待提交记录已建,尚未上传运行包直接提交;或删除记录否
UPLOADING上传运行包正在传 portable 包等待;网络中断会转 UPLOAD_UNKNOWN否
UPLOAD_UNKNOWN上传结果待核对本机流程中断,上传结果未知在运行中心核对,不要重复上传否
UPLOADED已上传包已落库,等待创建云端 Agent等待创建否
CREATING创建中正在调用 CreateAgent等待;中断会转 CREATE_UNKNOWN否
CREATE_UNKNOWN创建结果待核对创建流程中断,可能已建实例先去云端核对,Studio 不会重复创建否
PROVISIONING准备实例实例/令牌尚未就绪等待;若长时间停留说明密钥未就绪是
CONFIGURING配置访问令牌正在把 API Key 写进 AGENTKIT_RUNTIME_TOKEN等待是
TOKEN_PENDING等待配置生效令牌已写,尚未通过探针等待;持续停留说明环境变量被掩码是
STARTING启动中实例在跑,但 /health 或协议探针未通过等待;持续失败看运行中心日志是
UPDATING切换版本 · 等待入口确认平台正在滚动版本等待入口恢复是
UPDATE_UNKNOWN更新结果待核对更新流程中断核对云端版本后决定是否重试是
READY就绪健康检查、协议探针、版本全部通过正常使用否
AVAILABLE_UPDATING入口可用 · 平台更新中入口已可用,后台仍在滚动可用但避免强依赖是
ACTION_REQUIRED需要处理存储校验失败等需要人工介入看 failure.code 修复后重试是
FAILED失败云端明确失败看 failure,修复后重新部署否
DELETING删除中正在删除等待是
DELETE_UNKNOWN删除结果待核对删除流程中断核对云端后重试删除是
DELETED已删除记录逻辑删除,原生字节仍保留可重新绑定否

轮询集合:DEPLOYMENT_POLL_STATES(9 个)。需要人工关注:DEPLOYMENT_ATTENTION_STATES(7 个,含 TOKEN_PENDING 与四个 *_UNKNOWN)。依据:src/client/state/deployment.mjs:3、:5。

四个 *_UNKNOWN 状态不是错误

UPLOAD_UNKNOWN、CREATE_UNKNOWN、UPDATE_UNKNOWN、DELETE_UNKNOWN 都表示本机流程中断、云端结果未知。Studio 刻意不自动重试,因为重复创建实例的代价远大于让你去核对一次(src/studio-deployments.mjs:323、:362-363)。

平台能力矩阵

托管运行时对外只声明一部分能力,其余显式标为不可用,而不是静默近似:

能力支持形态
submit_interaction(人工审批)是native
cancel / StopRun是原生
resume / ResumeRun否显式不可用
background 后台运行否显式不可用
checkpoint / durable_restore否显式不可用
goal / loop / plan否显式不可用
attach / steer / inject否显式不可用
附件与工作区文件否Attachments: false、WorkspaceFiles: false
Kernel 会话事件否KernelSessionEvents: false

依据:src/managed-runtime-capabilities.mjs:2-30。

持久化声明为 dsh-native-disk,SharedAcrossPods: false,EffectiveFor: same_agent_version,且 ActiveRunRestore: false——同一 Agent 版本内可续,跨 Pod 不共享,活跃 Run 不自动恢复(:28-29)。

状态目录与身份

路径 / 项作用依据
<state>/.managed-runtime.json首次启动写入,格式 agentengine.managed-state/v1src/managed-runtime-host.mjs:289
<state>/versions/<sha256(versionId)>/.managed-version.json版本级不可变回执,格式 agentengine.managed-version/v1:296
<state>/dshDSH home,按 Agent 作用域,跨版本保留会话与设置:19-24
<state>/.dsh-adopted.json旧版本目录接管回执:22
agentkit/managed-sessions托管会话注册表:178

同一 VersionId 换一份不同字节的声明会失败——版本不可变(:292-296)。

本机端口认证与隐私边界

这一节只讲托管 Host 本机监听的端口。想调已部署 Agent 的云端接口(RunAgent、SSE 流、37 个 AgentEngine Action),见云端 Agent HTTP API —— 那是另一套认证,与本节的令牌无关。

项规则依据
运行时令牌AGENTKIT_RUNTIME_TOKEN 至少 24 字符src/managed-runtime-host.mjs:273
可信业务身份四个 x-agentengine-* 头全部必填,缺失 401src/managed-runtime-identity.mjs:5-18
主体标识四段身份排序后取 SHA-256,前缀 aeu_:21-24
版本护栏X-AgentEngine-Target-Version-Id 与 X-AgentEngine-Manifest-Sha256 必须与加载的声明一致,否则 409 RUNTIME_DEPLOYMENT_CHANGEDsrc/build-runtime-http.mjs:105
单活动 Run同一会话已有活动 Run 时返回 409 RUNTIME_SESSION_BUSY:193
审批超时2 分钟src/managed-runtime-approval.mjs:25

托管 Host 端点

托管 Host 在本机监听一个 HTTP 端口,平台通过它驱动会话。端点分两类:健康/身份探针,以及 /agentengine/api/v1/ 下的 Action。

方法路径作用
GET/health就绪探针:ready 返回 200,停机中返回 503 stopping
GET/v1/agentkit/runtime身份探针:AgentId、VersionId、manifest 摘要与运行时版本
POST/v1/responses、/runs模型运行入口(Responses 传输)
POST/runs/<runId>/cancel、/v1/responses/<id>/cancel取消一次运行
POST/agentengine/api/v1/<Action>会话与历史 Action(下表)
Action必填字段
GetAgentUiBootstrapName、SessionId
ListAgentModelsName
CreateSessionSessionId
GetSessionSessionId
ListSessionsPage、PageSize
DeleteSessionSessionId
CancelRunSessionId、InvocationId、ResponseId、ClientToken
SubmitInteractionSessionId、RunId、InteractionId、ExpectedRevision、Action、Response、IdempotencyKey
ListSessionMessagesSessionId、Limit、AfterSeqId、BeforeSeqId、HistoryEpoch、SnapshotSeqId、CursorSource、IncludeReasoning、IncludeToolEvents、IncludeAttachments
ListSessionEvents同左,另加 EventTypes、EventOrder、Offset、CheckpointIds

AgentId 与 UserId 始终允许;未列出字段抛 RUNTIME_ACTION_INPUT_UNSUPPORTED,未知 Action 返回 404 RUNTIME_ACTION_UNSUPPORTED(src/managed-runtime-actions.mjs:158-167、src/build-runtime-http.mjs:128-132)。

相关页面

本页导航