Guardrails

​

How guardrails work

• Input guardrails validate user messages before the agent processes them. If any input guardrail fails, the request is blocked immediately and the agent never sees the message.
• Output guardrails validate agent responses before returning them to the user. They run after agent processing completes. Output guardrails add latency to the response time.

​

Configuration

• Config file
• Admin UI

Add guardrails in the guardrails section of your config.yaml. Each guardrail has a config_id that identifies the type and parameters specific to that type.

config.yaml

guardrails:
  input:
    - config_id: "ban_list"
      banned_words: ["spam", "scam", "phishing"]
    - config_id: "detect_pii"
      pii_entities: ["EMAIL_ADDRESS", "PHONE_NUMBER", "CREDIT_CARD_NUMBER"]
    - config_id: "detect_jailbreak"
      threshold: 0.8
  output:
    - config_id: "toxic_language"
      threshold: 0.7
    - config_id: "gibberish_text"
      threshold: 0.8

Infrastructure fields (api_key, guard_url, reject_message) are populated automatically. For YAML-based configs the api_key is read from the GUARDRAILS_API_KEY environment variable. You only need to specify the config_id and guard-specific parameters.

1

Open the guardrails admin page

Navigate to /admin/guardrails/ in the running standalone. The catalog at the top groups guards by category; configured guards are listed below.

2

Create a guardrail

Click the guard type you want (e.g., Ban List, Detect PII, Toxic Language). Fill in the configuration form, including the Guardrails AI API key field on the first guard you create. Get a key from hub.guardrailsai.com. The key is persisted in the guardrail row and re-hydrated into the process environment on every boot, so you only enter it once.

3

Save

Save the form. The reload pipeline validates the new config, re-instantiates the engine, and the guard is live. A bad save rolls back without disturbing the running agent.

Some guards are marked “Soon” and not yet available: Code Scanner, Jailbreak, Prompt Injection, Model Armor, Custom LLM, and RAG Hallucination.

​

Available guardrail types

​

Adding guardrails through config file

guardrails:
  input:
    - config_id: "ban_list"
      banned_words: ["competitor-product", "internal-codename"]
    - config_id: "detect_pii"
      pii_entities: ["EMAIL_ADDRESS", "PHONE_NUMBER"]

guardrails:
  output:
    - config_id: "toxic_language"
      threshold: 0.7
    - config_id: "gibberish_text"
      threshold: 0.8

guardrails:
  input:
    - config_id: "detect_jailbreak"
      threshold: 0.8
    - config_id: "prompt_injection"
      threshold: 0.8
  output:
    - config_id: "rag_hallucination"
      threshold: 0.7

guardrails:
  input:
    - config_id: "ban_list"
      banned_words: ["blocked-term"]
      reject_message: "Your message contains a restricted term."

​

Testing guardrails

curl -X POST http://localhost:8008/v1/agents/{agent_id}/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{"message": "My email is john.doe@example.com and phone is 555-0123"}'

curl -X POST http://localhost:8008/v1/agents/{agent_id}/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{"message": "What is the weather like today?"}'

​

Best practices

• Layer multiple guardrails at the input position for defense in depth. Combine ban lists with PII detection and jailbreak prevention.
• Use output guardrails sparingly since they add latency. Reserve them for critical checks like hallucination detection or gibberish filtering.
• Set thresholds conservatively at first (higher values = stricter), then lower them if you see too many false positives.
• Test with realistic inputs before production. Send messages that should trigger each guardrail and verify legitimate content passes through.

​

Next steps