What should you do first when an AI coding agent misbehaves?

Contain, preserve, then investigate, in that order. Unlike a crashed service, a running agent keeps making changes while you diagnose, so time to contain matters more than time to diagnose. Pull the smallest kill switch that covers the blast radius, mark the workspace so automatic cleanup cannot destroy the evidence, and only then open the investigation.

Why do agent incidents need budget circuit breakers instead of error-rate alerts?

Because the distinctive agent failure is a run that succeeds by every technical measure while burning money in a loop. Every model call returns 200 and every tool call succeeds, so error-rate alerting never fires. Set per-run, per-agent and fleet ceilings plus a rate-of-change trigger, and count tokens at your own gateway, because provider usage accounting lags too far behind to drive a breaker.

How do you classify the root cause of an agent incident?

Ask whether it was prompt injection, a model failure, a bad tool definition, or a permissions mistake. Each has a different fix, and only the permissions case is genuinely closed by a policy change. The four overlap in practice, so name a primary cause and any contributing causes rather than forcing the incident into a single label.

Agent Runbooks - Incident Response When Agents Fail

Kill switches, budget circuit breakers, credential revocation and rollback - what to do when an autonomous agent misbehaves inside your infrastructure

An Agent Incident Is Not an Outage

Nothing is down; something is being done, repeatedly, while you decide

In a normal incident the system has stopped and the damage is bounded by the outage. An agent incident inverts that: the platform is healthy, the dashboards are green, and autonomous work product is wrong, expensive, or hostile, accumulating the whole time you read logs. A crashed service stops causing harm when it crashes. A running agent does not.

So the ordering rule changes. In an outage you diagnose in order to restore. Here you contain first, preserve second, investigate third, and accept that containment will sometimes be wrong: canceling a healthy run costs one run, while confirming the suspicion first costs ten minutes of whatever the agent is doing. This page covers only agent-specific cases - the general library is on runbooks, and ordinary environment faults belong in troubleshooting.

Contain, Preserve, Investigate - In That Order

The usual failure is investigating while the agent keeps working, then destroying the workspace during cleanup. Containment is reversible; lost evidence is not.

Kill Switches at Three Levels

One switch is not enough, because the faults have three different blast radii

Stop This Run

Cancel one task. Cheap, reversible, no escalation needed. It works only if a stable run identifier reaches the gateway, the workspace, and the audit log - see agent observability.

Stop This Agent

Disable one identity or workflow across every workspace at once - the switch for a fault in a prompt, a tool definition, or a scaffold rather than in one task. It requires a real revocable principal; see agent identity.

Stop the Fleet

A global halt, for a suspected compromise or an unbounded spend event. Expensive and disruptive, so it needs a named owner, written authority to pull it, and a rehearsed restart path. See agent fleets.

One constraint matters more than the taxonomy: a kill switch must not depend on the thing it is stopping. If halting the fleet requires the control plane the agents are saturating, it is not a kill switch, it is a request. Prefer mechanisms that act on the agent from outside - revoking the credential and cutting egress at the proxy both work on a process that has stopped reading its own control channel, and a cooperative "please stop" does not.

Level	Blast radius	Who can pull it	Latency	What it does NOT stop
Run	One task, one workspace	Any on-call engineer	Seconds	Other runs doing the same wrong thing
Agent	One identity, every workspace	On-call, incident lead informed	Bounded by token or session TTL	Merged work, and jobs it already triggered
Fleet	Every agent, every team	A named role with written authority	Minutes; the restart is the slow part	Humans doing the same thing by hand

Circuit Breakers That Trip on Spend, Not on Errors

The distinctive agent failure is a run that is succeeding by every technical measure

Classic alerting watches error rate, latency, and saturation. An agent stuck in a loop violates none of them. Every model call returns 200, every tool call succeeds, and the only thing going wrong is that money is leaving at a constant rate for no output. The breaker needs spend as its input.

Four ceilings at minimum: per-run tokens, per-agent per day, fleet-wide, and a rate-of-change trigger for when the absolute number is unremarkable but the slope is not. The rate trigger catches a new loop in its first minutes, before it crosses any fixed line.

Count Tokens at Your Own Gateway

Provider usage accounting lags, so a breaker driven by billing data reacts after the money is spent - a report, not a control. Meter at the proxy every call already passes through. See agent observability.

Decide What a Trip Leaves Behind

A hard ceiling mid-run leaves partial work: a half-applied refactor, an open pull request, a migration that ran but was not recorded. Define per agent class whether a trip cleans up or quarantines the workspace untouched.

Revocation Is Only Tractable If Credentials Are Short-Lived

Revoking a long-lived token is an unbounded search, not a step

With a long-lived shared token, "revoke the credential" is not an action you can complete during an incident. You have to find every place it was cached, exported into a shell profile, baked into an image layer, or copied into a log line, and you cannot prove you found them all.

