Alerts and Containment
When a guardrail holds or stops a call, the right people hear about it without being buried, and a responder can act at once. This page covers the alert, the triage queue, containment, who can do each, and the evidence export.
Guardrail Alerts
A guardrail enforcement raises an alert in the console: a held call, a stopped call, a hostile session, a tool that changed after approval, a canary hit or an investigator's session pause. AgentPass also emails the agent's supervisor about a held or stopped call, a hostile session, a changed tool or a canary hit, when the alert names a supervisor.
Two mechanisms keep alerts useful rather than noisy:
- Deduplication. Repeats of the same situation fold into one alert for a set window, 30 minutes by default. The same situation means the same agent, session, kind of enforcement and destination. The alert counts the repeats, such as ×4 seen. A tool whose definition changed follows its own rule instead: one alert per tool for as long as the alert is open. See When a Tool Keeps Changing.
- A daily budget per supervisor. Each supervisor gets a limited number of non-critical alerts a day, three by default, so one misbehaving session cannot flood an inbox. Critical alerts are always raised.
When a session keeps being denied, AgentPass can pause it automatically: repeated guardrail denials on one session, close together, pause the session. The pause is a full freeze, so the session can run no tools, reads included. Auto-pause is on by default. See What Pauses a Session.
The budget, the dedupe window and auto-pause are set on Guardrails → Settings. See Guardrail Settings.
The Triage Queue
Responders work alerts on Guardrails → Alerts. Each alert shows its severity, its status, when it was raised, a one-line summary, and the agent and session it concerns.
The page opens on Open alerts. Two filters narrow the list:
- Status: All statuses, Open, Acked, Resolved or False positive.
- Severity: All severities, Critical, High, Medium or Info.
When nothing matches, the page reads No alerts match these filters.
Any role with Guardrails: View can read the queue. Working an alert needs Guardrails: Manage, which Admin and Security analyst hold out of the box. To work an alert:
- Optional: In Resolution note (optional), enter a note to record with your decision.
- On the alert, click Ack to show someone is on it, or close it with Resolve or False positive.
The console confirms the change, such as Alert marked acked. Ack appears only on an open alert. A closed alert shows its status, who closed it and the note.
Tool Definition Changes
An alert for a tool whose definition changed after approval reads Tool definition changed: followed by the connector and the tool. Its severity follows what changed, as described in What Happens When a Definition Changes. The card carries the change and the decision, so you can settle it without leaving the queue.
The card shows these facts:
| Fact | Meaning |
|---|---|
| Change | Whether the change is to wording, structural, or widened so the tool accepts more input, and how many fields changed |
| Scanner | no findings, or what the scanner flagged in the new definition |
| Calls while changed | How many times agents called the tool successfully since it changed. It appears when you expand What changed |
| Also on | The other connectors that serve the same change, when there are any |
| Changed | How many times the tool has changed while this alert was open, when more than once |
| Last seen | When AgentPass last saw the changed definition |
Click What changed to see each changed field, with only the lines that were added or removed. It is expanded already on a High alert. When the scanner flagged the new definition, the card warns you to reject it unless the upstream owner confirms the change.
The actions on the card depend on the tool's state and your role.
| Button | Effect | Needs |
|---|---|---|
| Approve new version | Approves the change. Earlier approved versions stay accepted, and the alert is resolved | connectors:edit, and the tool still changed |
| Reject and block tool | Rejects the change after you confirm Block this tool for every agent?. The tool is blocked and disabled for every agent, and the alert is resolved | connectors:edit, and the tool still changed |
| Open tool | Opens the connector's Tools tab with Review tool change for this tool | — |
| Resolve | Closes the alert once the tool is back on an approved definition | A role that manages guardrails |
| False positive | Closes the alert as a false positive | A role that manages guardrails |
Approve and reject act on the tool, exactly as the review on the connector does.
The Same Change on Several Connectors
When several connectors reach the same MCP server, a change on that server reaches all of them. AgentPass raises one alert for it, and Also on names the other connectors. Approve new version and Reject and block tool then apply to every connector on the alert in one click, and the confirmation reads Block this tool on all N connectors for every agent?.
A connector leaves the alert when it goes back to an approved definition, when you review the tool on that connector's own page, or when it changes differently from the others (it then gets its own alert). The alert closes on its own only when every connector went back to an approved definition, quarantine was on the whole time, the scanner found nothing, and no agent called the tool on any of them while it was changed.
If a connector changed again since the alert was raised, approving skips it, so you never approve a definition you have not seen. The console names the connectors it skipped, and the alert stays open for them.
A tool-definition-change alert has no Ack and no Contain. Neither settles a tool change, and the alert names a tool rather than an agent. For the review dialog and the integrity states, see Tool-Definition Integrity.
Containing an Agent
When an alert names an agent, Contain turns that agent off and revokes its live sessions in one action. You need Guardrails: Manage.
- On the alert, click Contain.
- In Disable this agent and revoke its sessions?, confirm.
The console reports Agent contained (disabled, sessions revoked). The agent's next call is refused until someone turns the agent back on from Agents. See Who Can Turn an Agent Off and On.
If the agent cannot be contained, for example because it is already off, the console says why: Couldn't contain the agent: ….
To freeze one session instead of the whole agent, see Pausing and Stopping a Session.
Roles for Security Operations
Two editable system roles give security operations and audit the access their job needs, without making them administrators. Admin holds everything these roles do.
| Role | Can | Cannot |
|---|---|---|
| Security analyst | Read people, connectors, agents, approvals, policies, the Request log, Session watch and data classification. Read every guardrail page, including Settings and Judges. Work alerts, contain agents, turn agents off and on, run the Proving Ground attack pack, and mark a session pause a false positive | Change policies, connectors, credentials or data classification. Save guardrail settings, which also needs Settings: Edit. Decide approvals, which needs Approvals: Grant |
| Auditor | Read across the organization, including roles, gateway settings, data management and the API reference. Read every guardrail page except Settings, read judge configuration, and export guardrail evidence | Change anything |
A third role, Model governance owner, governs judges. Operator can read Posture, Alerts, History, the Proving Ground and the Session investigator, without working alerts.
Assign these roles like any other. See Roles and Permissions and Permissions by Role.
Evidence Export
Guardrail activity can be exported as an evidence package for an auditor or a governance review. Any role with Guardrails: View can export.
- Open Guardrails → Posture, and click Export evidence.
- In Export guardrail evidence, choose the period. It defaults to the last 30 days, and can span up to 366 days.
- Click Export.
The download is a zip of breaker decisions, alerts and Proving Ground runs over the period, with a mapping to the injection-defense controls it exercised. Every export is audited.
Guardrail Settings
Alert, containment, approval, tool-integrity and session investigator behavior is set on Guardrails → Settings. The page opens for roles with Guardrails: Manage, and saving also needs Settings: Edit. Every field, with its default and range, is listed in Guardrail Settings.
Related
- Input Guardrails Overview
- The Rule-of-Two Breaker — what produces most guardrail alerts
- Posture and History — the same activity trended over time
- Guardrail Settings — every setting on Guardrails Settings
- Notifications — how alert emails reach a supervisor