AgentKit Studio
Concepts

Concepts

Six nouns explain the product model: agent, revision, build, session, run, and runtime type.

The AgentKit Studio product model has exactly six nouns: agent, revision, build, session, run, and runtime type — the value that decides where those entities execute.

This chapter takes each one in turn and states the hard constraints between them. When you finish, you can answer questions like "will changing this setting affect a session that is already running?" without trying it first.

System layers

AgentKit Studio five-layer architecture: browser UI, Studio control plane, Host service domains, runtime adapters and external kernels, with the /agentkit RPC and HTTP prefix channelsAgentKit Studio five-layer architecture: browser UI, Studio control plane, Host service domains, runtime adapters and external kernels, with the /agentkit RPC and HTTP prefix channels (dark)点击放大 · 滚轮缩放 · 拖拽平移

How to read this: the browser only sends operation ids and holds no state; the Host service domains are the only persistence boundary; everything below the runtime adapters is an external kernel. Of the two physical channels, only /agentkit RPC goes through the 134-operation dispatcher — model proxying and conversation streaming use HTTP prefix routes instead.

Why a concepts chapter exists

The four panels each expose one slice of the product model, yet the same vocabulary appears together on the same screen:

What the UI showsThe concept behind itMost often mistaken for
A notice that saving produced a new revisionRevisionA draft you can overwrite
A build record in the operations panelAgent buildA CI or image build
A row in the agent listAgentA running process
An entry in the session listSessionA log of one request
Usage and duration at the bottomRunA cumulative total for the session

Treating a revision as an overwritable draft, or a build as a pipeline artifact, leads to the same wrong conclusion: that editing configuration changes a session already in flight. It does not. Not because the product lacks hot reload, but because these four entities freeze at different layers — see Agent · Revision · Build · Run.

The four panels and their secondary tabs are organised like this:

Workbench map: the browser UI splits into Overview, Agents, Resources and Operations, with each panel's second-level tabs and their responsibilityWorkbench map: the browser UI splits into Overview, Agents, Resources and Operations, with each panel's second-level tabs and their responsibility (dark)点击放大 · 滚轮缩放 · 拖拽平移

How to read it: the four panels are peers, not a hierarchy. What decides where a run executes is the agent's runtime type, not the panel.

The five tabs under Operations are not five sections of one page — they are five independent surfaces: builds and deployments own artifacts, automation owns schedules, evaluation owns pass rates, observability owns traces, and Channels owns remote channels. They share no selection state, so switching tabs never changes which Agent you are looking at.

What each of the six entities owns

EntityPrimary keyWhat it freezesWho owns its lifecycle
AgentagentIdOnly a "current pointer"Studio local store
RevisionrevisionA complete immutable snapshot after one editThe agent; append-only
Agent buildbuildIdA content-addressed package of one revision plus its execution engineThe agent; rebuildable
SessionsessionIdOne durable DSH event journalThe Host
RunrunIdOne turn from start to endThe session
Runtime typeruntime.typeWhich execution model serves this agentLocked when the agent is created

Studio neither generates nor stores the last two identifiers (sessionId, runId). It only validates that their binding is correct. A mismatched binding is an error, never a guess.

How the concepts relate

Agent agentId
  └─ Revision revision 1..N        (immutable; saving appends)
       └─ Agent build buildId       (content-addressed; same input, same id)
            └─ Session sessionId    (DSH owns the journal)
                 └─ Run runId       (one turn)

A complete run identity needs all five fields: agentId, revision, buildId, sessionId, runId. Missing one is rejected rather than degraded to a partial identity. The same rule implies: an agent without a build can still converse, but without a build there is no reproducible run identity.

The three runtimes

runtime.type has exactly three values, and they are STUDIO_RUNTIME_TYPES (src/runtime-contract.mjs:6):

ValueUI nameCreatableExecution model
dsh-nativeDSH Native HarnessYes (default for new agents)native
harnessStar HarnessConditionally: installed + enabled + a usable workspacenative-kernel
codexCodex AgentYescodex-app-server

Star Harness is the only pluggable one of the three: it is delivered as npm packages from ksadk-harness and only appears in the creation form once it is installed and bound to a workspace. See the three runtimes.

Five bindable resource kinds

Resources are not an appendix to the concepts chapter; they explain why the same prompt behaves differently in two environments:

kindUI labelSourceHow many per agent
modelModelLocal model profiles plus the model gatewayMany, one of them default
mcpMCPLocal MCP catalog plus the cloud catalogMany
skillSkillInstalled Skills plus cloud Skill SpacesMany
knowledge-baseKnowledge baseCloud control planeOne
memory-instanceMemoryCloud control planeOne

Bindings live on the revision, so changing resources means changing the revision. Credential values never enter a revision — see Resources and bindings.

What this chapter covers

PageQuestion it answers
Agent · Revision · Build · RunWhat each freezing layer guarantees, and which operations break reproducibility
The three runtimesWho executes each of the three values, and how to read the capability matrix
Resources and bindingsThe shape, exclusivity rules and degradation behavior of the five kinds
Sessions and workspacesWho owns the event journal, and how the workspace boundary decides what is writable
Experts and local teamsHow expert templates and teams reuse the same freezing semantics
Managed runtimeWhere a cloud-resident runtime differs from a local one
GlossaryThe one correct spelling of every term
What you needWhich page
The full enumeration of the five identifiers and the capability matrixRuntime and entity contract
The 134 control-protocol operationsOperations
Error codes against user actionsErrors
The 16 session eventsSession events
The 19 deployment statesDeployment states

On this page