AgentKit Studio
Runtimes and deployment

Managed runtime lifecycle

A managed runtime passes through 19 deployment states, from submission to deletion. Read where it is stuck, what you can do, and what is not available yet.

A managed runtime is driven by a platform YAML declaration; Studio does not edit the Agent inside the container, it projects the declaration into one DSH launch. The declaration format is fixed at agentengine.dsh-manifest/v1, capped at 900 KiB, and accepts exactly 8 fields (src/managed-runtime-manifest.mjs:9-12).

The declaration contract

ItemValueSource
Formatagentengine.dsh-manifest/v1src/managed-runtime-manifest.mjs:9
Size cap900 KiB (900 * 1024 bytes):10, :28
Allowed fieldsname, description, framework, artifact_type, runtime, model, prompt, resources:12
framework valuesdsh-native, harness, codex:11
runtime shapeExactly the name and version keys:44
artifact_typeMust be ManagedRuntime:46
Runtime profileagentkit-runtimesrc/runtime-host-installation.mjs:12
Base bundles@deepseek-ai/dsh-base, @deepseek-ai/dsh-web-app, @kingsoftcloud/agentkit-studio:19

No inline credentials in a declaration

mcp_servers credentials can only reference deployment environment variables through env_refs; values are injected separately at deployment time. Inline credentials, query strings, fragments and backslashes are all rejected (src/managed-resource-contract.mjs). Any Agent write inside the container returns MANAGED_RUNTIME_READ_ONLY (src/managed-runtime-definition.mjs:79).

The main path: submission to ready

Start with the shortest route. This diagram has seven steps and three exits — it places most day-to-day questions.

Deployment main path: PREPARED → UPLOADING → UPLOADED → CREATING → PROVISIONING → STARTING → READY, plus the FAILED, UPLOAD_UNKNOWN and CREATE_UNKNOWN exitsDeployment main path: PREPARED → UPLOADING → UPLOADED → CREATING → PROVISIONING → STARTING → READY, plus the FAILED, UPLOAD_UNKNOWN and CREATE_UNKNOWN exits (dark)点击放大 · 滚轮缩放 · 拖拽平移

How to read it: once a deployment reaches FAILED that attempt is over — fix the cause and create again, it does not retry in place. Reaching a *_UNKNOWN means the platform did not confirm the outcome, so reconcile before acting.

The full state tree: 19 states, 26 transitions

Updates, rollbacks, deletion and every branch live here. States are grouped by what you should do next, not by internal order.

Full state tree of the 19 deployment states: the main path is PREPARED → UPLOADING → UPLOADED, the remaining states unfold by operator intent, including the direct READY → DELETED edge and the reconciliation loops of the four UNKNOWN statesFull state tree of the 19 deployment states: the main path is PREPARED → UPLOADING → UPLOADED, the remaining states unfold by operator intent, including the direct READY → DELETED edge and the reconciliation loops of the four UNKNOWN states (dark)点击放大 · 滚轮缩放 · 拖拽平移

How to read this: grouping is by "what should you do next", not by internal ordering. The four *_UNKNOWN states have a fixed meaning — the platform did not confirm the outcome, so they are neither failure nor success, and the only correct action is to reconcile before acting. Treating one as a failure and retrying submits a paid operation twice.

Below is the precise transition list for the same machine, for cross-checking against code:

Source: src/studio-deployments.mjs:268-430, src/client/state/deployment.mjs:1. State names match the strings in code exactly — do not translate them, because they appear in API responses.

What you can do in each state

StateLabelMeaningWhat you can doAuto-poll
PREPAREDPending submitRecord exists, bundle not uploadedSubmit as-is, or delete the recordNo
UPLOADINGUploading bundlePortable bundle in flightWait; an interruption becomes UPLOAD_UNKNOWNNo
UPLOAD_UNKNOWNUpload result unverifiedLocal flow interrupted, result unknownVerify in the operations centre; do not re-uploadNo
UPLOADEDUploadedBundle stored, waiting to create the cloud AgentWait for creationNo
CREATINGCreatingCall to CreateAgent in flightWait; an interruption becomes CREATE_UNKNOWNNo
CREATE_UNKNOWNCreate result unverifiedCreation interrupted, an instance may existVerify in the cloud first; Studio will not create a duplicateNo
PROVISIONINGProvisioning instanceInstance or token not ready yetWait; a long stay means the key is not readyYes
CONFIGURINGConfiguring access tokenWriting the API key into AGENTKIT_RUNTIME_TOKENWaitYes
TOKEN_PENDINGWaiting for the token to take effectToken written, probe not passingWait; a long stay means the env var is maskedYes
STARTINGStartingInstance running, but /health or the protocol probe has not passedWait; on repeated failure read the operations logYes
UPDATINGSwitching version, waiting for the entry pointPlatform rolling a versionWait for the entry point to recoverYes
UPDATE_UNKNOWNUpdate result unverifiedUpdate interruptedVerify the cloud version, then decide whether to retryYes
READYReadyHealth, protocol probe and version all passUse it normallyNo
AVAILABLE_UPDATINGEntry point available, platform updatingEntry point up, rollout still in progressUsable, but avoid hard dependenciesYes
ACTION_REQUIREDAction requiredStorage verification and similar need a humanRead failure.code, fix, retryYes
FAILEDFailedThe cloud reported a definite failureRead failure, fix, redeployNo
DELETINGDeletingDeletion in flightWaitYes
DELETE_UNKNOWNDelete result unverifiedDeletion interruptedVerify in the cloud, then retry deletionYes
DELETEDDeletedLogically deleted; native bytes are retainedRe-bind when readyNo

