Guardrail Behavior

Guardrails add content-policy checks before AISIX calls an upstream model, after the model responds, or at both points. Their shared runtime controls determine which traffic is checked, whether a match blocks traffic, and what callers and operators observe.

Built-in keyword and PII guardrails evaluate content inside the gateway. Remote guardrails send extracted content to a moderation service and apply its decision. Choosing a Guardrail Provider compares the available built-in and remote options.

Both categories use the behavior described on this page. Remote guardrails also need an explicit policy for moderation-service failures.

Guardrail Hook Point

The hook point controls where AISIX runs a guardrail and what happens when it blocks content:

Hook Point	What AISIX Checks	Effect When Blocked
input	The caller request before AISIX sends it to the provider.	The provider is not called.
output	Response content before AISIX returns it to the caller.	The caller does not receive the blocked response.
both	Both request and response content.	AISIX applies the same guardrail on both sides where the route supports it.

Input guardrails cover the text-bearing parts of standard inference routes: chat completions, completions, responses, messages, embeddings, image generation, audio speech, optional audio transcription and translation prompts, and rerank requests. They also scan Realtime text frames, MCP tools/call arguments, Files, Batch, and Fine-tuning request payloads, and raw provider passthrough bodies.

Output guardrails scan returned text from chat completions, completions, responses, messages, and audio transcription and translation. They also scan Realtime text frames, MCP tools/call results, Files, Batch, and Fine-tuning response payloads, and passthrough bodies. Realtime binary frames are relayed without a guardrail content check.

On the passthrough tunnel AISIX cannot resolve a request shape, so it scans the entire request and response body as text against the attached guardrails. A match on either side returns a 422 and the upstream body is not relayed.

Guardrail Matching

After selecting a hook point, use scope to control which requests can reach the guardrail. In self-hosted deployments, guardrails created through the Admin API apply across the environment. The AISIX managed control plane can instead attach a guardrail to the environment or to selected model aliases, caller API keys, or teams.

When more than one guardrail applies to the same request, AISIX evaluates them as one chain. A blocking verdict from any guardrail blocks the request or response.

If the same guardrail is attached through multiple matching managed scopes, AISIX keeps one copy of that guardrail in the request chain. The highest-priority attachment wins. When priorities are equal, the more specific scope wins in this order: caller API key, team, model alias, then environment.

Enforcement Modes

A guardrail's enforcement_mode controls what AISIX does after a guardrail detects matching content.

Choose one of two enforcement modes:

• block rejects matching content. This is the default when enforcement_mode is omitted.
• monitor allows matching content and records what the guardrail would have done.

Detection-based guardrails, including PII recognizers, injection classifiers, and category moderation, can produce false positives and false negatives. Monitor mode is useful when you need to tune a policy against real traffic before enforcing it.

In block mode, an input match stops the request before the provider is called, and an output match prevents the caller from receiving the response.

In monitor mode, the caller-visible request and response do not change. A request that block mode would reject with 422 Unprocessable Entity returns the normal upstream result instead. Content that a redacting guardrail would mask also reaches the model or caller unchanged.

AISIX records each observation on the request's usage record as a monitor hit. A hit carries the guardrail name, the hook that matched, and what the guardrail would have done: would_block with the match reason, or would_mask with per-detector match counts. AISIX does not record the matched request or response content.

These records let you stage a new guardrail, observe its hit rate, tune the policy, and then switch it to block. For block observations, AISIX also records the match in a gateway log line at info level:

guardrail in monitor mode observed a violation; not blocking (enforcement_mode=monitor)

Streaming Output

When an enforcing guardrail covers the output hook, AISIX holds streamed response content until the relevant check can run. Depending on the guardrail kind, AISIX may hold the full response or inspect buffered windows. This prevents blocked or unmasked content from reaching the caller before the guardrail decision, and it lets AISIX detect spans that cross stream chunks.

A guardrail in monitor mode never causes streamed output to be held back. When every output guardrail runs in monitor mode, AISIX forwards the stream as it arrives. After the stream ends, AISIX runs the checks and records any matches.

The buffer cap below does not apply to a monitor-only output chain. AISIX delivers and observes an oversized response instead of rejecting it. If any enforcing guardrail also covers the output hook, AISIX holds the stream so the enforcing chain can inspect it before delivery.

Guardrail kinds that expose stream buffer settings use these defaults:

{
  "max_buffer_bytes": 262144,
  "on_buffer_exceeded": "fail_closed"
}

Add these fields to a guardrail resource to change its buffer cap or overflow behavior. fail_closed blocks oversized output. fail_open releases output that AISIX could not fully inspect or rewrite, so use it only when availability is more important than strict output enforcement. Guardrail kinds that do not expose these fields use the built-in cap and fail closed on overflow.

Handle Remote Guardrail Failures

Guardrail kinds that call an external service can fail to reach their backend. This applies to AWS Bedrock Guardrails, Azure AI Content Safety, Alibaba Cloud AI Guardrails, Lakera Guard, OpenAI Moderation, and Microsoft Presidio.

Set the input and output failure policies independently:

Setting	Check Side	Default	When true	When false
fail_open	Input	true	Let the request through unscanned.	Block the request.
output_fail_open	Output	false	Let the response through unscanned.	Block the response.

The mandatory field can appear in Admin API and control-plane payloads. When mandatory is true, a remote guardrail failure blocks traffic even if fail_open would otherwise allow the request through. This outer policy also makes an unavailable monitor-mode guardrail fatal, although content matches still remain observational in monitor mode.

Built-in keyword and PII guardrails run inside the gateway and never call a backend, so remote failure behavior does not apply to them.

When AISIX allows traffic because a remote guardrail could not return a decision, the request or response proceeds without inspection. Telemetry for this outcome varies by endpoint, as described in Caller Response and Telemetry.

Caller Response and Telemetry

When a guardrail blocks proxy traffic, AISIX preserves the error convention of the requested endpoint:

• OpenAI-compatible routes return 422 with content_filter.
• Passthrough routes return 422 with the same OpenAI-style content_filter envelope.
• Anthropic-compatible non-streaming errors return 422 with invalid_request_error.
• Anthropic-compatible streaming responses surface the block as an Anthropic SSE error frame.

MCP guardrail blocks follow the MCP protocol shape instead. AISIX returns HTTP 200 with a JSON-RPC error envelope, so MCP clients can handle the failure as a protocol response. See Headers and Error Codes.

Remote guardrails that fail open do not block the request or response. For chat-completions traffic, AISIX records the provider-specific bypass reason in usage events and increments the guardrail bypass metric. Other endpoint handlers do not currently populate the bypass-reason field, so do not use that field as the sole signal across all routes.

On every endpoint, each guardrail execution also records an observation on the aisix_guardrail_latency_seconds Prometheus histogram, labeled with the guardrail name, kind, phase, and result — including monitor-mode would_block/would_mask outcomes and fail-open bypassed results with their failure cause. Use it to track per-guardrail added latency (P50/P95/P99), compare local and remote detection, and watch block and bypass rates. See Metrics Reference for labels and PromQL examples.

Next Steps

Choose a provider or configure an in-gateway policy next:

• Choosing a Guardrail Provider: compare built-in and remote guardrail options.
• Built-in Keyword Guardrails: create an in-gateway blocklist.
• PII Detection and Redaction: detect, mask, or block sensitive data inside AISIX.