Agents and versions

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.

At a glance

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

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 for the full procedure.

Promotion is not a rollout

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.

Models and the LLM gateway

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

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.

Where to go next

• Deploy a version: what happens between tanomis agent deploy and an enabled tenant.
• Roll out and roll back: canaries, graduation, and rollback.
• Policy, approvals, and evidence: the controls a version’s contract participates in.