Guardrail Behavior

Guardrails add content-policy checks to the AISIX request path. They help operators control what reaches an upstream model, what returns to callers, and how strict enforcement should be while a policy is being tuned.

AISIX supports two broad guardrail categories:

• Built-in guardrails (keyword and PII detection) evaluate patterns inside the gateway. Use them for policies that should not call an external moderation service.
• Remote guardrails send extracted content to an external service, then apply the returned decision: AWS Bedrock Guardrails, Azure AI Content Safety, Alibaba Cloud AI Guardrails, Lakera Guard, OpenAI Moderation, or a self-hosted Microsoft Presidio deployment.

Choosing a Guardrail Provider compares all kinds side by side.

The same request-path behavior applies whether a guardrail runs inside AISIX or calls a remote moderation service. Both categories use the same runtime controls for hook point, enforcement mode, scoping, and caller response behavior. Remote guardrails also use failure-handling settings for external-service outages.

Guardrail Hook Point

A guardrail's hook point controls where AISIX runs the check:

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 run on proxy routes where AISIX can extract request text. This includes chat completions, completions, responses, messages, embeddings, image generation, audio speech, rerank requests, and the raw provider passthrough tunnel. Output guardrails run on routes where AISIX can scan returned text, including chat completions, completions, responses, messages, and the passthrough tunnel.

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

Guardrail scope determines which requests a guardrail can evaluate. In self-hosted deployments, guardrails created through the Admin API apply across the environment. AISIX Cloud can also scope guardrails 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 Cloud 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.

AISIX supports two enforcement modes:

• block: reject matching content. This is the default when enforcement_mode is omitted.
• monitor: allow matching content and record the match.

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 response does 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 a 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.

Guardrail kinds that expose stream buffer settings use these defaults:

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

Add those fields to the guardrail resource when you need to change the 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.

Two settings decide whether AISIX lets unscanned traffic through or blocks it:

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 the input-side fail_open setting would otherwise allow the request through. 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 usage record includes a provider-specific bypass reason. The reason distinguishes timeouts, throttling, service or connection failures, and configuration errors.

Caller Response and Telemetry

When a guardrail blocks an OpenAI-compatible or Anthropic-compatible proxy request, AISIX returns 422 with the matching proxy error envelope:

• OpenAI-compatible routes use content_filter.
• Anthropic-compatible non-streaming errors use 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. AISIX records the bypass reason in usage events. For chat-completions traffic, AISIX also increments the guardrail bypass metric.

Next Steps

You now understand the shared guardrail behavior that setup guides build on. Use these guides to choose and configure a policy:

• 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.