Enough for someone who did not build the agent to run it, stop it and recover from its mistakes at three in the morning. That means who owns it, what it may do, the daily routine, signals and thresholds, how to lower its depth, how to route work to people, how to roll back, and who to call.
Why does an agent need its own runbook?
A general IT runbook, as described in what a runbook is, covers keeping a system up. An agent adds a different question: not only "is it running?" but "is it doing the right thing, and is it allowed to?". The person on call needs to know what the agent may do at each depth, how to read its verdicts, and what to do when it is running perfectly well but making the wrong decisions.
Agents also fail in quieter ways than servers. A rising edit rate or a growing held queue is often the first sign. A runbook that only covers outages misses the failures that matter most.
What sections should it have?
| Section | What it contains | Who maintains it |
|---|---|---|
| Identity | Agent name, owner, deputy, capabilities with current depth, certificate dates, model and version | Process owner |
| What it may not do | Bounds, the customer's limits, and actions withheld at the platform floor | Process owner |
| Daily routine | Held queue review, sample checks, end-of-day reconciliation | Team lead |
| Signals and thresholds | Hold, escalation, refusal and edit rates; source availability; what level triggers what | Process owner |
| Lowering depth | Exactly how to drop a capability to depth 1, who may do it, how it is recorded | Platform owner |
| Routing work to people | Which queue goes to which team, and how to switch | Operations lead |
| Rollback | How to restore the last certified version and review actions since a set time | Platform owner |
| Outages | What to do if the model provider or a connected system is down | Platform owner |
| Incidents | Classification, who to inform, reporting duties, customer correction | Risk |
| Changes and recertification | How changes are made, tested and released; the recertification calendar | Process owner |
| Contacts | On-call rota, escalation names, provider support | Team lead |
The AI agent runbook template turns this into fields you can fill.
Which sections are specific to agents?
Three sections have no real equivalent in an ordinary runbook.
What it may not do. The on-call person must be able to tell at a glance whether an action was outside the agent's bounds, inside them but wrong, or withheld for every agent. That decides whether the problem is the agent, its configuration or something else.
Lowering depth. This is the agent's equivalent of pulling a plug, but gentler: the agent keeps reading and reporting, so you do not lose visibility. The runbook should say exactly how, in steps someone can follow under pressure, and confirm that no second approval is needed to make the agent safer.
Reading a verdict. Every filed verdict names the bound that decided it. The runbook should show one example and explain each field, so a person on call can work out what happened without asking the builder.
What does a good entry look like?
Say a bank runs an agent that handles requests to raise daily card limits at depth 3, up to a ceiling set by the customer's account type. The runbook's signals section says: if held requests exceed twice the weekly average for two hours, check the card system's limit table for changes; if refusals exceed the threshold, check whether the identity service is responding.
The lowering-depth section says: open the agent's page, set "card limit change" to depth 1, enter a reason. The verdict is filed automatically. Then route the card limit queue to the card services team using the switch named in the routing section. The incident section says a wrong limit increase counts as a customer-impacting incident and must be reported to the risk duty officer within the hour.
Each line is something a stand-in can do without judgement calls they are not qualified to make.
Which controls keep the runbook current?
- Reviewed at every recertification, since depth, sources and bounds may have changed.
- Tested in drills, with the person on call following it literally.
- Versioned alongside the agent, so the runbook matches the version running.
- Owned by operations, not by the build team.
The wider sequence is in our guide to deploying an AI agent.
Questions people ask
How long should a runbook be?
As short as it can be while covering every section. A few pages with clear steps is better than a long document nobody will read during an incident.
Should each agent have its own runbook?
Yes, because capabilities, bounds and signals differ. Shared sections such as outage handling can be referenced from a common document.
Who should be able to follow it?
Anyone on the on-call rota, including people from other teams. If it needs the builder to interpret it, it is not finished.