Short-lived, per-run, narrowly-scoped credentials collapse that into one operation. Expiry does most of the work, and revocation targets a single principal - the argument for treating each run as its own identity, on agent identity. The strongest version keeps the secret out of the workspace and injects it at a proxy on the way out. Cloudflare's sandbox proxy documentation states the goal plainly: "Real credentials never enter the sandbox" (Cloudflare Sandbox documentation). The best revocation is a credential the workspace never held.

Say in the runbook what revocation does not fix. It does not un-send anything already exfiltrated, and it does not invalidate a downstream token the agent minted before you pulled it - a session, an API key, a deploy token, an OAuth grant. Enumerate secondary credentials as a distinct step; revoking the primary and declaring victory is how an incident reopens.

Rolling Back Merged Agent Changes

Harder than a deploy rollback, because other work already sits on top of it

Rolling back a deploy swaps a running artifact. Rolling back merged agent output means editing shared history other people have built on. Revert rather than force-push: a revert commit is additive and auditable, whereas a rewrite during an incident creates a second incident.

Identify the change set by agent identity and run id, not by author name - authorship is usually the human who approved, or a bot account shared by every workflow, so it over-selects or under-selects. Then look outside the repository: issues and comments the agent wrote, tickets it transitioned, generated configuration, cloud resources it created.

The structural problem is fan-out. One bad run may have opened many small pull requests across many repositories, several merged cleanly and looking unrelated. If your unit of rollback is the commit, you will find some of them. The unit has to be the run, which means the run id must be stamped on every artifact as it is produced. Retrofitting that mid-incident is not possible.

Data Changes Are a Different and Worse Problem

All of the above assumes the change is code. If the agent ran a migration, mutated production rows, or called a third-party API that changed state, reverting the commit undoes none of it and there may be no undo at all. Route those cases to the data recovery procedure.

Quarantine the Workspace, Do Not Destroy It

Ephemerality is a security property and an incident-response liability at once

Disposable workspaces are the right default. They are also a process that deletes your evidence on a timer, because the reaper does not know an investigation started. Every agent runbook needs an explicit preservation step first, and the platform needs a way to exempt one workspace from cleanup.

Preserve four things: a filesystem snapshot, the full conversation and tool-call transcript, the egress log for the run, and environment metadata - image digest, model version, tool definitions, resolved permissions. Then freeze the workspace in a network-isolated state rather than deleting it. Mechanics are on workspace snapshots; the isolation that makes a frozen workspace safe to keep is on sandbox environments.

The tension is real. Quarantined workspaces cost storage indefinitely if nobody prunes them, and they may hold secrets, customer data, or source you are contractually required to delete on a schedule. Set a retention clock at quarantine time, name an owner for each frozen artifact, and put the rule under AI governance.

Detection - Which Signals Indicate Which Failure

Four failure classes, each with a recognizable shape in the telemetry

Failure class	What it looks like	Signal source
Runaway loop	Tokens climbing with no new file writes; the same tool called repeatedly with near-identical arguments; duration far outside the distribution for that task type; the context window refilled repeatedly	Gateway token counters and tool-call spans, joined on run id
Exfiltration attempt	A destination never before seen for that agent; request or response bytes far above the peer distribution; a burst of requests to one host; writes outside the assigned repository or branch	The egress proxy allow and deny log - see below
Burning tokens without progress	No diff over a long window; repeated test failures against an unchanged patch; oscillating edits that revert one another	Workspace diff state sampled on an interval, plus test exit codes
Behavior change, no code change	The same prompt and scaffold behaving differently after a model version changed underneath you	A pinned eval suite, run on a schedule and on every model change

The exfiltration row needs a warning about where its log comes from. Kubernetes NetworkPolicy is a policy object, not a logging surface: the official list of "What you can't do with network policies (at least, not yet)" includes "The ability to log network security events (for example connections that are blocked or accepted)" (Kubernetes documentation). It stops the connection and tells you nothing about it, so the record must come from an egress proxy that logs decisions. As one vendor example, Coder's Agent Firewall documentation states that it "streams audit logs to the Coder control plane, providing centralized visibility into HTTP requests made within workspaces," recording "Whether the request was allowed (allow) or blocked (deny)" (Coder documentation - vendor claim). That layer is covered on agent egress control.

Behavior drift is the argument for a pinned suite you re-run against a new model version before it reaches production agents; see agent evals. One caveat covers all of it: every threshold here is workload-specific. A long run with no diff is pathological for a refactoring agent and normal for a browser-driving agent that mostly reads pages, of the kind covered in computer use agents. Derive thresholds per task type from your own distributions.

A Runbook Template You Can Actually Fill In

Five headings, one file per incident class, written before the incident

agent-runbook-template.yaml

# All timings below are EXAMPLE values. Tune them to your own
# observed distributions - do not adopt them as given.
name: "<short imperative title of the incident class>"
severity: "sev2"                 # EXAMPLE default; raise for suspected compromise
owner: "platform-oncall"         # a rota, never a named individual

