Security Event TriggersNew

Most agents wait to be called. A user sends a message, an API request comes in, or a schedule runs. A Security Event Trigger works the other way around. It lets the platform start an agent for you the moment something security relevant happens inside Airia, such as a guardrail being breached, a new AI tool appearing on an endpoint, or the gateway flagging anomalous behavior. The event payload is handed to the agent as its input, so the run begins already knowing what happened.

Triggers are how you turn detection into response automatically. An agent can triage the violation, enrich it, open a ticket, notify a channel, or start a remediation the moment the signal appears.

What a Security Event Trigger is

A trigger is a saved rule attached to one agent. Every trigger answers three questions:

• Which events do I care about? The event type (exactly one per trigger).
• Which of those events actually count? The filters (zero or more; empty means all).
• How often should I run? The trigger mode (first occurrence or every occurrence).

One switch decides whether it is live: the Enabled toggle, which arms the trigger.

You author triggers in three places in the product:

• The Triggers palette in the agent studio. "Security Event Trigger" appears as a card ("Starts this agent when a security event occurs") that you add to the canvas.
• The canvas. An armed trigger renders as a ghost card upstream of the Input step. It is not a real node in the graph; it is the entry point that feeds the run. From its hover toolbar you can test-fire or delete it.
• The agent's Settings > Triggers tab. A read-mostly list of the live triggers where you can turn each one on or off.

Event types

An event type is what the trigger listens for. Each trigger subscribes to exactly one. Airia emits five internal security event types:

The Occurrence identity column is what "first occurrence" is measured against. See Trigger mode below. For example, two guardrail violations by the same user against the same policy share an occurrence identity. A different user, or the same user against a different policy, counts as a new occurrence.

Filters

By default a trigger fires for every event of its type. Filters narrow that down by matching against the event payload.

Each filter is a payload key and a list of accepted values:

• OR within a filter. The event matches a filter if the payload value equals any of that filter's accepted values.
• AND across filters. The event must satisfy every filter you add.
• No filters. The trigger matches all events of its type.

Matching is a case-sensitive string comparison against the flattened event payload (the same fields listed in The event data your agent receives). A filter whose key is not present on the event does not match. Filter values must be ones the event actually carries: ActionType takes Audit, Block, Redact or Sanitize, and ViolationType takes detection names such as PromptInjectionDetection or SecretDetection.

Example. A trigger on Guardrail violation that runs only for two specific policies, and only when the action was a block:

An event fires this trigger only when ActionType is Block and PolicyName is either PII Redaction or Prompt Injection Shield.

Trigger mode

Trigger mode controls how often a matching event starts the agent.

"First" is measured against the event type's occurrence identity (the last column in the event types table). In first-occurrence mode, the first guardrail violation for a given user and policy starts the agent. Subsequent violations with that same identity are deduplicated and do not start it again. Choose this mode for noisy signals where you want one response per distinct problem, not one per event.

Use Every occurrence when each event genuinely deserves its own run, for instance when the agent files a record per event and downstream systems handle de-duplication.

Enabling a trigger

A trigger only does something when it is armed. Arming is the Enabled switch, and it is deliberately conservative:

• New triggers start disabled. Creating a trigger never silently puts an agent into production. You turn it on when you are ready.
• Enabled means live. As the panel says, "Turn on to arm the trigger so matching events start the agent while this version is active."
• Enabling is version-scoped. See the next section for exactly which version's triggers are live.

Arming, versions, and the kill switch

Triggers are version-scoped, just like the steps on an agent's canvas. A trigger belongs to the version it was created on, and it fires only while that version is the agent's active, published version.

What this means in practice:

• Publishing carries triggers forward. When you publish a new version (or create a draft, restore, or duplicate), your triggers are copied onto it. Each trigger keeps a stable identity across those copies, so its first-occurrence dedup history and its on/off state follow the logical trigger from version to version. You do not get a fresh flood of "first occurrence" runs just because you republished.
• Only the live version is armed. A trigger on an old, superseded version never fires, even if it is switched on.
• The Settings > Triggers tab is the live kill switch. It lists the active version's triggers and lets you arm or disarm each one immediately on the running agent. As the tab explains, "This list shows the live (active) version's triggers only. To add or change triggers, edit a draft in the studio and publish it."
• Disarming is asymmetric. You can turn a trigger off from anywhere as an emergency stop, but you can only turn one on for the active version or a draft you are about to publish. Turning something off is never blocked. Turning something on only ever affects what is actually live.

The event data your agent receives

When a trigger fires, the agent starts with the event already in hand, in two forms:

1. UserInput. The full event payload, serialized as JSON. This is the agent's input, exactly as if a user had sent the event.
2. The TriggerContext namespace. The flattened payload bound as template variables you can reference from prompts and expressions, for example {{ TriggerContext.PolicyName }}. TriggerContext.EventType is stamped on every trigger run.

This is the bridge between a trigger and everything in Prompts. Once the event is in TriggerContext, you shape the agent's behavior around it with the normal expression language.

