AI Runbooks
Route: /org/resolve/settings?tab=runbooks · Permission: Manage Helpdesk Settings
1. What a runbook is
A runbook tells the AI what to do when it recognises a particular kind of request — the standing instructions for a recurring situation, keyed to an intent.
Where a knowledge article tells a customer what to do, a runbook tells the assistant what to check and what to advise.
2. How it spreads
3. Field reference
| Field | Control | Required | Notes |
|---|---|---|---|
| Intent key | Text | ✅ | Placeholder e.g. password_reset. The situation this runbook answers |
| Title | Text | ✅ | Placeholder e.g. Reset a locked account |
| Description | Text | Placeholder Short description of when this applies | |
| Steps | Repeating | Each step is Diagnostic or Action — "What the agent should do / check" | |
| Active | Toggle | Inactive runbooks are never matched |
Cancel edit abandons changes. Empty state: "No runbooks yet."
Diagnostic vs Action steps
| Type | Purpose |
|---|---|
| Diagnostic | Establish facts — check a status, confirm a symptom |
| Action | Change something — reset, restart, provision |
The split is the safety mechanism: diagnostics observe, actions change. A runbook that acts before it has diagnosed is a runbook that will confidently do the wrong thing at scale. Put every check in Diagnostic, and only what you would be comfortable automating in Action.
It is how a ticket is recognised as belonging to this runbook. Two runbooks with overlapping intents produce unpredictable selection — keep intents distinct and specific.
4. Don't confuse this with…
| These two | Differ by |
|---|---|
| Runbook vs KB article | Agent/AI instructions vs customer reading |
| Runbook vs AI training sources | Explicit steps vs ingested reference material |
| Runbook vs workflow | What to do vs what states exist |
| Runbook steps vs auto-assignment | What happens to the work vs who gets it |
5. Troubleshooting
| Symptom | Cause |
|---|---|
| Runbook never fires | Inactive, or the intent key never matches |
| Wrong runbook fires | Overlapping intent keys |
| It acts too early | Steps typed as Action that should be Diagnostic |