trigger:
  alert: "<alert name or saved query that fires this runbook>"
  condition: "<the exact threshold, stated as a rule not a feeling>"
  also_entered_via: "human report in the incident channel"

immediate_actions:               # EXAMPLE target: first action within 5 minutes
  - contain: "pull the smallest kill switch covering the blast radius"
  - preserve: "mark the workspace no-reap BEFORE anything else touches it"
  - declare: "open the incident channel, name an incident lead"
  - notify: "<who must be told, and by when>"

investigation:                   # EXAMPLE target: classified within 60 minutes
  collect:
    - "full conversation and tool-call transcript for the run id"
    - "egress allow/deny log for the run id"
    - "token spend timeline from the gateway, not from billing"
    - "environment metadata: image digest, model version, tools, perms"
  questions:
    - "what was the last action taken before behavior diverged"
    - "did the agent read any untrusted content before diverging"
    - "was every action it took inside its granted permissions"

recovery:
  - "revoke the run credential, then enumerate secondary credentials"
  - "revert merged changes by run id, in every repository touched"
  - "check non-repository artifacts: tickets, comments, cloud resources"
  - "confirm no data-affecting change occurred; if it did, escalate"
  - "restart path: <how the agent or fleet comes back, who approves>"

follow_up:                       # EXAMPLE target: review within 5 business days
  primary_cause: "injection | model | tool-definition | permissions"
  contributing_causes: "<may be more than one>"
  actions:
    - "add or tighten the eval that would have caught this"
    - "narrow the tool contract or the permission that allowed it"
    - "add the detection signal if a human found this first"
  retention: "quarantine expires <date>, owner <name>"

Filled in for one concrete class it looks like this. The commands are generic placeholders for whatever your platform provides - do not read them as any real product's syntax.

Worked instance: runaway token consumption on a single agent run

# TRIGGER
#   Alert: agent_run_tokens_per_minute above the p99 for this task type
#   for 10 consecutive minutes, with zero workspace diff bytes.

# IMMEDIATE ACTIONS - commands are PLACEHOLDERS, not real CLI syntax
RUN_ID="the run id from the alert payload"

agentctl run  cancel  --run-id "$RUN_ID"        # contain first
agentctl ws   hold    --run-id "$RUN_ID"        # exempt from the reaper
agentctl cred revoke  --run-id "$RUN_ID"        # do not rely on cancel alone

# If cancel has not taken effect within ~60 seconds, escalate one level:
agentctl agent disable --agent "$AGENT_ID"

# INVESTIGATION
agentctl transcript get --run-id "$RUN_ID"  > ./evidence/transcript.jsonl
agentctl egress    log  --run-id "$RUN_ID"  > ./evidence/egress.jsonl
agentctl spend   trace  --run-id "$RUN_ID"  > ./evidence/spend.csv
#   Look for: the same tool called with near-identical arguments;
#   context repeatedly refilled with the same content; a tool that
#   returns an error the agent has no way to act on.

# RECOVERY
#   1. Confirm zero merged output. A no-diff loop usually merged nothing,
#      but confirm rather than assume.
#   2. If output did merge, revert by run id across every repository.
#   3. Re-run the task with a lower per-run token ceiling and observe.

# FOLLOW-UP
#   Primary cause here is usually a tool definition or a scaffold defect,
#   not injection. Add the failing case to the eval suite before closing.
#   Quarantine retention: 30 days (EXAMPLE), owner named in the ticket.

The Post-Incident Question: Which of Four Things Happened

Each has a different fix, and a wrong classification produces a fix that does not hold

Prompt Injection

Untrusted content the agent read steered what it did. Simon Willison's lethal trifecta names the dangerous combination: access to private data, exposure to untrusted content, and the ability to communicate externally. The fix is containment and reducing what the agent can reach, not a better prompt; see prompt injection defense.

Model Failure

The instruction was correct, no adversarial input was involved, and the agent misunderstood it anyway. The fix is scaffold, context, task decomposition, or a different model, confirmed by an evaluation that reproduces the failure and then passes; see agent evals.

Bad Tool Definition

The tool did what its description said, and the description was wrong or the tool was too broad for the job. The fix is the tool contract: narrower scope, an accurate account of side effects, confirmation required on irreversible operations. Often misfiled as a model failure.

Permissions Mistake

The agent should never have been able to perform the action at all. The fix is authorization, and this is the only one of the four where a policy change genuinely closes the hole rather than making it less likely. Prefer it over anything probabilistic.

These overlap constantly. An injection that succeeded because permissions were too broad is both, and forcing one label loses the half of the fix that would have held. Name a primary cause and one or more contributing causes, and require a concrete change for each.

The last point is organizational. DORA's 2025 report concludes that "AI's primary role is as an amplifier, magnifying an organization's existing strengths and weaknesses" (DORA, Google Cloud, September 2025). Applied here that is unwelcome news: a team without a working incident process does not acquire one by adopting agents, it gets a faster way to generate incidents it cannot classify. Build the runbooks, the kill switches, and the ownership model in AI governance first.