Writing a Shutdown Section for an Agent Runbook

Before you write a single step, write one sentence that defines what "stopped" means. Security teams distinguish two levels: containment, which denies specified consequential actions, and quiescence, which additionally requires running execution and outstanding work to reach verified terminal states the operational analysis. A paused job is not terminal. A completed job may already have produced effects you need to reverse.

Three artifacts make the objective reviewable:

1. Stop scope. Which effects are forbidden (outbound email, database writes, file exports, payment submissions), which execution units must end (containers, jobs, scheduled triggers), and what collateral damage is acceptable while you stop.
2. Shutdown protocol. The numbered steps, each with an owner, a dependency and a failure path.
3. Acceptance report. Observed coverage, timing and persistence, written during the incident, not reconstructed afterward.

Build the scope from what actually grants the agent power: credentials, reachable destinations, writable resources and submitted work. "All registered action paths are closed" is a bounded, checkable claim. "The agent cannot cause harm" is not the operational analysis. For example, an invoice agent might have four paths: an enterprise API, a model provider, local file writes and a job queue. Revoking the API credential closes one of four. If the business harm is duplicate invoice submissions, then the queue matters more than the model credential, and the checklist must be ordered accordingly.

A practical decision rule: rank every step by the consequences it removes, not by how easy it is to perform. If a queued job needs no further model call, blocking model access does nothing for that exposure. Teams that reorder around convenience gradually redefine "successful containment" as "the admin action we knew how to do quickly."

Write the section as a numbered checklist, one line per step, with these columns: step, action, owner role, time budget, verification command or check, and rollback or escalation if the check fails. Aim for a complete run in under 30 minutes for a single agent, and state that budget at the top of the section so the on-call engineer knows the target.

Three details in that table carry most of the weight:

Freeze ingress before snapshotting. If the agent keeps accepting work while you copy logs, the evidence is moving under you and the queue keeps growing. The exception is a partial throttle, which sometimes beats a hard stop because a half-completed write is harder to reason about than a bounded intake. Write down which of the two your team defaults to.

Verification means the resource denies, not the issuer responds. Revoking a refresh token stops new issuance. It does not prove the resource rejects an access token already in hand. The OAuth revocation specification requires support for refresh-token revocation, recommends access-token revocation, and acknowledges propagation delay RFC 7009 via the operational analysis. Self-contained tokens can be validated locally, so issuer-side changes need resource-side enforcement to bite immediately. Your verification step should be an actual denied call from the agent's identity, not a green checkmark in an admin console.

Snapshot before you kill. Terminating processes destroys the fastest source of evidence: in-memory state, the current context window, the exact tool call in flight. Capture first, unless execution is actively causing harm, in which case your scope document should say so and you swap steps 4 and 6 in that specific scenario.

Here is a verification sequence you can adapt for the credential step, written as a test anyone on call can run:

# 1. Confirm the token is rejected by the resource, not just the issuer
curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  https://api.example.com/v1/orders
# Expect 401. A 200 means revocation has not propagated.

# 2. Confirm execution units are gone
kubectl get pods -l agent=invoice-bot -o wide
# Expect empty list, then wait one full observation window and repeat.

# 3. Confirm no queued work can start
kubectl get jobs -l agent=invoice-bot
# Expect no active jobs; inspect any parked items one by one.

The acceptance report is the last artifact: a short record of what was checked, when, by whom, and what was observed, per the runtime policy guidance that a stop needs a testable outcome the operational analysis. It doubles as the evidence a board or auditor asks for, alongside activation thresholds and named owners the governance discussion.

The most common way a written shutdown section fails is that it stops the visible thing. For a conversational agent, that means revoking model access. But the same runtime often holds cloud API rights, code execution, Kubernetes access and MCP tool connections. The control surface has to cover all of them.

Sort the agent's tools into tiers and write the shutdown treatment for each tier into the runbook:

That tiering mirrors the human-in-the-loop guidance that recommends explicit approval on high-impact or irreversible actions, action previews before execution, and four risk levels from reads up to irreversible changes the runtime policy guide. The same guide recommends a unique agent identity with a named owner, denying unreviewed tools by default, and testing revocation paths, all of which belong in the shutdown section as prerequisites.

