# Agents and versions

An agent is a name; a version is an immutable build plus its declared contract; enablement decides which tenants a version serves.

An agent on Tanomis is not a container you run. It is a name that owns a lineage of immutable
versions, and a set of per-tenant decisions about which version serves each tenant's traffic.

- **Agent**: a stable name, such as `support-copilot`.
- **Version**: one immutable build of that agent, with the manifest contract captured at
  registration. Change anything and you publish a new version.
- **Enablement**: a tenant-scoped assignment that says "this tenant serves this version". No
  version receives traffic until a tenant is enabled for it.
- **Warm start**: a version's sessions start from a pre-built snapshot when one exists, so a new
  session is ready in well under a second instead of booting the harness cold.

## A version is immutable

`tanomis agent deploy` packages your source deterministically, builds it remotely, and registers the
result as a version with everything the manifest declared: entry point, harness, models, network
egress, policy ceiling, connectors, resources. That contract is validated at registration and
frozen for the version's lifetime.

This is what makes rollouts safe. A version that served traffic yesterday will behave the same way
today, and rolling back means enabling a version that already exists rather than rebuilding
anything.

## Version status and enablement are separate

A version has a **status**: it starts as a draft, and it must be at production status before a
tenant can serve it. Promotion changes the global status only. It routes no traffic on its own.

A tenant has an **enablement** for the agent: which version it serves as the baseline, and
optionally which version it serves as a canary at a percentage share. Enablement is the commit
point, and it is always tenant-scoped.

```bash title="Terminal"
tanomis agent versions support-copilot --by-tenant   # who serves which version
tanomis agent rollout support-copilot --version v2 --tenants acme-prod --canary-share 10
```

`rollout` does both steps for the tenants you name: it promotes the version if needed, then
enables it for exactly those tenants, as their baseline or as a canary. Other tenants are never
touched. See [Roll out and roll back](/guides/deploy/rollout-and-rollback) for the full procedure.

`tanomis agent promote` moves a version to production status and nothing else. If you want a tenant to
serve it, enable it for that tenant, or use `rollout`, which does both.

## Warm starts

For a deployed version, Tanomis builds a golden snapshot: a checkpoint of the agent's warmed-up
process taken over an empty workspace, containing no tenant data. When a session starts, the
snapshot is restored and the session's own workspace is mounted into it, so the first turn does not
wait for the harness to boot.

You do not manage snapshots. The deploy builds or reuses one before the tenant is enabled, so the
first session never races the build. A version whose snapshot could not be produced still deploys;
its sessions start cold, and the deploy output says so.

Idle sessions are suspended the same way and restored when work arrives. An idle session costs
storage, not a running process, which is why sessions can be long-lived. See
[Sessions and runs](/concepts/sessions-and-runs).

## Models and the LLM gateway

A version declares the model it uses and, optionally, the models a run may request:

```yaml title="agent.yaml"
model: "your-workspace-model-id"
permitted_models:
  - "your-workspace-model-id"
```

Every model call from an agent goes through the tenant's LLM gateway. That is where model access
is authorized, where usage is metered per run, and where model traffic is traced. An empty
`permitted_models` does not widen access: the decision falls to platform and tenant policy. A run
that requests a model outside the allowlist is refused.

## What a version carries

| Declared in `agent.yaml` | What it governs | Where it is enforced |
|---|---|---|
| `entrypoint`, `framework` | How the harness starts your code | Build and runtime |
| `model`, `permitted_models` | Which models a run may call | LLM gateway |
| `network.egress` | Which external hosts the agent may reach | Deploy (grammar and tenant ceiling), runtime proxy |
| `policy.approval_required_tools`, `policy.enable_ask_user` | Which actions pause for a person | Runtime, as durable interactions |
| `policy.scope_ceiling` | The most authority the agent's own tokens can carry | Delegation and token exchange |
| `integrations` | Which governed tools the agent may call | Gateway, per tool |
| `delegation` | Whether the agent calls or accepts work from other agents | Control plane, per call |
| `session.idle_timeout`, `session.max_lifetime` | How long a session lives | Session lifecycle |

The complete field list, defaults, and validation rules are in the
[Agent manifest reference](/reference/agent-manifest).

## Where to go next

- [Deploy a version](/guides/deploy/deploy-a-version): what happens between `tanomis agent deploy`
  and an enabled tenant.
- [Roll out and roll back](/guides/deploy/rollout-and-rollback): canaries, graduation, and
  rollback.
- [Policy, approvals, and evidence](/concepts/governance): the controls a version's contract
  participates in.