An effective runbook for AI agent on-call answers three questions in order for whoever is paged: what kind of incident is this — availability, cost, quality, or a combination — what is the fastest way to stop further damage, and what is the diagnostic path to root cause once damage is contained. This structure differs from a conventional infrastructure runbook because an agent incident routinely has dimensions a web-service incident doesn't: a misbehaving agent can simultaneously be down, expensive, and producing wrong output, and the runbook has to route the responder to the right containment action for each dimension rather than a single restart step.
This post assumes you already have the observability foundation — see observability for AI agents — and the SLOs that turn signals into alerts — see SLOs for AI services. This is about what happens after the page fires.
Why "restart the service" doesn't work here
The default first step in most infrastructure runbooks is some version of "restart the affected instance" — a reasonable first move for a stateless service where a bad process state is a common cause of trouble. For an agent incident, restarting a worker process rarely fixes anything, because the problem usually isn't in the process — it's in the prompt, the policy, the provider, or the task data the agent is operating on. A restart clears in-memory state and does nothing for a prompt that's causing every task of a given type to fail, a guardrail rule that's misfiring, or a provider that's degraded.
A useful agent runbook replaces "restart" as the default first move with "classify," because the correct next action depends entirely on which category the incident falls into.
Classify before you act
| Incident signature | Likely category | First containment move |
|---|---|---|
| Token burn rate spikes with no proportional task-volume increase | Cost incident (runaway agent or loop) | Cap or pause the specific agent or organization driving the spike; see threat model: runaway agent spend |
| Task success rate drops, error rate flat | Quality incident | Check for a recent prompt or model version change first, before assuming an infrastructure cause |
| Queue depth climbs, task success rate flat | Capacity incident | Check provider rate-limit and token-throughput signals before assuming a compute problem |
| Guardrail intervention rate spikes or drops sharply | Policy incident | Check for a recent policy or guardrail bundle change; a sharp drop can mean a rule silently stopped firing, not that behavior improved |
| Agent count or availability drops | Availability incident | Check control-plane health and agent liveness signals before assuming a fleet-wide problem |
Most real incidents are a combination — a runaway agent is both a cost incident and, if it's consuming shared provider quota, an availability incident for every other agent sharing that quota. The classification step isn't about picking exactly one category; it's about identifying every category in play so the runbook routes to every relevant containment action, not just the first one that matches.
Containment first, root cause second
Every runbook needs a containment step that is explicit, has its own trigger condition, and does not wait for root-cause analysis to complete. This is a deliberate separation: stopping the damage is urgent and often does not require understanding why it's happening; understanding why is important but can proceed after damage is contained.
Concretely, containment for agent incidents usually means one of:
- Pause or kill the specific agent implicated by the classification signals. See rogue AI agents and kill switches for what a fast, dependency-independent kill mechanism looks like.
- Revert the most recent change — prompt, policy, or model routing — if the incident timeline correlates with a recent deploy. This is frequently faster and more reliable than root-causing the specific defect in the change. See versioning and rollback for AI agents.
- Apply or tighten a budget cap for cost incidents, even before you know exactly why the spend spiked. See budget policies and hard spend caps.
- Escalate to a human-in-the-loop approval gate for actions the agent is attempting that look anomalous, rather than letting them proceed while you investigate. See human-in-the-loop approvals for agents.
The runbook should state the trigger condition for each containment action explicitly — "if token burn rate exceeds your alert threshold for the affected agent, pause that agent" — rather than leaving the judgment call to the on-call engineer to invent under pressure at three in the morning.
Structuring the runbook as a decision tree
A flat checklist works for a single, well-understood failure mode. Agent incidents rarely present cleanly, so the runbook is more useful structured as a decision tree: a sequence of yes/no diagnostic questions, each backed by a specific signal to check, that narrows down the category and points to the corresponding containment and remediation steps.
A minimal decision-tree structure:
- Is token or cost burn rate abnormal relative to baseline? If yes, treat as a cost incident: identify the responsible agent or organization, apply containment, then investigate.
- Is task success rate degraded while error rate is flat? If yes, treat as a quality incident: check for a recent prompt, model, or policy change before anything else.
- Is queue depth or latency degraded? If yes, check provider and downstream tool signals before compute signals — queue depth is usually the earliest visible symptom of a capacity ceiling being approached, well before task failures appear.
- Is guardrail intervention behavior anomalous? If yes, check for a recent policy change and treat any unexpected drop as seriously as an unexpected spike.
- None of the above, but agents are unresponsive? Fall back to a conventional infrastructure diagnostic path — control-plane and network health.
Each branch should link directly to the specific containment action and the specific dashboard or query needed to confirm the diagnosis, so the on-call engineer isn't searching for the right tool mid-incident.
Getting the on-call engineer to the right runbook
A well-written runbook that nobody can find during a page is not a working runbook. Maintain an explicit mapping from each alert configuration to the runbook it should trigger, and test that mapping — not just the runbook content — as part of your incident-readiness practice. See the AI incident readiness checklist and running an AI agent incident tabletop exercise for how to verify this end to end, from alert firing to the responder having the right document open.
Keep runbooks current
Agent runbooks go stale faster than infrastructure runbooks, because the systems they describe change more often. A prompt shipped last week can change which failure signatures are plausible. A policy bundle rewritten last month can change which containment action is correct. Review runbooks on the same cadence you review prompt and policy releases, and treat a runbook update as part of the deploy checklist for any change that alters agent behavior, not as separate documentation maintenance that happens on its own schedule.
After every real incident, update the runbook that was used — or write one if none existed — as part of the post-incident review, not as a follow-up ticket that may or may not get done. See post-incident forensics for AI agents.
Writing steps a stranger can follow
The test of a runbook step is whether an engineer unfamiliar with the specific agent or workflow can execute it correctly under pressure. That means every diagnostic step needs to name the exact signal to check and where to find it, not a vague instruction like "check if the agent looks healthy." Every containment step needs to name the exact action and its trigger condition, not "consider pausing the agent if it seems necessary." Ambiguity that a runbook author would resolve instinctively, because they wrote the system, is exactly the ambiguity that costs the most time for whoever is actually paged.
It also helps to write the runbook from an incident that already happened, using the real signals that were checked and the real action that resolved it, rather than drafting one speculatively for a failure mode nobody has seen yet. A runbook grounded in a real incident tends to be more specific and more trustworthy than one written from first principles, and it can always be generalized once a second, similar incident confirms the pattern holds.
What good looks like
A working agent on-call runbook set classifies incidents by category before prescribing a fix, separates containment from root-cause investigation with explicit trigger conditions for each containment action, is structured as a decision tree keyed to real observable signals rather than a flat checklist, is reachable from the alert that fires it through a tested mapping, and gets revised on the same cadence as the prompts and policies it covers. The test of a good runbook is whether an engineer who has never seen this specific failure before can still act correctly at three in the morning.