How the Kill Switch Works
The kill switch is an emergency stop for an agent’s traffic. When an agent is contained, AI Gateway denies every call the agent makes to its LLM providers, MCP servers, and other agents, and every call other agents make to it. A kill switch policy contains an agent when its guardrail or data policy signals spike, and the agent stays contained until it’s released.
After reading this page, you will be able to:
-
Describe what containing an agent blocks and what it leaves running
-
Identify how a kill switch policy decides to fire, and how Observe differs from Enforce
-
Recognize a contained agent in the UI and in a denied response
What containment does
Containing an agent cuts it off at AI Gateway:
-
Calls from the agent to LLM providers, MCP servers, and other agents are denied.
-
Calls from other agents and clients to the agent over A2A are denied.
-
Calls already in progress are canceled, including streaming responses.
Containment isn’t the same as stopping the agent. The agent’s runtime keeps running, but none of its calls get through the gateway. Because containment acts at the gateway, it takes effect even when the agent itself is misbehaving, and the agent can’t release itself.
Every containment records a reason, who or what contained the agent, and when. The reason appears in every denied response, so a caller sees why its request failed. When a kill switch policy contains an agent, the reason names the policy, the detection method, and the rate it detected, and the audit log records the policy’s firing.
Containment never expires on its own. When the agent is released, gateway calls resume within seconds. Calls that were canceled aren’t replayed, and releasing an agent doesn’t start a runtime that was stopped.
Release a contained agent
Release a contained agent with rpk ai. If rpk ai agent-kill-switch isn’t recognized, run rpk ai upgrade. Releasing an agent needs the Full access template or the Admin role. See Permissions.
-
Check the agent’s containment state and the reason it was contained:
rpk ai agent-kill-switch get --agent agents/<agent-id>Replace
<agent-id>with the agent’s ID. -
Fix the cause. If a kill switch policy contained the agent, review the firing on the agent’s Govern tab.
-
Release the agent:
rpk ai agent-kill-switch update --agent agents/<agent-id> --kill-switch.enabled=false
The Agentic Data Plane UI doesn’t have a control for releasing an agent. For the command’s flags, see rpk ai agent-kill-switch update.
What a caller sees
A call from or to a contained agent fails with HTTP 403 and the code agent_contained. The error message names the agent and includes the containment reason. MCP clients receive a JSON-RPC error with code -32003. The response carries no retry hint, because a contained agent stays contained until it’s released.
For how to recognize these errors when you debug an agent, see Gateway errors.
How kill switch policies decide
A kill switch policy belongs to one agent and watches one signal. Each signal is a rate that comes from the guardrails and data policies already running on that agent:
| Signal | What it measures |
|---|---|
Guardrail block rate |
The share of the agent’s requests that guardrails block. See How guardrails work. |
Data policy deny rate |
The share of the agent’s data access attempts that the data policies on its MCP servers deny. See Shape tool data with data policies. |
Evaluation error rate |
The share of guardrail and data policy checks that fail to evaluate. |
A policy can only fire when something on the agent produces its signal. If the agent has no guardrail on its LLM provider, for example, a guardrail block rate policy has nothing to watch, and the UI won’t save it.
Agentic Data Plane evaluates each signal in 5-minute windows. A window with fewer than 10 calls isn’t evaluated, so a quiet agent doesn’t fire on a handful of requests. Each policy uses one of two detection methods:
-
Burst: Fires when a single window clearly exceeds the threshold. Burst reacts fastest, but a single spike is enough to fire it.
-
Drift: Fires when the rate stays above normal long enough to build evidence. Drift ignores isolated spikes and catches sustained shifts.
A sensitivity setting of Low, Medium, or High sets the detection values for you. Before you save, a backtest replays the agent’s last 7 days of history and shows where the policy would have fired.
Observe and Enforce
Every policy runs in one of two modes:
-
Observe: Records each firing on the agent’s Govern tab. The agent keeps running. New policies start in Observe.
-
Enforce: Each firing contains the agent until it’s released.
Evaluation error rate policies run in Observe only. A check that fails to evaluate says more about the guardrail or data policy than about the agent, so it can’t contain the agent.
Start every policy in Observe, compare its firings with what you know happened, and promote it to Enforce once it fires only when it should.
Where a contained agent shows up
On a contained agent’s page, the Govern tab shows a red dot. On that tab, the Recorded firings table shows the firing that contained the agent, with the outcome Contained.
The agent’s Settings tab also summarizes its kill switch policies, for example whether any policy is enforcing.
Permissions
Every built-in access policy template, starting with Read only, lets a principal see an agent’s containment state, its kill switch policies, and their firings. Only the Full access template and the Admin role grant containing and releasing an agent and creating, changing, or deleting kill switch policies. The Standard template deliberately leaves them out, so that permission to edit an agent doesn’t include permission to release it. See Action reference and Kill switch permissions.
