--- title: "Use case: Stop one agent, a whole team, or everything, now" canonical_url: "https://tokenobserve.com/use-cases/kill-a-misbehaving-agent" published: 2026-09-02 last_updated: 2026-10-21 --- # Use case: Stop one agent, a whole team, or everything, now A kill switch scoped to one agent, one team or the whole estate is the first thing Token Observe's governance pipeline checks (ahead of lifecycle status, permissions, budgets and every policy), so nothing further down can outrank it. Engaging one is an admin action requiring a stated reason. ## The stated limit It is admission control: It refuses new work; it cannot recall a dispatched request ## Revoking a key and redeploying both take longer than the incident allows. Revoking a credential works on the next authentication attempt, for the calls that use it, in the systems where you can find it, and an agent running six months may hold one key at the gateway and a second directly against a vendor. Redeploying takes as long as a deploy takes and needs the owning team awake, which is usually the bottleneck. ## The steps, in this order 1. Decide the blast radius first. One agent when the misbehaviour is contained. One team when you do not yet know which agent. Everything, when you do not know. 2. Engage it with a real reason. Engagement is admin-only and the reason is mandatory. Every affected caller's refusal names the scope, the person and the reason. 3. Check what it did not reach. New requests from every subject the scope selects are refused with a 403 at the first check. Dispatched requests are not recalled. 4. Convert it into a durable decision. A kill switch is an emergency posture, not a lifecycle state. If the agent should not run again until reviewed, suspend it. ### Three scopes, and one predicate behind all of them. A team switch compares team names case-insensitively, because a team name is typed by a human under incident pressure and a capital letter should not decide whether a fleet stops. The predicate that answers whether a switch reaches a subject is written once and exported: the same function the gateway stops a request with decides which switches are compiled into a seat's signed policy bundle. - global: Every governed subject, refused with a 403 naming the scope, the person who engaged it and the reason they gave. - team: Matched case-insensitively against the subject's team, so a newly registered agent joining it is stopped without anyone adding it. - agent: One subject id. Pointed at a seat id, it stops that seat's device-side enforcement at the next bundle it holds. - Never licence-gated: The gateway, permissions, redaction, approvals, budgets, the flight recorder, the audit chain and the kill switch are in every tier. ### Four controls sit underneath the big red button. Reaching for the switch when something narrower would do is how an incident becomes an outage. The narrowest is a policy, which blocks one action rather than stopping the agent and is the only one you can rehearse in shadow mode. Next is the lifecycle state, then the credential (the right tool when the problem is who holds the key), and finally the budget, the only brake that acts without a person. ## What this still does not solve - A kill switch cannot recall a request already dispatched to a provider, and it cannot undo a tool call that has already executed upstream. - It cannot stop an agent that does not route through Token Observe, which makes the stop only as broad as your coverage. - It cannot revoke a vendor subscription. Retiring a seat stops that seat reaching Token Observe, and only the vendor's own console ends the entitlement. - Nothing engages it automatically. A policy can block a request and suspend the agent, but a team or global stop is a person's decision with a stated reason. ## Questions and answers Q: Does the kill switch stop calls that are already in flight? A: No. It is checked at the start of every governed request, so it refuses new work rather than recalling a call already dispatched. What it covers is broader than the model gateway: it runs on token counting and the model-catalogue routes too, which open no trace because they execute nothing and once skipped the check with them. Q: How fast does a stop take effect? A: On the agent's next governed request. There is no propagation step and no redeployment, because the resolver loads the agent, its roles and the switches in force live from the store. The one exception is a developer seat, where enforcement happens inside the vendor's own hook against a signed bundle it already holds. Q: Can we make it engage automatically on a threshold? A: Not the switch itself. A policy can act without a person: its suspend_agent action blocks the request and takes the agent out of service, and if the status write fails the block still stands. A team-wide or global stop stays a human decision with a stated reason, because a threshold cannot write the sentence explaining why a fleet stopped.