For sandboxed code agents, add an egress check to the checklist. Start with an explicit list of destinations, operations and credentials each task needs, then test network controls from inside the actual runtime, because a policy file alone does not prove enforcement the sandbox security guide. Where an egress gateway is the enforcement point, test what happens when the gateway is unavailable: the intended result is a failed task with a clear error, not a silent route around the restriction. Keep infrastructure control credentials outside agent-controlled processes, and validate that revocation works while a task is still running by checking what the application does when its next authenticated request fails.

A checklist nobody has executed is a hypothesis. Incident-response practice treats discussion-based exercises (tabletops) as the low-risk entry point, then moves to functional exercises where participants actually perform the tasks in a simulated environment the tabletop guide. A shutdown rehearsal should be a functional exercise: someone really revokes a test credential, really kills a test job, really runs the verification command.

A schedule that holds up:

The single-step drill is where most of the value sits. Pick the step people are least sure about, usually credential revocation, and have the on-call engineer run only that step plus its verification during a calm week. If the verification fails, you have found a propagation delay or a caching problem while nothing is on fire.

The review loop after a real stop follows the same discipline as an incident postmortem: reconstruct the timeline from logs, identify which step was late or skipped, and change the document rather than the memory. Record the actual per-step durations in the acceptance report and compare them with the budgets. Two patterns typically show up. First, the step everyone thought took three minutes took nine because a console page was deprecated. Second, a step failed outright because the owner role was ambiguous. Both fixes are edits to the runbook, and both disappear if nobody writes them down.

Treat the checklist as versioned code. Keep it in the same repository as the agent's deployment configuration, review changes like a pull request, and link the current version from the alert that fires the stop rule. Runbooks that live in a wiki drift from reality, which is exactly why responders stop trusting them at 3am and improvise the runbook automation summary.

Seven failure modes account for most of the gap between a documented shutdown and an executed one.

Stop authority without decision rights. If the threshold is undefined or the owner is unnamed, the stop becomes a meeting. Fix it by writing the trigger conditions, the named role that can fire without asking, and the escalation path into the same section.

Credential revocation mistaken for termination. A revocation response proves the issuer acted. It does not prove the resource rejected an in-hand token, and cached active responses can keep a revoked token usable the operational analysis. Fix it with a denied-call verification as in the script above.

Stopping the model and leaving the workload. Termination removes execution units, not outstanding work. Queued submissions, accepted jobs and scheduled triggers need their own drain step with a terminal-state definition the operational analysis.

Unverified egress controls. Kubernetes network policies are additive, and another matching policy can allow traffic you expected to block the sandbox security guide. Test from inside the sandbox and test direct IP access, not just DNS.

Vendor promises in place of local controls. Waiting for a model provider or cloud host to decide in a crisis is not control the governance discussion. Contract language, testing and compensating controls are the mitigations, but the checklist must be executable with what you hold.

A runbook that was never rehearsed. The tabletop literature is blunt: tabletops reveal unclear authority, slow handoffs and conflicting assumptions that penetration tests cannot the tabletop guide. A shutdown section is a claim about authority. Rehearse it.

No restart path. A shutdown with no documented criteria for resuming invites pressure to "just turn it back on." Write the restart conditions, the approver, and what must be fixed before the stop signature is cleared, alongside the shutdown steps in the same record.

The shutdown section sits inside a wider operating model. Someone has to own the agent in production after the build team moves on: stability, observability, runbooks and long-term health are a distinct role, and it is the role programs most often forget to staff the vision AI team blueprint. The same split applies to any agent in production. A builder takes the agent from zero to one; a scaler ports it across teams and works themselves out of each deployment; an operator keeps it trusted for years. The shutdown section belongs to the operator, not the builder, and the operator should be the one who signs off on each drill.

When you assemble the drill, invite the roles that make decisions rather than just the engineers who run commands. Cross-functional tabletops are designed to validate escalation paths and clarify ownership of decisions such as system shutdowns, and to test out-of-band communication when email or chat may be compromised the tabletop guide. A shutdown drill that only involves the platform team proves the commands work. It does not prove that legal, communications and the business owner know who speaks and when.

One more habit keeps the document accurate: let the drill produce the edit. Every functional exercise ends with a dated diff to the checklist, and every diff gets a retest of the changed step at the next monthly micro-drill. That loop, not the initial writing, is what makes a written stop rule hold up at 3am.

If your team is standing this up for the first time, a structured review of the current stop rules, action paths and owner roles can save a quarter of guesswork. The Quanta experts can work through your agent's shutdown plan with you and hand back a completed runbook and drill calendar as deliverables.