AI Agent Incident Response Runbook: From Alert to Verified Fix

Service runbooks assume the symptom and the cause live in the same telemetry: an error rate spikes, a dependency is slow, a deploy is rolled back. An agent incident usually looks healthy on every dashboard. CPU, latency, and uptime are fine while the agent routes users to the wrong specialist, invents a refund policy, or stops calling a tool it called yesterday.

Two things differ in response. The evidence is in conversations, so the first job is reading the right ones at the right turn. And the fix is a behavior change, so the proof that it worked is a count of the failure after the fix, not a green deploy.

The table is the runbook. Each step has a timebox for a typical production agent and an exit criterion. Timeboxes assume the team has step-level diagnosis and a regression suite available; without them, steps 3 and 6 take days instead of hours.

Alerts for agent incidents arrive from three places: a user or customer report, your monitoring or observability tool, or a quality metric moving in a dashboard. Converra does not page you; use whatever already does. The first question is whether the agent is unresponsive or responding wrongly. If responses are failing or slow, follow the service runbook; the guide to what to do when an AI agent stops working separates the two.

Exit with one sentence that names the behavior, not the symptom: 'the agent quotes delivery dates without confirming the order number', not 'customers are complaining about deliveries'.

Announce a freeze on prompt, configuration, and model edits for the affected agent until the verdict is in. This is the step teams skip, and it is the one that makes the result readable. Converra marks a verdict confounded when the prompt was edited outside the fix during the measurement window; a freeze is how you avoid earning that outcome.

Pull the conversations that show the behavior, plus a sample from before the incident started. For each, find the first turn where the agent diverged from what the user needed and classify the cause: prompt, configuration, context or retrieval, code or routing, or model fit. Count how many conversations in the window show the pattern and over what denominator; exclude conversations you could not diagnose rather than counting them as fine.

Check for a change marker near the onset. A new prompt version, a configuration edit, a model update from the provider, or a tool or API change in the same hour is the leading suspect. Converra's step-level diagnosis does the turn-level work and records failure types per conversation, which is also the baseline the verdict will use later.

Containment buys time without pretending to be the fix. If a recent change coincides with onset, revert it and re-measure; that is the fastest containment there is. If a model update is the suspect, pin the previous version where your provider allows it. If a tool is misbehaving, narrow or disable it with a graceful fallback. If none applies, route the affected intent to a human queue.

Record what containment changed. It is another change in the window, and the postmortem needs it.

Make the smallest change that removes the diagnosed behavior in the diagnosed layer. A prompt-layer cause gets an instruction change; a configuration cause gets a threshold or tool-setting change; a code or routing cause gets a described change with evidence for the engineer who owns that code. Do not rewrite the prompt during an incident. Converra generates bounded prompt and configuration fixes from the diagnosis and provides a PR-ready description for code causes; it does not merge code on its own.

Run the current agent and the candidate on the same simulated conversations, including scenarios built from the incident conversations, and score both with the same rules. The candidate advances only if it beats the current agent on the conversations both ran and the regression suite passes. Converra runs this as paired simulation on shared personas with a regression gate; see simulation testing for agents.

This stage is what separates a runbook from a hotfix. It takes an hour or two, and it is the hour that keeps the fix from becoming the next incident.

Deployment is review-first in Converra: the winning change ships as a GitHub pull request or as a direct update that a person applies, and automatic deployment is optional, off until enabled, and only behind a passing regression suite. During an incident, a named person approves. Record the serving version and the time; that marker divides before from after in the next step. Keep the previous version deployable.

Count the targeted failure in new production conversations with the same detector used in step 3. Converra's rules for a fix it shipped, as of October 2026: monitoring until at least 5 diagnosed conversations after the change; verified with at least 15 conversations after the change and zero recurrences of a failure that occurred before; improving when recurrences fell but did not reach zero; not fixed when the failure recurred at least as often; regressed when the overall failure rate rose; confounded when the prompt was edited outside the fix. Model version changes and traffic-mix shifts are not detected automatically, so check them by hand.

Low-traffic agents wait longer. Do not lower the bar to close the incident faster; a not-enough-evidence state that is honest beats a verified label that is not. The guide to verifying a fix after deployment covers the full design.

Close the incident only on verified or improving. Not fixed sends you back to step 3 with the recurrences as new evidence. Confounded means waiting for a clean window or re-shipping the change alone. Regressed means revert and reopen.

Before closing, add the incident scenario to the regression suite so it never leaves, and write the postmortem using the incident postmortem template: impact, the failed trajectory, the active prompt and model versions, containment, the tested fix, the deployment marker, and the verdict.

The numbers are illustrative, not customer data. At 09:20 a support lead reports that the agent is confirming refunds for orders it cannot find. Triage confirms the service is healthy. A freeze is announced at 09:30. Step-level diagnosis of the morning's 180 conversations finds the pattern at turn three or four in 14 of them (7.8%), classified as a prompt-layer cause; a prompt edit shipped the previous evening at 18:05 is the suspect. Containment reverts that edit at 10:15.

A bounded fix requires a found order before any refund commitment. In paired simulation it removes the behavior on the incident scenarios and matches the baseline elsewhere; the regression suite passes. A named approver ships it at 13:40 and the serving version is logged. By the next morning the detector finds the pattern in 1 of 210 conversations after the marker; under the rules above that reads as improving, so the incident stays open at reduced severity until the count reaches zero over at least 15 conversations or the single recurrence is diagnosed as a different cause.

The one published Converra example is the Salespeak case study, where unsupported pricing, VAT, and infrastructure claims did not recur on live traffic after a deployed fix. Limits: one customer, one agent, and percentages rather than counts.