Guide
Retire an agent without leaving its authority behind
An agent that has not called recently is a retirement candidate, not proof that its authority is unused. It may run monthly, respond to rare incidents, or have descendants that still matter.
Before retiring it, find out what depends on it and who can approve permanently removing its authority. It is a different operation from emergency containment: the objective is to remove authority without surprising owners or destroying the evidence needed to explain past activity.
Find out what still needs the agent
Start with the operational registry record. Confirm the owner, purpose, execution environment, schedule, resource access, and any parent or descendant relationship.
Ask the owner what would break if the agent stopped for one full business cycle. A quarterly reconciliation workload can look abandoned during several quiet weeks. Recent activity is one signal; it is not a complete dependency inventory.
Use the agent lifecycle documentation for the state transitions available in the release you operate. Lifecycle changes affect the agent's authority through Dome. They do not remove its code from a scheduler or erase copies of backend credentials outside that path.
A retirement record
Fill in this record before revoking the agent:
| Field | Required decision |
|---|---|
| Agent and scope | Exact identity to retire, with tenant and workspace |
| Owner | Person accountable for accepting the impact |
| Usage horizon | Schedule and observation period that cover legitimate use |
| Dependencies | Jobs, applications, delegated workflows, and descendants to assess |
| Replacement | Successor identity or an explicit decision that no successor is needed |
| Reversible checkpoint | Whether an approved suspension/observation stage is appropriate |
| Terminal action | Who approves revocation and understands its descendant impact |
| Credential follow-up | Which independently managed credentials or jobs need separate action |
| Evidence retention | Where prior audit and ownership records remain available |
| Completion checks | Expected refusals, remaining dependencies, and reviewer |
Do not turn this into a bulk “revoke everything quiet for 30 days” rule. A cleanup candidate requires an owner decision.
Consider an observation period before revoking
For a planned retirement, an approved suspension can provide an observation period before permanent revocation. Choose the interval from the workload's cadence, not from an arbitrary short timer.
Resolve the exact affected agent set first. If descendants are involved, verify the cascade behavior in your deployed release and record which identities will change. Do not assume that every child is either active or irrelevant.
Notify dependent teams, then look for the expected refusals and for unexpected callers. Keep the restoration decision explicit. A suspended agent should not be reactivated automatically simply because a dependency complains; the complaint may reveal a missing migration.
If the workload cannot tolerate an observation pause, establish dependency evidence another way and document that limitation. Reversibility is useful only when the interruption itself is acceptable.
Revocation can't be undone
Revocation is permanent in Dome and applies to the affected descendant chain described by the lifecycle model. Confirm the full non-revoked descendant set before approving the operation. A child agent is not protected from the parent's terminal decision merely because it currently serves another team.
Migrate legitimate dependents before revoking. If a replacement agent is needed, create and authorize it deliberately; do not treat the old identity as a reusable label for a new workload.
After the change, test the retired identity's expected refusal through the intended path. Also verify that the replacement, if any, still performs its narrow allowed work. A negative test alone cannot show that the migration succeeded.
Clean up schedules and separate credentials
Disable obsolete schedules and deployments through their owning systems. Review backend credentials separately: rotate or remove a credential only after checking whether other workloads share it. Retiring one agent does not authorize deleting a shared provider account.
Preserve audit history and the retirement record according to the organization's retention policy. Removing a workload's authority and deleting its historical evidence are separate decisions.
Finally, mark the registry record with the terminal outcome, date, owner, successor, and evidence links. Keep any unresolved external cleanup visible instead of calling the whole retirement complete.
Close the retirement when the old identity is refused, legitimate work has moved or ended, and the ownership and audit records are retained. If an old schedule or separate credential still needs attention, leave that work visible.