Polling set: DEPLOYMENT_POLL_STATES (9 entries). Requires attention: DEPLOYMENT_ATTENTION_STATES (7 entries, including TOKEN_PENDING and the four *_UNKNOWN states). Source: src/client/state/deployment.mjs:3, :5.

The four *_UNKNOWN states are not errors

UPLOAD_UNKNOWN, CREATE_UNKNOWN, UPDATE_UNKNOWN and DELETE_UNKNOWN all mean the local flow was interrupted and the cloud result is unknown. Studio deliberately does not retry automatically, because creating a duplicate instance costs far more than asking you to verify once (src/studio-deployments.mjs:323, :362-363).

Platform capability matrix

A managed runtime declares only part of the surface and marks the rest explicitly unavailable rather than silently approximating it:

CapabilitySupportedMode
submit_interaction (human approval)yesnative
cancel / StopRunyesNative
resume / ResumeRunnoExplicitly unavailable
background runsnoExplicitly unavailable
checkpoint / durable_restorenoExplicitly unavailable
goal / loop / plannoExplicitly unavailable
attach / steer / injectnoExplicitly unavailable
Attachments and workspace filesnoAttachments: false, WorkspaceFiles: false
Kernel session eventsnoKernelSessionEvents: false

Source: src/managed-runtime-capabilities.mjs:2-30.

Persistence is declared as dsh-native-disk with SharedAcrossPods: false, EffectiveFor: same_agent_version and ActiveRunRestore: false — resumable within one Agent version, not shared across Pods, and active runs are not restored automatically (:28-29).

State directory and identity

Path / itemPurposeSource
<state>/.managed-runtime.jsonWritten on first boot, format agentengine.managed-state/v1src/managed-runtime-host.mjs:289
<state>/versions/<sha256(versionId)>/.managed-version.jsonVersion-scoped immutable receipt, format agentengine.managed-version/v1:296
<state>/dshDSH home, Agent-scoped, keeping sessions and settings across versions:19-24
<state>/.dsh-adopted.jsonReceipt for adopting a pre-fix version directory:22
agentkit/managed-sessionsManaged session registry:178

Reusing one VersionId with different declaration bytes fails: a version is immutable (:292-296).

Local port authentication and privacy boundary

This section covers the port the managed Host listens on locally. To call a deployed Agent's cloud API (RunAgent, the SSE stream, the 37 AgentEngine Actions), see Cloud Agent HTTP API — that is a different authentication scheme and has nothing to do with the token here.

ItemRuleSource
Runtime tokenAGENTKIT_RUNTIME_TOKEN is at least 24 characterssrc/managed-runtime-host.mjs:273
Trusted business identityAll four x-agentengine-* headers are required; missing returns 401src/managed-runtime-identity.mjs:5-18
Subject identifierSort the four identity parts, then SHA-256, prefixed aeu_:21-24
Version fenceX-AgentEngine-Target-Version-Id and X-AgentEngine-Manifest-Sha256 must match the loaded declaration, otherwise 409 RUNTIME_DEPLOYMENT_CHANGEDsrc/build-runtime-http.mjs:105
One active runA session with an active run returns 409 RUNTIME_SESSION_BUSY:193
Approval timeout2 minutessrc/managed-runtime-approval.mjs:25

Managed Host endpoints

A managed Host listens on a local HTTP port and the platform drives sessions through it. The surface splits into health/identity probes and the Actions under /agentengine/api/v1/.

MethodPathPurpose
GET/healthReadiness probe: 200 ready, 503 stopping
GET/v1/agentkit/runtimeIdentity probe: AgentId, VersionId, manifest digest and runtime version
POST/v1/responses, /runsModel run entry point (Responses transport)
POST/runs/<runId>/cancel, /v1/responses/<id>/cancelCancel one run
POST/agentengine/api/v1/<Action>Session and history Actions (table below)
ActionRequired fields
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
ListSessionEventsAs above, plus EventTypes, EventOrder, Offset, CheckpointIds

AgentId and UserId are always allowed; an unlisted field fails with RUNTIME_ACTION_INPUT_UNSUPPORTED and an unknown Action returns 404 RUNTIME_ACTION_UNSUPPORTED (src/managed-runtime-actions.mjs:158-167, src/build-runtime-http.mjs:128-132).

On this page