# What is Runbook?

Also called operational runbook, playbook.

A runbook is a written procedure for handling a specific operational situation, listing the steps to diagnose and resolve it in order. It exists so that a responder who did not build the system can act correctly under time pressure, without reconstructing knowledge that someone already has.

A useful runbook is narrow and concrete. It names the alert or symptom it applies to, states how to confirm the situation is the one described, gives exact commands or dashboard links rather than descriptions of where to look, lists decision points with explicit criteria, and says what to do when the procedure does not resolve the problem. Broad documents covering a whole subsystem are reference material, not runbooks.

The failure mode is staleness. Commands change, dashboards move, service names change, and a runbook that sends a responder down a dead path during an incident is worse than none, because it consumes attention at the worst moment. Keeping runbooks in the same repository as the code they describe, linking them from the alert that triggers them, and updating them as part of incident review are the mechanisms that keep them alive.

Runbooks are the natural precursor to automation. A procedure that has been executed reliably several times, whose decision points have clear criteria, is a candidate to become a script or an automated remediation. Writing the runbook first is valuable even when automation is the goal, because the act of writing exposes the steps whose criteria were never actually defined.

For AI systems the situations worth documenting differ from classic infrastructure. Alongside restarts and failovers, teams need procedures for disabling a tool an agent is misusing, rolling a prompt back to a prior version, draining a queue of pending agent actions, and identifying which runs were affected by a bad model configuration during a window. These are rarely obvious to a responder who has not done them before.

## Key points

- Narrow procedure for one symptom, with exact commands and links
- Must state how to confirm the situation and when to escalate
- Stale runbooks actively harm response, so they live beside the code
- A stable runbook is the natural candidate for automation
- Agent systems need prompt rollback and tool disable procedures

## In practice

An alert for rising agent tool error rates links to a runbook. It lists the query that groups recent failures by tool name, the dashboard filtered to the last hour, and a decision table: a single tool failing means disable that tool's flag, all tools failing means check the provider status page, and errors confined to one tenant means inspect that tenant's stored credentials. Escalation contacts appear at the end.

## Related terms

- [Incident](/en/glossary/incident)
- [Alerting](/en/glossary/alerting)
- [Postmortem](/en/glossary/postmortem)
- [Mean Time to Recovery](/en/glossary/mean-time-to-recovery)
- [Kill Switch](/en/glossary/kill-switch)

[Back to the AI Glossary](/en/glossary)