# Roll back a Live agent configuration

> Review an exact prior approved version and restore its definition as a new immutable publication.

Section: Synapse and Locus. Web page: https://docs.katara.com/products/agent-rollback/

Controlled rollback requires the agent publication and rollback
services enabled for your environment. It does not run a quality evaluation or
recover an unavailable dependency.

Rollback copies an exact prior approved Live definition into a new immutable version.
For example, restoring version 3 while version 7 is current publishes version 8 with
version 3's definition. The prior versions remain unchanged. This operation does not
move a deployment pointer or erase publication history.

Use a signed-in human owner session. The selected environment must be Live. API keys, service accounts and workloads cannot
review or activate a rollback.

## Select the versions and current authority

Pin the current head's ID, revision and integrity, then the earlier version to restore.
Both must belong to the same agent in the selected Live environment. The restore
version must have recorded approved publication provenance, remain unrevoked and
pass current source and dependency checks. An arbitrary earlier publication is not
sufficient merely because its revision is lower.

A broken or revoked current head can still be identified for rollback. That does not
make a revoked restore version usable. Current source, model, tool, collection and
policy dependencies must support the definition being restored.

Select current grants, payer consent and funded limits for the restored definition.
Each grant must pin the selected agent authority epoch and cover its required actions
and resources. Old grants, credentials, budget settings and balances are never restored
from the historical version.

## Review the prepared publication

Call `client.agentRollbacks.review(scope, request, key)` in TypeScript or
`client.agent_rollbacks.review(scope, request, key)` in Python. The request includes:

- The exact Live environment and its current authority and reset generation.
- The agent ID and subject authority epoch.
- `current_version` and `restore_version`, each with ID, revision and integrity.
- Explicit selected grants and current funding.

The returned review contains the signed restore version, the exact prepared target
version, dependency and preparation digests, creator and review digest. The target
must copy the restore definition and have revision `current_version.version + 1`.
Reviewing this response does not publish it.

Inspect the restored sources, model, tools, policies, limits and selected funding.
`getReview` / `get_review` reloads the review under current authority and dependency
checks. `listReviews` / `list_reviews` lists the environment's rollback reviews, newest
first, each saying whether it was activated so its receipt can be read instead. A
listed review is not rechecked; reading it is. If the head, source or dependencies changed, review the current state again;
do not silently replace the reviewed version or funding.

## Activate the exact review

Call `activate(scope, review, key)` only after reviewing the prepared publication.
Both SDKs submit its exact review digest and target version ID with
`acknowledge: true`. The request requires your own idempotency key.

Activation checks the current head and all required authority again. It publishes
the new immutable version and records the receipt in one transaction. If a required
check or receipt write fails, the publication is not committed.

The receipt identifies the exact restored and newly published versions. Read it with
`receipt(scope, reviewID)`; pass the saved review as the optional third argument for
additional client-side comparison. A receipt records that publication completed. It
does not claim a new evaluation, restored historical permissions, cancelled existing
runs, or recovery of customer data or external tool side effects.

After a lost activation response, keep the saved review, request body and original
idempotency key. Retry only that same reviewed request and key to recover the result.
The SDKs make no automatic retry. A new key is not a recovery mechanism.

Cookie-based applications must keep the reviewed account binding. If the signed-in
account or selected scope changes, discard the current selection and reload before
another decision. See [access](https://docs.katara.com/products/access.txt) and the [product API reference](https://docs.katara.com/product-api.txt)
for account checks and exact route fields.