F5 Guardrails Integration

NeMo Guardrails supports using F5 AI Guardrails API as an input and output rail.

1
rails:
2
  input:
3
    flows:
4
      - f5 guardrails scan input
5
  output:
6
    flows:
7
      - f5 guardrails scan output

The F5 Guardrails API scans the text for various violations and returns an outcome. If the outcome is not cleared, the rail will trigger and the bot will refuse to respond.

Data handling

When these rails are active, the full user message (for the input rail) and the full bot response (for the output rail) are transmitted to the F5 AI Guardrails API for scanning. Review F5’s privacy notice and any applicable F5 AI Guardrails data retention terms before enabling this integration in production.

Configuration

The following environment variables can be used to configure the integration:

• F5_GUARDRAILS_API_KEY: The API key for the F5 Guardrails API.
• F5_GUARDRAILS_API_URL: The base URL for the F5 Guardrails API (defaults to https://us1.calypsoai.app).

Setup

Colang v1:

1
# config.yml
2
3
rails:
4
  config:
5
    f5:
6
      fail_open: false
7
8
  input:
9
    flows:
10
      - f5 guardrails scan input
11
12
  output:
13
    flows:
14
      - f5 guardrails scan output

Colang v2:

In Colang 2 the rails.input.flows / rails.output.flows lists are not used; the runtime runs the flows named input rails and output rails if they are defined. Import the F5 library flows and wire them up in a Colang file:

1
# config.yml
2
3
colang_version: "2.x"
4
rails:
5
  config:
6
    f5:
7
      fail_open: false

# rails.co
import guardrails
import nemoguardrails.library.f5
flow input rails $input_text
    f5 guardrails scan input $input_text
flow output rails $output_text
    f5 guardrails scan output $output_text

See examples/configs/f5_guardrails_v2/ for a complete configuration.

You can enable fail-open behavior so content is allowed when the connection to the F5 API fails by setting the fail_open flag to true.

1
# config.yml
2
rails:
3
  config:
4
    f5:
5
      fail_open: true

Rate limiting (HTTP 429)

The action respects the 429 Too Many Requests responses from the F5 Guardrails API. After exhausting the configured retries, the request falls back to the fail-open / fail-closed behavior described above.

1
# config.yml
2
rails:
3
  config:
4
    f5:
5
      # Additional attempts after a 429. Total attempts = max_retries + 1.
6
      # Set to 0 to disable rate-limit retries.
7
      max_retries: 2
8
      # Upper bound (in seconds) on how long to wait before retrying.
9
      max_retry_after_seconds: 30.0
10
      # Base delay used with exponential backoff when Retry-After is absent
11
      # or unparseable. Delay for attempt N is retry_backoff_seconds * 2**N.
12
      retry_backoff_seconds: 1.0

Rails exceptions

Setting the top-level enable_rails_exceptions: true flag causes the F5 rails to emit an F5GuardrailsRailException event instead of triggering the default bot refuse to respond. This lets callers of generate_async distinguish policy blocks from normal bot responses.

1
# config.yml
2
enable_rails_exceptions: true
3
4
rails:
5
  input:
6
    flows:
7
      - f5 guardrails scan input
8
  output:
9
    flows:
10
      - f5 guardrails scan output

When a scan is not cleared, the response has role: "exception" and content.type: "F5GuardrailsRailException", with a message naming the flow that blocked the request.

Customization

To customize the behavior, you can overwrite the default flows in your configuration. For example, to provide a custom refusal message:

define subflow f5 guardrails scan input
  $result = execute f5_guardrails_scan(text=$user_message)
  if $result.is_blocked
    bot say "I cannot process this request due to safety policies."
    stop