AgentKit Studio
Concepts

Agent · Revision · Build · Run

An agent is a pointer, a revision is immutable, a build is content-addressed, and a run is one turn.

An agent is an editable configuration pointer, a revision is one immutable snapshot of it, a build freezes a revision into a content-addressed runnable package, and a run is a single turn executed against a build.

Each layer answers one question and no layer can replace another. This page covers what each freezes, why the split is necessary, and which operations break reproducibility.

Lifecycle of Agent, immutable Revision, content-addressed Build, Session and Run, showing that editing appends a new Revision while running sessions stay putLifecycle of Agent, immutable Revision, content-addressed Build, Session and Run, showing that editing appends a new Revision while running sessions stay put (dark)点击放大 · 滚轮缩放 · 拖拽平移

How to read this: each stage freezes at a different level. Editing an Agent only appends a new Revision, and a running session stays bound to the old one — this is not a missing hot reload, it is the precondition for "one revision plus one engine always yields the same run identity".

Why these cannot collapse into one layer

With only an "agent" concept, two requirements cannot both hold:

RequirementConsequence of one layer
Editing configuration must not affect sessions already runningYou must choose: forbid editing, or let in-flight sessions drift
The same configuration must rebuild into the same artifactBuild IDs can only carry timestamps, so every rerun is a "new version"

Splitting the layers satisfies both, at the cost of always knowing which layer you are editing. This table is the answer:

LayerWhat you changeAffectsDoes not affect
AgentName, description, which snapshot it points atThe list and future editsExisting revisions and builds
RevisionPrompt, runtime, resource bindingsThe next buildBuilds already produced
BuildThe artifact itselfRuns started from itRuns already finished
RunOne conversationNothingNothing (finished the moment it ends)

Agent: a current pointer and nothing more

A local agent ID looks like ar-local- followed by 16 hex digits; any other shape is rejected (INVALID_AGENT_ID). Revision 1 is written the moment the agent is created, so there is no such thing as an unsaved agent.

The agent record holds two things: metadata (name, description, revision sequence number, timestamps) and which snapshot it currently points at. It stores no history — history lives in the revisions directory.

Revision: append-only

Every save writes a new revision number. Files for older numbers are never rewritten. The rules have concrete consequences:

  • Overwrites are rejected. If the target revision file exists with different content, the result is AGENT_REVISION_CONFLICT. This is a hard failure, not a warning.
  • Concurrent edits carry an expected number. When expectedRevision does not match the current value, the result is AGENT_EXPECTED_REVISION_CONFLICT with both expectedRevision and actualRevision, so you can decide whether to reload or give up. An invalid number is INVALID_EXPECTED_AGENT_REVISION.
  • Publication per agent is serialized. The lock waits at most 5 seconds, then returns AGENT_MUTATION_BUSY ("the agent is being updated, retry shortly").
  • Lost authority is explicit. If the caller stops holding write authority after an asynchronous wait, the result is AGENT_UPDATE_AUTHORITY_LOST rather than a silent write into a stale state.
  • Crash semantics are conservative. The revision is written first, the pointer second. A crash between the two leaves an immutable revision for explicit recovery, never a silent replacement.

A revision is a sequence number, not a version

It is a positive integer starting at 1, with no major/minor semantics. Comparing revision numbers across agents means nothing.

Build: content-addressed, therefore idempotent

A build ID looks like build_ followed by 20 hex digits, derived from the first 20 characters of the manifest's SHA-256. The same revision plus the same execution engine always produces the same ID — rebuilding is idempotent and never invents a "new version".

RuleBehavior
Two bundle formatsagentkit.agent-bundle/v1 for everything except Star Harness; v2 for Star Harness, because the execution engine is frozen too
Exactly three entriesagent-bundle/manifest.json, agent-bundle/spec.json, agent-bundle/README.md
Execution engine swappedBUILD_ENGINE_BINDING_CHANGED; a new engine may not interpret an old package
Download ceilingOver 4 MiB returns BUILD_DOWNLOAD_TOO_LARGE
Tampered artifactThe manifest/spec correspondence is re-verified; a mismatch returns BUILD_ARTIFACT_INVALID
Artifact missingBUILD_NOT_FOUND

Other build errors: BUILD_AGENT_ID_INVALID (agent ID format), BUILD_REVISION_INVALID (revision is not a positive integer, or disagrees with the agent definition), BUILD_DEFINITION_INVALID (no valid agent definition), BUILD_ID_INVALID (build ID format).

A successful build always ends in status SUCCEEDED. There is no partial success — a package is either completely usable or absent.

Run: one turn, five identifiers

A complete run identity needs all five fields: agentId, revision, buildId, sessionId, runId. Any missing field returns RUN_IDENTITY_INVALID; revision must be a positive integer starting at 1.

When a run is bound to a concrete route (a session tab, for instance), agentId and sessionId are additionally checked against that route; a mismatch returns RUN_IDENTITY_MISMATCH. This guards against triggering session B's run from session A's view.

Runs are driven by DSH session events: turn/start opens a turn, turn/end closes it, and step/start, tool/call and tool/result in between all share one runId. The vocabulary lives in Sessions and workspaces.

Frozen runtime: what a build locks down

A Star Harness build additionally freezes its execution engine (agentkit.build-engine/v1), so "upgrading the engine" is a new build rather than a configuration change. The runtime itself has two fixed budgets:

ItemDefaultCeilingOut-of-range behavior
Per-run timeout15 minutes24 hoursA non-positive-integer or sub-1-second value falls back to the default instead of silently becoming 0
Host capabilityMust support request fingerprints—Otherwise RUNTIME_HOST_CAPABILITY_UNAVAILABLE
Frozen model routeMust resolve—Otherwise RUNTIME_MODEL_UNAVAILABLE

"Frozen" means: whatever model routes the build recorded are the only routes the runtime may use. Models available outside the build are never selected.

Hard rules

  1. A revision is append-only. Overwriting is an error, not a policy.
  2. A build ID depends only on content. Same input, same ID; a different ID means genuinely different content.
  3. All five run identity fields are mandatory. Missing any one is an error with no degraded form.
  4. Swapping the execution engine requires a new build. An old package is never interpreted by a new engine.
  5. Editing only ever creates a new revision. No existing revision is ever "updated".
What you needWhich page
The five identifiers and the full agentkit.studio.runtime/v1 shapeRuntime and entity contract
Parameters of the four builds/* operationsOperations
BUILD_*, AGENT_* and RUN_* error codesErrors
The 16 session events and 3 stream framesSession events

On this page