---
title: Agents and versions
description: An agent is a name; its versions hold the model, the prompt, and the grants. Sessions bind a version and keep it.
sidebar:
  order: 2
---

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**.

```bash
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.

```bash
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:

```bash
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.

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

| Prop | Type | Default | Description |
| - | - | - | - |
| `system_prompt?` | `string` | - | The standing instruction the model runs under. |
| `model` | `object` | - | Which model this version runs on: its format (anthropic or openai_responses), the model id, and the limits that go with it. |
| `skills?` | `array` | - | Skills this version grants. A grant may pin a version number, or float to the skill's latest. |
| `mcp?` | `array` | - | MCP servers this version may call. The broker attaches credentials from the session's vaults at call time. |

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.

:::warning
The model id itself is not validated at publish time. A typo publishes cleanly and fails when a session runs against it.
:::

## 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.