An agent incident is not resolved merely because an error rate falls or a model starts returning responses again. A workflow may already have changed a record, sent a message, or exposed information before anyone notices. The response must first limit additional harm, then preserve enough evidence to understand what happened, and finally demonstrate that the affected business process can safely resume.
This checklist is designed for engineering leaders and incident responders operating agent-enabled products. It covers preparation, the first containment decisions, evidence capture, investigation, recovery and the handoff back to normal operations. It is not a substitute for your organization’s incident command process. Adapt the roles and escalation thresholds to the systems and customer commitments you actually operate.
Treat the time ranges as prompts for action, not deadlines. In a fast-moving incident, containment may need to happen before a complete diagnosis. Conversely, a system that appears quiet may still have queued or delayed work requiring investigation.
1. Prepare the runbook before an incident
Name the person who can stop agent activity. Record the on-call role and a backup, plus the location of the control they can use. The important test is not whether a kill switch exists in a design document; it is whether the responsible person can find and operate it during an incident. Identify separately how to stop new requests, queued jobs and ongoing executions. One control may not affect all three.
Write down the scope of each stop control. For each control, specify which service, tenant, workflow or action class it affects and what it does not stop. For example, a switch that prevents new model requests may leave previously created jobs in a queue. Document that difference so responders do not infer that a quiet dashboard proves all work has ceased.
Choose a safe fallback for the user-facing journey. Decide what the product should do when an agent workflow is disabled: show a clear unavailable state, offer a manual route, retain a draft for later, or decline the task. The fallback should avoid suggesting that unfinished work completed. Write the customer-visible wording and the internal behavior separately.
Keep a known-good configuration reference. Record how to identify the last reviewed prompt, workflow configuration, application build and action policy. A reference is useful only if responders can retrieve it without editing production state. Include the owner of the reference and how to distinguish a reviewed version from an experiment.
Define the minimum incident record. Prepare a shared record with incident ID, declaration time and time zone, incident lead, affected service, current containment state, known customer impact, next decision and next update time. Add a chronological event log. A consistent record prevents facts from being scattered across private chats and makes handoffs less lossy.
Confirm what operational signals can be correlated. Ensure responders know where to find request identifiers, workflow or task identifiers, timestamps, action results and relevant model-call records. Traces can contain spans and context that help correlate operations, but correlation alone does not demonstrate that the user’s task succeeded. OpenTelemetry’s explanation of traces is useful background for interpreting that distinction.
Document evidence handling before collecting sensitive examples. Decide which roles may access request content, where incident material can be stored, how unnecessary personal or confidential data should be excluded, and who can approve broader access. Preserve what is necessary for the investigation without copying entire customer records into a general incident channel.
Set a completed-work reliability baseline. Define what counts as a successfully completed user task, which eligible tasks form the denominator, and the measurement window. SLOs are about user-relevant service behavior, so a response generated is not automatically equivalent to work completed. Google’s SLO guidance discusses choosing a meaningful behavior, denominator and window. Use AI Agent SLOs: Define Reliability in Terms of Completed Work for the distinct measurement design problem.
A responder benefits from having the agent’s ordinary operating shape documented: expected task volume, normal completion signals, typical delays, and which actions can change external state. These are local baselines, not universal thresholds. If an incident begins with a sudden increase in retries or pending tasks, the baseline helps determine whether that is unusual for this product and whether it could amplify the effect.
2. Declare and establish command
Declare when credible evidence suggests user impact or uncontrolled work. Record what was observed, when it was first observed and who reported it. Do not delay declaration while trying to prove the root cause. A declaration starts coordination; it does not assert that every suspected detail is confirmed.
Assign one incident lead and one operational investigator. The lead coordinates decisions and communication; the investigator gathers and tests evidence. In a small team, one person may temporarily hold both roles, but explicitly record that fact and name the next person to take over. Unclear ownership can leave the system running while everyone assumes somebody else is stopping it.
Separate confirmed facts, hypotheses and unknowns in updates. Use those labels in the incident record. For example, “three duplicate submissions confirmed” is a fact only if records establish it; “a retry loop may be creating duplicates” remains a hypothesis until traced. This distinction prevents an early guess from becoming the accepted explanation.
Set a decision rhythm appropriate to the incident. Record the time of the next update and the decision that update must resolve. A useful update says what changed, what remains uncertain, which containment is active, and what will happen next. Avoid sending repeated status messages that add no new information or imply certainty that the team does not have.
Identify who handles customer and business communication. Give that person verified impact, the current fallback and the next update time. Technical responders should not make unsupported promises about restoration or claim that records are safe before checking. Keep customer communication aligned with the actual state of the affected journey.
If the incident involves a possible cross-tenant boundary failure, treat the affected data path as a separate containment concern and escalate through the organization’s established process. The deeper negative-test design belongs in Cross-Tenant Agent Security: A Negative-Test Matrix; this runbook focuses on response, evidence and controlled resumption rather than reproducing that test program.
3. Stop, contain and preserve
Stop the narrowest unsafe action that reliably limits harm. If a particular write action or workflow is implicated, stopping that capability may preserve unrelated service. If responders cannot confidently isolate it, disable the broader agent path. Choose the smallest control whose scope is understood, not the smallest one that merely looks convenient.
Stop intake and in-flight work as separate decisions. Preventing new tasks does not necessarily cancel work already accepted. Check whether workers, scheduled tasks or queues continue processing, and record how each was handled. Do not assume cancellation is safe if it could leave partially completed business operations; inspect the system’s actual semantics first.
Prevent retries from multiplying uncertain effects. Determine whether failed or timed-out actions are retried automatically and whether the retry can repeat an external effect. If that behavior is not known, pause the relevant retry path while preserving enough state to reconcile pending work. A timeout is not proof that the action failed; the destination may have accepted it before the response was lost.
Freeze changes to the implicated behavior. Pause prompt, policy, workflow and application changes that could alter the evidence or widen the incident. Record any emergency change, its author, time, purpose and expected effect. This is a temporary control to keep the investigation interpretable, not a reason to block a narrowly necessary containment action.
Record the state before changing it when doing so will not prolong harm. Capture active configuration identifiers, deployment references, relevant timestamps, current queue state and the control actions taken. If immediate shutdown is necessary, stop first and record the state as soon as safely possible. Never defer an urgent containment action merely to produce a perfect snapshot.
Preserve a bounded, access-controlled evidence set. Retain the incident window’s relevant task identifiers, event times, action requests and outcomes, errors, configuration references and user reports. Record where each source came from and who collected it. Avoid broad exports by default; collect additional material only when a concrete investigative question requires it.
Mark uncertain outcomes for reconciliation. Where a task could have performed an external action but the result is missing or ambiguous, create a list of affected identifiers and the destination to check. Do not replay those actions as a test. The immediate objective is to establish whether the effect occurred, not to make the workflow appear complete.
Protect the evidence from routine cleanup. Note any normal retention, queue expiry or log rotation that could remove relevant information during response. Ask the appropriate system owner to preserve only the scoped material needed for the incident, following internal data-handling rules. Record any evidence that is unavailable and the reason; an evidence gap is itself important.
The response sequence can be summarized as a small operational decision path. It deliberately routes uncertain external outcomes to reconciliation instead of automatic replay.
flowchart TD
A["Signal or report"] --> B["Declare and assign lead"]
B --> C["Stop unsafe intake or action"]
C --> D["Preserve scoped evidence"]
D --> E["Trace affected tasks"]
E --> F["Verify effects and recovery"]
F --> G["Resume with monitoring"]
accTitle: Agent incident containment and recovery flow
accDescr: A signal leads to incident command, containment, evidence preservation, task tracing, effect verification, and only then monitored resumption.
The flow is a sequence, not a claim that every incident has one root cause. If evidence shows that containment did not stop in-flight work, return to the containment decision and close that gap before advancing. If a task’s external effect cannot be established, treat it as unresolved and reconcile it rather than marking it successful or replaying it blindly.
4. Scope impact and build the event timeline
Choose a clear incident window. Start with the earliest credible signal and continue through the time containment took effect. Extend the window if evidence suggests the behavior began earlier or work continued afterward. Record time zone and clock source where possible, since mismatched timestamps can make events appear out of order.
Identify affected tasks using stable identifiers. Link request, workflow and action identifiers where available. If those identifiers do not join cleanly, document the gap and use the most reliable available combination of time, tenant, workflow and destination. Do not treat a matching timestamp alone as conclusive when multiple tasks could overlap.
Build a timeline from observable events. Include the initial trigger, agent steps, tool or external action request, returned outcome, retries, user-visible result, relevant configuration change and containment action. Keep source references beside each entry. Mark inferred transitions as inferred rather than presenting them as directly observed.
Classify each affected task by outcome. Use categories such as confirmed completed, confirmed not performed, ambiguous external effect, duplicate or repeated effect, and outcome unknown. Define the categories in the incident record. This prevents “request succeeded” from being used as a shortcut for “user’s task was completed correctly.”
Check whether the visible symptom understates the impact. A malformed response may be the only visible symptom while a separate action has already changed state. Compare user-facing outcomes with action records and the relevant destination’s state. Conversely, a troubling model response does not by itself prove that an external action occurred.
Measure the scope with an explicit denominator. State the number of confirmed affected tasks and the population examined, plus the time window and exclusions. If the full population cannot yet be enumerated, say so. A percentage without a defined eligible population can create false confidence and obscure tasks that have not yet finished.
Check for delayed work after the apparent start of recovery. Examine scheduled, queued and retrying tasks within the affected scope. Record whether each was stopped, completed, canceled or left unresolved. A quiet stream of new requests does not establish that old work has drained.
Keep task correctness separate from service availability. An endpoint may respond while the underlying task is wrong, incomplete or duplicated. Track both whether the service is operating and whether eligible user work reaches the intended, verified state. For implementation details about correlating agent operations, see AI Agents in Production: Agent Observability.
A useful incident timeline does not need to reproduce every internal event. It needs enough linked evidence to answer three questions: what did the system attempt, what happened at the destination, and what did the user or operator see? When one of those answers is missing, record the uncertainty explicitly and assign an owner to close it.
5. Investigate without changing the evidence
Write the investigation question before running a test. Examples include whether a specific configuration version preceded the first bad task, whether a retry repeated an action, or whether a reported output corresponds to a recorded task. A bounded question discourages live experimentation that changes production behavior without narrowing the diagnosis.
Reconstruct the affected path from recorded inputs and outputs. Use the preserved records and the relevant version references. Note which steps are directly observed and which are reconstructed. If the necessary input is unavailable or sensitive, use the approved access route rather than copying it into an unprotected workspace.
Distinguish model or instruction behavior from orchestration behavior. Check whether the agent selected an incorrect action, whether the application passed the wrong context, whether a tool request was transformed incorrectly, and whether the destination returned or applied an unexpected result. These are different failure locations and require different corrective actions.
Inspect retries, timeouts and partial completion explicitly. For each ambiguous task, establish whether the request reached the destination, whether the destination committed it, and whether a later retry followed. If the destination cannot answer those questions, keep the state classified as unknown and use a controlled reconciliation process.
Compare the incident configuration with the last known acceptable reference. Identify exact differences in prompt, task logic, parameters, application behavior and action permissions. Do not assume that the most recent deployment caused the incident simply because it is recent. Record competing explanations and what evidence would distinguish them.
Use controlled replay only in a non-production environment with side effects disabled or safely intercepted. A replay that can send a message, update a record or trigger another external consequence is not a harmless diagnostic. Record the replay’s inputs, configuration and purpose, and label its output as a reproduction result rather than proof of the original production outcome.
Inspect context and token limits when truncation or incomplete work is plausible. Determine what context was actually sent and what the application omitted or shortened. Do not infer the cause from response length alone. If this is a recurring design concern, Token Budget Management Across Agent Hops covers the separate problem of managing context across agent steps.
Update the working hypothesis only when evidence changes. Preserve the earlier hypothesis and note why it was revised. A concise record of what was disproved can prevent a later responder from repeating the same investigation. Avoid changing multiple variables at once in a diagnostic test; doing so makes its result difficult to interpret.
Worked incident: duplicate customer notices
Consider a hypothetical support workflow that prepares a customer notice and submits it through an external service. A user reports receiving two notices for one request. The initial alert shows a rise in timeouts, but the dashboard does not establish whether the notice service accepted the first submission. The incident lead disables new automated submissions for the affected workflow and pauses its pending retry path. Other unrelated product functions remain available.
The investigator preserves the relevant task IDs, application and workflow version references, request times, submission attempts, timeout records and destination responses. They classify each task rather than assuming the timeout means failure. In this hypothetical case, the destination’s records confirm two accepted submissions for one task, one accepted submission for another, and an unresolved outcome for a third. The team has therefore identified both a duplicate effect and an ambiguity; it has not established that every timeout caused a duplicate.
The timeline shows that a timeout occurred after a submission request, followed by a retry. The first response is missing from the application record, while the destination confirms acceptance. This supports a retry-related hypothesis for the confirmed duplicate, but the team still checks whether a second application path could have submitted the same notice. The unresolved task stays paused and is assigned for destination reconciliation. No one replays it merely to see what happens.
For recovery, the team first tests the proposed behavior in an environment where notice submission cannot reach real customers. They verify that a repeated request is detected or held for review according to the design chosen by the product team; they do not claim that a generic retry mechanism guarantees exactly-once delivery. They then reconcile the confirmed duplicate and unresolved task through the organization’s established customer-operations process. Any customer communication is based on the verified records, not the initial alert alone.
The incident remains contained until responders can show that new unsafe submissions are blocked, pending work is accounted for, and the correction passes the defined checks. The exercise illustrates why a response needs separate evidence for attempted work, destination effects and user-visible completion. A model’s statement that it sent a notice would not, by itself, prove that the notice was sent once—or sent at all.
6. Decide on rollback, correction or continued containment
Compare the cost of continued containment with the risk of resuming. Record which user journeys are unavailable, what manual fallback exists and what harm could follow from premature operation. Keep the decision grounded in observed impact and remaining unknowns rather than pressure to restore a green dashboard.
Prefer rollback when the change associated with the failure is identifiable and a known acceptable state is available. Confirm that reverting it will not reintroduce a separate, understood problem. Record the exact version or configuration reference selected and the reason for selecting it. A rollback is not automatically safe simply because it moves backward.
Choose a forward correction only when its behavior and scope are understood. State the specific defect being corrected and what evidence would show that the correction addresses it. If several changes are bundled together, separate them where practical so that responders can identify which change affected the result.
Keep changes to rollout strategy distinct from incident containment. A gradual release can reduce exposure to a new change, but it does not resolve uncertain work already performed. Canary Releases for Agent Changes: Prompts Need Rollback Too treats prompt and change rollout as a separate topic; here, the immediate decision is whether the implicated path is safe to resume at all.
Define a stop condition for the recovery attempt. Specify which signal, task outcome or customer impact will cause responders to pause or reverse the change. Ensure the person monitoring can activate that response, and do not set a threshold based on an unverified assumption about normal behavior.
Record what remains unresolved before choosing a path. Unknown external effects, incomplete logs or unexamined tenants do not disappear when the service is restored. Assign each material unknown an owner and next action. If the uncertainty could change the safety of resumed work, maintain containment until it is resolved or an explicit alternative control is in place.
A decision record can be short: option selected, alternatives rejected, evidence relied on, known uncertainty, decision owner and time. This makes it possible to revisit the choice when new facts arrive without reconstructing the discussion from chat history.
7. Verify recovery before resuming normal operation
Write acceptance criteria before re-enabling the affected path. Include the safe user-visible result, the expected action behavior, the handling of an ambiguous outcome, and the signals that indicate failure. Criteria should be specific enough that a responder can mark each pass or fail without interpreting a general statement such as “looks healthy.”
Check the corrected behavior using representative, non-side-effecting cases. Cover the ordinary path, the incident-triggering condition and relevant boundary conditions. If an external effect must be exercised, use an approved controlled destination or a process that cannot affect a real customer. Record the configuration and inputs used.
Reconcile pending and uncertain work before allowing it to execute. For each affected task, record whether it is safe to resume, must be handled manually, has already completed, or remains under investigation. Keep unresolved tasks out of automatic execution until their status and next action are clear.
Confirm containment controls are intentionally released. Identify which controls remain active, which are being lifted and who is making that change. Verify that releasing one control does not also release a broader class of work unintentionally. Keep a clear route back to containment during monitored recovery.
Resume in a bounded scope that responders can observe. Define the eligible workflows or task population, the observation period and the signals that trigger a pause. If the system cannot distinguish the proposed scope reliably, do not describe the resumption as scoped; choose a safer operational approach until it can.
Verify completed work, not only technical availability. Check that tasks reach the intended business state and that their outcomes can be linked to the relevant evidence. A successful request or a plausible agent response is not enough if the user’s objective remains incomplete.
Keep the incident lead informed during the observation period. Record what has been resumed, what was observed, whether the acceptance criteria passed and when the next review occurs. If a criterion fails, stop the affected work and reopen the investigation rather than adjusting the criterion to fit the result.
Close the incident only when the closure condition is met. Document the current service state, known user impact, unresolved follow-up items, customer communication status and owner for each action. If the response is stable but analysis remains incomplete, close the active incident only under the organization’s established definition and keep the investigation tracked separately.
8. Learn from the response and improve the runbook
Reconstruct the detection-to-containment interval. Record when the first observable signal appeared, when a responder recognized it, when the incident was declared and when unsafe work actually stopped. The differences identify whether the main gap was monitoring, ownership, access to controls or uncertainty about what those controls do.
Review evidence quality, not just evidence quantity. Ask whether responders could join the task, action and destination records; distinguish observed facts from inferred steps; and identify outcomes that remained ambiguous. More logs do not help if identifiers cannot be correlated or the evidence is inaccessible to the right responder.
Find the first point where the system could have failed safely. Consider whether it could have stopped before an external action, surfaced an uncertain result for human review, or prevented an automatic retry. Prioritize changes that make the failure bounded and diagnosable, not merely changes that make the incident report look cleaner.
Test the stop path and recovery path as separate exercises. A stop control may work while pending work continues; a recovery procedure may work for new tasks but mishandle records left in an unknown state. Exercise both, record the observed behavior and update the runbook when the documented scope differs from the actual scope.
Assign improvement work with a verifiable completion condition. Replace “improve agent reliability” with a concrete deliverable, such as recording an action outcome against a stable task identifier or documenting how pending tasks are reconciled. Name an owner and a review date through the team’s normal planning process.
Update the runbook where responders hesitated or took an unsafe shortcut. Change the relevant control instructions, decision criteria or evidence fields. Keep a version reference and make the revised runbook easy to find from the on-call procedure. A post-incident discussion without a corresponding operational change does not improve the next response.
A useful review distinguishes the trigger from the conditions that allowed it to create impact. The trigger may be a timeout or an unexpected output; contributing conditions might include an unbounded retry, missing outcome records, a stop control that affects only new work, or unclear ownership of reconciliation. Recording those conditions creates practical engineering work without turning the review into blame assignment.
9. Printable incident worksheet
Copy this worksheet into your incident record or print it for a response exercise. Fill unknown fields with “unknown” and assign an owner; do not leave a blank that could be mistaken for “not applicable.” The worksheet is a working record, not a promise that all questions can be answered immediately.
Incident declaration
- Incident ID and declaration time: Record the incident reference, date, time and time zone. Note the first credible signal separately if it predates declaration.
- Incident lead and investigator: Record names or on-call roles, backups and any handoff time.
- Affected product path: Name the workflow, action class, customer journey and known scope. Mark unconfirmed scope as unknown.
- Current user-facing behavior: Record what users see and the fallback currently offered. Distinguish a disabled feature from an unavailable core task.
Containment and evidence
- Controls activated: For each control, record its scope, activation time, operator and observed effect. Note whether intake, in-flight work, queues and retries were each addressed.
- Evidence preserved: List the sources, task or request identifiers, time window, collector, storage location and access constraints. Note material evidence that could not be retrieved.
- Uncertain external effects: List task identifiers and the destination requiring reconciliation. Record a named owner and prohibit unreviewed replay while status is uncertain.
- Configuration reference: Record the implicated and comparison versions, relevant change times and any emergency changes made during response.
Impact and decision
- Affected task classification: Record counts for confirmed completed, confirmed not performed, ambiguous, duplicate and unknown outcomes. Include the population examined and the time window.
- Current hypothesis and alternatives: State supporting evidence, contradicting evidence and the next observation that could distinguish competing explanations.
- Chosen recovery path: Record rollback, correction or continued containment; decision owner; reason; known risks; and the condition that would stop the attempt.
- Customer and business communication: Record verified impact, messages sent, next update time and the owner for follow-up.
Recovery and closure
- Acceptance criteria: List each pass/fail condition for task correctness, external effects, uncertain outcomes and monitoring. Record the configuration and environment used to check them.
- Pending work disposition: Identify what resumed, what was handled manually, what was confirmed complete and what remains unresolved.
- Resumption scope and observation: Record what was re-enabled, at what time, which signals were reviewed and whether any stop condition occurred.
- Closure and follow-up: Record closure time, remaining customer impact, open investigation items, owners and due dates. Keep the incident open if your established closure criteria are not met.
One-page response summary
- Stop: Halt the unsafe intake or action path; separately account for in-flight work, queues and retries.
- Preserve: Capture scoped evidence and exact configuration references without delaying urgent containment.
- Trace: Link tasks to attempted actions, destination outcomes and user-visible results; label unknowns honestly.
- Decide: Select rollback, correction or continued containment based on evidence and recorded tradeoffs.
- Verify: Test defined recovery criteria without creating uncontrolled external effects; reconcile uncertain work.
- Resume: Re-enable only a bounded, observable scope and keep a clear route back to containment.
- Learn: Record gaps, assign verifiable corrective work and update the runbook.
If responders repeatedly struggle to locate controls, join records or distinguish completed work from a generated response, those are platform design problems as well as documentation problems. Teams that need help making incident controls, observability and recovery paths operational can explore production platform engineering. The next step is to rehearse this checklist against one realistic failure path in your own system, then revise it to reflect what the controls actually do.