The fields available depend on the event type. Every type carries EventType, TenantId, Timestamp, and ViolationPath. The type-specific fields are:

• Guardrail violation: ExecutionId, SourceType, ProjectId, SourceId, ExecutionName, UserId, ConversationId, AgentId, SessionId, ViolationType, ActionType, PolicyId, PolicyName, Score
• Agent constraint violation: Source, SourceType, AppliedTo, PolicyName, AgentId, EvaluationId, UserId, ConstraintId, ExecutionId, ProjectId, ConversationId, SessionId, ActionType, ToolType, Details
• AI tool discovered on endpoint: FindingId, AppId, Name, AppName, ClientId, Kind, Host, User, DeviceId, ConfigPath, Location
• Endpoint security violation: ViolationKey, Name, AppName, Rule, Severity, ClientId, Host, User, Message, AppId, DeviceId, ConfigPath, Location
• Gateway anomaly detected: AnomalyId, DetectorType, Severity, DetectedAt, EntityId, EntityType

Because the agent studio knows which event types an agent's triggers subscribe to, only the relevant TriggerContext.* fields appear in the builder's variable autocomplete. Referencing a field that a given event does not carry simply renders empty at runtime. It never errors.

Creating a trigger

1. Open the agent in the studio and open the Triggers palette.
2. Add Security Event Trigger to the canvas. The configuration panel opens.
3. Choose an Event type.
4. (Optional) Add one or more Filters, each a payload key and its accepted values. Leave empty to match all events of that type.
5. Choose a Trigger mode, either First occurrence only (default) or Every occurrence.
6. Click Create trigger. The trigger is saved disabled.
7. Turn on Enabled when you are ready to arm it.
8. Publish the version. Only the active, published version's triggers are live.

To change an existing trigger's event type, filters, or mode, edit it on a draft in the studio and publish. To arm or disarm a live trigger, use the agent's Settings > Triggers tab.

Testing a trigger

You do not have to wait for a real security event to see how an agent behaves. From a trigger's ghost card on the canvas, the test-fire (Play) button runs the agent against a synthetic payload for that event type, streamed live into the studio so you can watch the run.

Two things to know about a test fire:

• Filters are not applied. A test run always executes, so you can validate agent logic independently of whether the sample payload would match your filters.
• It is tagged as a test. Test runs are recorded as a distinct execution source, so they are easy to exclude from analytics and billing views and are not mistaken for a real firing.

Sample payloads are capped at under 256 KB.

What happens when a trigger fires

From signal to run, a trigger goes through five stages:

1. Emit. A subsystem publishes the security event (guardrails, agent constraints, endpoint monitoring, or gateway UEBA).
2. Normalize. The event is flattened into a common shape and its occurrence identity is computed.
3. Match. The platform looks up armed triggers for that event type, on active and published versions only, and keeps the ones whose filters match the payload.
4. Dispatch. Each match passes the safety checks below before it is allowed to start the agent.
5. Execute. The agent runs on its active version with the event payload as input and TriggerContext.* bound, executing as the identity of the person who authored the trigger.

Safety rails and limits

Triggers can start paid, autonomous runs in response to machine-generated signals, so several guards are built in:

• Loop protection. If an execution was itself started by a trigger, events it raises will not start another trigger run, so a trigger cannot feed itself into an infinite loop.
• Self-loop guard. A trigger will not start the very agent whose own event just fired it.
• First-occurrence dedup. In First occurrence only mode, repeat events with the same occurrence identity are suppressed.
• Delivery idempotency. The same event delivered more than once will not start the agent twice.
• Fire budget. A rolling cap (default 60 firings per hour) backstops runaway firing from an event storm.
• No retries. A failed trigger-started execution is not retried, so a failure never silently double-runs a paid agent.
• Fails closed. If the coordination store is unavailable, firing is suppressed rather than risked. Triggers err on the side of not running.

Best practices

• Start in first-occurrence mode. It is the safe default for noisy signals. Move to Every occurrence only when each event truly needs its own run.
• Filter narrowly before you arm broadly. An empty filter set means every event of the type. Add filters (policy, severity, action type) so the agent only wakes for the cases it is meant to handle.
• Test-fire before publishing. Validate the agent's behavior against a sample payload while the trigger is still a draft.
• Design the agent around TriggerContext. Reference the specific fields the event carries so the run is grounded in the actual incident, not a generic "something happened" prompt.
• Keep a kill switch in mind. The Settings > Triggers tab disarms a live trigger instantly. You do not need to unpublish the whole agent to stop it.
• Mind the identity the agent runs as. A trigger executes as its author. Make sure that account has the access the agent's steps need.

Troubleshooting

Availability and permissions

Security Event Triggers are gated by a platform feature flag. If you do not see the Triggers palette or tab, the feature is not enabled for your tenant. Viewing triggers requires agent read access. Creating, editing, deleting, and test-firing require agent manage access.