AgentKit Studio
Concepts

Managed runtime

A resident cloud runtime described by a manifest, with a deliberately conservative capability surface.

A managed runtime is a resident execution environment in the cloud. It is described by a manifest, it packages no model and copies no Studio store, and its identity is rebuilt from a trusted platform hop rather than read from the request body.

A local session ends when its Host process exits; a managed runtime runs around the clock. But "resident" does not mean "more capable" — the managed surface declares a conservative subset. This page draws that boundary.

Why a separate runtime form exists

DimensionLocal runManaged runtime
LifecycleTied to the Host processResident, scheduled by the platform
Definition sourceLocal agent store plus a local buildOne YAML manifest declaration
Identity sourceLocal agent recordPlatform-injected environment plus trusted headers
Session storageLocal diskLocal disk (valid within one agent version)
Capability surfaceCompleteA conservative subset, below

A managed runtime performs no local build and produces no ZIP package. It projects a mounted declaration onto the existing DSH admission contract, and native session storage stays authoritative.

The manifest declaration

The manifest format is agentengine.dsh-manifest/v1, capped at 900 KiB. It accepts exactly eight fields: name, description, framework, artifact_type, runtime, model, prompt, resources. One extra field raises MANAGED_MANIFEST_FIELD_UNSUPPORTED.

RuleConstraint
EncodingMust be valid UTF-8 YAML 1.2
KeysStrings only; duplicate keys forbidden
AliasesYAML aliases forbidden (maxAliasCount: 0)
RootMust be a mapping, not a sequence or scalar
runtimeMay contain only name and version
artifact_typeMust be ManagedRuntime
Three must agreeframework and runtime.name equal the selected runtime; runtime.version equals the selected version
Lengthsname ≤ 240, model ≤ 512, description ≤ 4096, prompt ≤ 900 KiB
Control charactersForbidden in every field except prompt

Disagreement among the three returns MANAGED_RUNTIME_IDENTITY_MISMATCH — the declaration names a runtime the platform is not launching, and nothing is auto-corrected. Other manifest codes: MANAGED_MANIFEST_INVALID, MANAGED_MANIFEST_TOO_LARGE, MANAGED_RUNTIME_IDENTITY_INVALID.

The resources field follows the managed resource contract; the shape and exclusivity rules of the five kinds live in Resources and bindings.

Identity: rebuilt from a trusted hop

A managed runtime's identity is not decided by the request body. Four trusted headers are mandatory, and a missing one returns RUNTIME_TRUSTED_IDENTITY_REQUIRED (401):

HeaderMeaning
x-agentengine-identity-namespaceIdentity namespace
x-agentengine-business-tenant-idBusiness tenant
x-agentengine-subject-typeSubject type (≤ 32 characters)
x-agentengine-subject-idSubject identifier (≤ 128 characters)

The four values are sorted in a fixed order, compacted to JSON, and hashed with SHA-256, producing a user identifier of aeu_ plus the digest. Any oversized value or control character returns RUNTIME_TRUSTED_IDENTITY_INVALID.

Identity cannot be forged from the request body

The platform hop has already authenticated the caller. A managed runtime does not read tenant or subject fields from the body — otherwise anyone who can send a request could claim any tenant.

Host-side inputs

InputConstraintFailure code
Platform AgentId and VersionIdMust be provided explicitly and match the identifier ruleMANAGED_HOST_IDENTITY_INVALID
Declaration input versus packageCannot specify a portable build or run package at the same timeMANAGED_HOST_INPUT_CONFLICT
Model endpointMust be an HTTP(S) address with no embedded credentials, query string, or fragmentMANAGED_HOST_MODEL_INVALID
Model credentialMust be injected by the platformMANAGED_HOST_MODEL_CREDENTIAL_MISSING
Codex API typeresponses or chat-completionsMANAGED_HOST_MODEL_INVALID

The endpoint points at an OpenAI-compatible service, and the credential name is fixed as AGENTKIT_MODEL_API_KEY. The runtime never caches or persists a model key.

Capability surface: a conservative declaration

The managed runtime exposes its capabilities explicitly. Unimplemented actions are marked unavailable rather than silently failing or returning an empty result:

ActionSupportedNote
submit_interaction✅ NativeThe Host holds each approval as an Interaction record and settles it here
cancel✅ NativeCancel a run
stop_run✅Stop the current run
pause / resume❌managed_surface_not_implemented
steer / inject❌Same
checkpoint / durable_restore❌No checkpoints
goal / loop / plan❌Same
resume_run❌Stop only, no resume
background_run❌Foreground runs only

Other declared capabilities:

ItemValue
Hosted chat formatresponses, endpoint /agentengine/api/v1/RunAgent, version v1
Cancel / interruptCancel supported, interrupt not
History readksadk.history/v2, session contract version 2, epochs and snapshots supported
Approval policyModes ask / risk, default risk, runtime override allowed
Persistence backenddsh-native-disk
Shared across podsNo
Effective scopeThe same agent version
Active run restoreNo (history is readable; an unfinished run does not resume automatically)
Attachments / workspace filesNeither supported
Kernel session eventsNot supported

"Effective scope is the same agent version" is an easy constraint to miss: session history is not readable across versions.

Execution policy

A managed runtime's execution policy comes from the deployment declaration and has two explicit layers:

ItemDefaultCeiling
Permission modeworkspace-writedanger-full-access

The exposed "allowed permission modes" is the subset up to and including the ceiling. A requested mode above the ceiling is clamped rather than rejected — see The three runtimes.

The deployment state machine

A deployment has 19 states, in three groups: polling states (9, continuously refreshed by the UI), attention states (7, requiring a person), and the remaining terminal or steady states.

StateLabelStateLabelStateLabel
PREPAREDReady to submitUPLOADINGUploading packageUPLOAD_UNKNOWNUpload result unverified
UPLOADEDUploadedCREATINGCreatingCREATE_UNKNOWNCreate result unverified
PROVISIONINGProvisioning instanceCONFIGURINGConfiguring access tokenTOKEN_PENDINGWaiting for config to apply
STARTINGStartingUPDATINGSwitching versionUPDATE_UNKNOWNUpdate result unverified
READYReadyAVAILABLE_UPDATINGEndpoint available, platform updatingACTION_REQUIREDAction required
FAILEDFailedDELETINGDeletingDELETE_UNKNOWNDelete result unverified
DELETEDDeleted

The three *_UNKNOWN states (upload, create, update, delete) mean outcome unknown, not failure. They mean "the request was sent but no definite receipt arrived", and the response is verification rather than retry. TOKEN_PENDING is both a polling state and an attention state — it is waiting for platform configuration to take effect.

Hard rules

  1. A manifest is never auto-corrected. Disagreement is an error, never "the platform value silently wins".
  2. Identity comes only from trusted headers. Identity fields in the request body are never read.
  3. Unimplemented actions must be marked unavailable, never return an empty result that impersonates success.
  4. Persistence crosses neither agent versions nor pods.
  5. Managed deployment accepts two runtimes only: DSH Native and Codex.
What you needWhich page
The full 19-state enumeration and polling setsDeployment states
MANAGED_* and RUNTIME_* error codesErrors
The environment variables the platform injectsEnvironment
Lifecycle and rollback detailsManaged runtime lifecycle

On this page