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 keyword guardrails evaluate literal strings or regular expressions inside the gateway. Use them for local blocklists that should not call an external moderation service.
• Remote guardrails send extracted content to an external service, then apply the returned decision from AWS Bedrock Guardrails, Azure AI Content Safety, or Alibaba Cloud AI Guardrails.

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.

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. AISIX records the match in a gateway log line at info level:

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

The log line includes the guardrail name, the hook that matched, and the match reason.

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, and Alibaba Cloud AI Guardrails.

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 for compatibility, but current data-plane enforcement follows these two settings. Do not rely on mandatory to override them. Built-in keyword guardrails run inside the gateway and never call a backend, so remote failure behavior does not apply to them.

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

Create a built-in keyword guardrail when the policy should run inside AISIX. Use AWS Bedrock Guardrails, Azure AI Content Safety Guardrails, or Alibaba Cloud AI Guardrails when an external moderation service should evaluate the content.