# Retire an agent

Stop serving a version to a tenant, deprecate old versions, and soft-retire an agent while keeping its history.

Retiring is three separate, reversible-in-different-ways decisions: stop a tenant serving a
version, mark a version as no longer a rollout target, and retire the agent registration itself.
None of them deletes evidence.

- `tanomis agent disable --tenants T` removes T's enablement. Sessions can no longer start; history
  stays.
- A version that nothing serves can be deprecated; it remains serveable for rollback.
- `tanomis agent rm` soft-retires the agent registration and preserves its audit history.

## 1. Stop serving a tenant

```bash title="Terminal"
tanomis agent versions support-copilot --by-tenant
tanomis agent disable support-copilot --tenants bluewater-bank
```

`disable` removes only the named tenants' enablement and records an audit event. It is idempotent:
a tenant that is not enabled is reported and skipped. The agent and its versions are untouched, so
re-enabling later is a `rollout`. There is no `all`; removing every tenant's enablement must be
explicit.

New sessions for that agent are refused in the tenant. Existing sessions keep their history and can
be read; whether an in-flight run completes depends on the runtime's state at the moment of the
change, so disable between runs where you can.

## 2. Deprecate a version

Once no tenant serves a version and you do not intend to roll it out again, deprecate it. A
deprecated version is not a target for new enablement but stays serveable for tenants already on
it, which is what makes [rollback](/guides/deploy/rollout-and-rollback#6-roll-back-to-the-known-good-version)
possible. Deprecation is a status transition; see [Versions and statuses](/guides/deploy/versions-and-statuses).

## 3. Retire the agent

```bash title="Terminal"
tanomis agent rm support-copilot --scope global
```

`rm` soft-retires exactly one agent registration. The scope selector is mandatory because global
and tenant-scoped agents may share a name; use `--scope tenant --scope-tenant-id TENANT` for a
tenant-scoped agent. History, versions, sessions, and ledger entries are preserved. Permanent
erasure is an administrator operation and is not reversible.

## Clean up locally

```bash title="Terminal"
tanomis agent delete-local support-copilot --agents-root ./agents
```

Removes the scaffolded directory from disk. It does nothing on the platform.

## Where to go next

- [Roll out and roll back](/guides/deploy/rollout-and-rollback): moving tenants between versions
  before you retire one.
- [Audit and evidence](/guides/audit/audit-and-evidence): where the disable and retire events
  land.