Agents and versions

An agent is a name; its versions hold the model, the prompt, and the grants. Sessions bind a version and keep it.

An agent holds no configuration. It is a name in a workspace and an identity for sessions to point at. Everything that decides how it behaves lives in an agent version.

subako agent create --name support-triage
subako agent list
subako agent show <agent-id>

Versions are immutable

Publishing does not edit anything. It appends a new version, and the newest live version is what a new session binds.

subako agent publish <agent-id> --config agent.json --model-provider <provider-id>
subako agent versions <agent-id>

A session binds its version once, at creation, and never re-binds. A version published mid-conversation does not change a session already running — which is what makes publishing safe during business hours.

Versions are permanent, and there is no way to retire one on its own. To move new sessions off a version, publish a newer one — agent versions marks the one a new session would bind.

Removing an agent is all or nothing:

subako agent delete <agent-id>

That takes the agent, all of its versions, and every session that ran them. Billing history is retained; the transcripts are not.

The configuration document

The shape belongs to the server; subako agent config-example prints the smallest thing that publishes, in the format your provider speaks.

{
  "system_prompt": "You are a helpful assistant.",
  "model": {
    "format": "anthropic",
    "model": "your-model-id",
    "max_tokens": 8192
  }
}

PropType

system_prompt?string

The standing instruction the model runs under.

Typestring

modelobject

Which model this version runs on: its format (anthropic or openai_responses), the model id, and the limits that go with it.

Typeobject

skills?array

Skills this version grants. A grant may pin a version number, or float to the skill's latest.

Typearray

mcp?array

MCP servers this version may call. The broker attaches credentials from the session's vaults at call time.

Typearray

The provider is named by --model-provider at publish time, not in the file. Its format must match the format the config’s model speaks — publishing an anthropic config against an openai_responses provider is refused.

Choosing what to grant

Grants are the agent version’s authority, and they compound: a skill tells the agent how to do something, an MCP server gives it somewhere to do it, and a vault — named per session, not per version — decides which credentials the broker will use.

That split is deliberate. The same published version can run against a production vault for one customer and a sandbox vault for another, with no republish in between.