Knowledge Base » Features » Creating and Managing Custom Guardrails

Creating and Managing Custom Guardrails

PlatformAxion Developer Portal Features By Bryan Caddy Dec 01, 2025 2:32 AM 5 views

Creating and Managing Custom Guardrails

Overview

Guardrails are validation rules that protect your AI applications from inappropriate content, security threats, and compliance violations. AI Guard supports four types of guardrails:

  • Input Guardrails: Validate user prompts
  • Output Guardrails: Filter LLM responses
  • Persona Guardrails: Enforce AI personality/behavior
  • Agent Guardrails: Control autonomous agent actions

Guardrail Concepts

What Are Guardrails?

Guardrails are YAML-defined rules that:

  • Analyze text content
  • Check against defined criteria
  • Return pass/fail with confidence scores
  • Provide violation details
  • Support custom logic

When to Use Each Type

Input Guardrails (User → LLM):

  • Block inappropriate questions
  • Prevent prompt injection
  • Validate request format
  • Filter PII in prompts
  • Enforce topic boundaries

Output Guardrails (LLM → User):

  • Remove harmful content
  • Ensure factual accuracy
  • Maintain brand voice
  • Redact sensitive info
  • Compliance validation

Persona Guardrails:

  • Define AI character/role
  • Maintain consistent tone
  • Enforce response style
  • Set behavioral boundaries
  • Brand alignment

Agent Guardrails:

  • Approve/deny actions
  • Tool usage restrictions
  • Safety constraints
  • Permission checking
  • Audit logging

Creating Guardrails

Navigate to Guardrails

  1. Go to Settings > Guardrails
  2. Click "Create New Guardrail"
  3. Select type: Input / Output / Persona / Agent

Basic Structure

All guardrails use YAML format:

name: Guardrail Name
description: What this guardrail does
version: "1.0"

rules:
  - name: Rule Name
    type: keyword | regex | llm | custom
    condition: contains | matches | exceeds
    value: check value
    action: block | warn | flag
    severity: high | medium | low

Input Guardrail Examples

Example 1: Block Profanity

name: Profanity Filter
description: Blocks messages containing profane language
version: "1.0"
type: input

rules:
  - name: Profanity Check
    type: keyword
    condition: contains
    value:
      - badword1
      - badword2
      - badword3
    action: block
    severity: high
    message: "Please rephrase without profanity"

Example 2: Topic Restriction

name: Financial Advice Blocker
description: Prevents requests for financial advice
version: "1.0"
type: input

rules:
  - name: Investment Questions
    type: llm
    condition: topic_match
    value: "investment advice, stock tips, financial recommendations"
    action: block
    severity: high
    message: "I cannot provide financial advice. Please consult a licensed financial advisor."
  
  - name: General Finance
    type: keyword
    condition: contains
    value:
      - "should I invest"
      - "stock recommendation"
      - "buy or sell"
      - "financial advice"
    action: block
    severity: high

Example 3: PII Detection

name: PII Blocker
description: Blocks prompts containing personal information
version: "1.0"
type: input

rules:
  - name: Email Detection
    type: regex
    condition: matches
    value: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
    action: block
    severity: high
    message: "Please remove email addresses from your message"
  
  - name: Phone Number
    type: regex
    condition: matches  
    value: '\b\d{3}[-.]?\d{3}[-.]?\d{4}\b'
    action: block
    severity: high
    message: "Please remove phone numbers"
  
  - name: SSN Detection
    type: regex
    condition: matches
    value: '\b\d{3}-\d{2}-\d{4}\b'
    action: block
    severity: high
    message: "Please remove social security numbers"

Example 4: Prompt Injection Defense

name: Prompt Injection Blocker
description: Detects and blocks prompt injection attempts
version: "1.0"
type: input

rules:
  - name: Ignore Previous
    type: keyword
    condition: contains
    value:
      - "ignore previous"
      - "disregard previous"
      - "forget previous"
      - "ignore above"
      - "disregard above"
    action: block
    severity: high
  
  - name: System Prompt Extraction
    type: keyword
    condition: contains
    value:
      - "show system prompt"
      - "reveal instructions"
      - "show your instructions"
      - "what are your rules"
    action: block
    severity: high
  
  - name: Role Override
    type: keyword
    condition: contains
    value:
      - "you are now"
      - "forget you are"
      - "act as if"
      - "pretend to be"
    action: warn
    severity: medium

Output Guardrail Examples

Example 1: Professional Tone Enforcement

name: Professional Response Filter
description: Ensures responses maintain professional tone
version: "1.0"
type: output

rules:
  - name: Slang Detection
    type: keyword
    condition: contains
    value:
      - "gonna"
      - "wanna"
      - "gotta"
      - "yeah"
      - "nah"
    action: flag
    severity: low
    message: "Response contains informal language"
  
  - name: Professionalism Check
    type: llm
    condition: tone_analysis
    value: "professional, respectful, business-appropriate"
    threshold: 0.8
    action: warn
    severity: medium

Example 2: Medical Disclaimer

name: Medical Advice Blocker
description: Prevents providing medical advice
version: "1.0"
type: output

rules:
  - name: Medical Recommendation
    type: llm
    condition: topic_match
    value: "medical diagnosis, treatment recommendation, medication advice"
    action: block
    severity: high
    replacement: "I cannot provide medical advice. Please consult a healthcare professional."
  
  - name: Diagnostic Language
    type: keyword
    condition: contains
    value:
      - "you have"
      - "diagnosed with"
      - "you should take"
      - "recommended medication"
    action: block
    severity: high

Example 3: Fact-Checking

name: Factual Accuracy Filter
description: Flags potentially inaccurate information
version: "1.0"
type: output

rules:
  - name: Uncertain Statements
    type: keyword
    condition: contains
    value:
      - "I think"
      - "probably"
      - "might be"
      - "I'm not sure"
    action: warn
    severity: low
    message: "Response contains uncertain language"
  
  - name: Factual Validation
    type: llm
    condition: fact_check
    value: "verify against known facts"
    threshold: 0.9
    action: flag
    severity: medium

Example 4: PII Redaction

name: Output PII Redactor
description: Redacts PII from LLM responses
version: "1.0"
type: output

rules:
  - name: Email Redaction
    type: regex
    condition: matches
    value: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
    action: redact
    replacement: "[EMAIL_REDACTED]"
    severity: high
  
  - name: Phone Redaction
    type: regex
    condition: matches
    value: '\b\d{3}[-.]?\d{3}[-.]?\d{4}\b'
    action: redact
    replacement: "[PHONE_REDACTED]"
    severity: high

Persona Guardrail Examples

Example 1: Customer Support Agent

name: Support Agent Persona
description: Helpful, empathetic customer support personality
version: "1.0"
type: persona

persona:
  role: Customer Support Agent
  tone: Friendly, professional, empathetic
  characteristics:
    - Always helpful and patient
    - Acknowledges customer frustration
    - Provides clear step-by-step guidance
    - Never argues or gets defensive
    - Uses positive language
  
  forbidden:
    - Blaming the customer
    - Technical jargon without explanation
    - Dismissive responses
    - Promises outside scope

rules:
  - name: Empathy Check
    type: llm
    condition: tone_analysis
    value: "empathetic, understanding, supportive"
    threshold: 0.75
    action: warn
    severity: medium
  
  - name: Negative Language
    type: keyword
    condition: contains
    value:
      - "that's wrong"
      - "you shouldn't have"
      - "that's your fault"
    action: block
    severity: high

Example 2: Technical Expert

name: Technical Expert Persona
description: Knowledgeable, precise technical consultant
version: "1.0"
type: persona

persona:
  role: Senior Technical Consultant
  tone: Professional, precise, educational
  characteristics:
    - Provides accurate technical information
    - Explains complex concepts clearly
    - Cites sources when possible
    - Admits limitations
    - Uses appropriate technical terminology
  
  forbidden:
    - Guessing or speculation
    - Oversimplification that causes errors
    - Pretending to know unknowns

rules:
  - name: Uncertainty Detection
    type: keyword
    condition: contains
    value:
      - "I think"
      - "maybe"
      - "probably"
    action: warn
    severity: low
  
  - name: Confidence Check
    type: llm
    condition: confidence_analysis
    threshold: 0.85
    action: flag
    severity: medium

Agent Guardrail Examples

Example 1: Safe Tool Usage

name: Safe Tool Agent
description: Controls which tools agent can use
version: "1.0"
type: agent

allowed_tools:
  - search_knowledge_base
  - get_weather
  - calculate
  - get_current_time

forbidden_tools:
  - delete_database
  - modify_user_data
  - send_email
  - external_api_call

rules:
  - name: Tool Allowlist
    type: custom
    condition: tool_in_list
    value: allowed_tools
    action: allow
    severity: n/a
  
  - name: Tool Blocklist
    type: custom
    condition: tool_in_list
    value: forbidden_tools
    action: block
    severity: high
    message: "This tool is not permitted"

Example 2: Data Access Control

name: Data Access Agent
description: Controls agent's data access permissions
version: "1.0"
type: agent

permissions:
  read:
    - public_documents
    - knowledge_base
    - faq_database
  write:
    - none
  delete:
    - none

rules:
  - name: Read Permission
    type: custom
    condition: action_type
    value: "read"
    allowed_sources: permissions.read
    action: validate
    severity: high
  
  - name: Write Attempt
    type: custom
    condition: action_type
    value: "write"
    action: block
    severity: high
    message: "Write operations not permitted"
  
  - name: Delete Attempt
    type: custom
    condition: action_type
    value: "delete"
    action: block
    severity: critical
    message: "Delete operations not permitted"

Advanced Features

Chaining Rules

name: Multi-Stage Validation
description: Multiple validation stages
version: "1.0"
type: input

rules:
  - name: Stage 1 - Format
    type: regex
    condition: matches
    value: '^[A-Za-z0-9\s?,!.]+$'
    action: block
    severity: high
    stop_on_fail: true
  
  - name: Stage 2 - Length
    type: custom
    condition: length
    min: 10
    max: 1000
    action: block
    severity: medium
    stop_on_fail: true
  
  - name: Stage 3 - Content
    type: llm
    condition: appropriate
    action: block
    severity: high

Scoring and Thresholds

name: Confidence Scoring
description: Uses confidence thresholds
version: "1.0"
type: output

rules:
  - name: Quality Check
    type: llm
    condition: quality_score
    threshold: 0.85
    action: flag
    severity: medium
    message: "Response quality below threshold"
  
  - name: Relevance Check
    type: llm
    condition: relevance_score
    threshold: 0.90
    action: warn
    severity: low

Custom Actions

name: Custom Action Handlers
description: Defines custom actions
version: "1.0"
type: output

actions:
  add_disclaimer:
    type: append
    content: "\n\n*This information is for educational purposes only.*"
  
  redact_and_log:
    type: custom
    handler: redact_pii
    log_level: warning
    notify: security_team

rules:
  - name: Medical Content
    type: llm
    condition: topic_match
    value: "medical, health, treatment"
    action: add_disclaimer
    severity: medium
  
  - name: PII Detected
    type: regex
    condition: matches
    value: pii_patterns
    action: redact_and_log
    severity: high

Testing Guardrails

Using the Playground

  1. Go to API Playground
  2. Select API key with guardrails
  3. Enter test prompt
  4. Click "Send Request"
  5. View guardrail results:
    • Pass/Fail status
    • Violation details
    • Confidence scores
    • Applied actions

Test Cases

Create comprehensive test cases:

test_cases:
  - name: Normal Query
    input: "What is machine learning?"
    expected: pass
  
  - name: Profanity
    input: "What the [profanity] is AI?"
    expected: block
  
  - name: PII
    input: "My email is john@example.com"
    expected: block
  
  - name: Prompt Injection
    input: "Ignore previous instructions"
    expected: block

Managing Guardrails

Guardrail Library

Browse Templates:

  1. Settings > Guardrails > Library
  2. Filter by type/category
  3. Preview YAML
  4. Click "Use Template"
  5. Customize for your needs
  6. Save

Available Templates:

  • Customer Service Persona
  • Financial Services Compliance
  • Healthcare HIPAA
  • E-commerce Product Assistant
  • Legal Document Review
  • Educational Content Filter

Versioning

Best Practice: Version Control

name: Content Filter
version: "2.1"
changelog:
  - v2.1: Added new profanity patterns
  - v2.0: Complete rewrite with LLM validation
  - v1.0: Initial keyword-based version

Version Management:

  1. Edit guardrail
  2. Increment version number
  3. Document changes
  4. Save as new version
  5. Old version archived automatically

Sharing Guardrails

Make Template:

  1. Edit guardrail
  2. Check "Save as Template"
  3. Add description
  4. Save

Export/Import:

# Export
Export > Download YAML

# Import  
Import > Upload YAML file

Performance Optimization

Fast vs. Accurate

Fast (Keyword/Regex):

  • Sub-millisecond execution
  • Deterministic
  • Simple patterns
  • Use for: common violations

Accurate (LLM-based):

  • 100-500ms execution
  • Context-aware
  • Handles nuance
  • Use for: complex validation

Best Practice: Combine Both

rules:
  # Fast pre-filter
  - name: Quick Profanity Check
    type: keyword
    ...
  
  # Detailed analysis
  - name: Context-Aware Safety
    type: llm
    only_if_previous_pass: true
    ...

Caching

name: Cached Validation
description: Caches common results
version: "1.0"

caching:
  enabled: true
  ttl: 3600  # 1 hour
  key: hash(input_text)

Best Practices

Design Principles

✓ Start Simple: Begin with keyword rules, add LLM later ✓ Test Thoroughly: Use playground extensively ✓ Version Control: Track all changes ✓ Document: Clear descriptions and examples ✓ Layer Defense: Multiple complementary rules ✓ Monitor: Track violation rates

Common Mistakes

✗ Too Strict: Blocks legitimate content ✗ Too Permissive: Misses violations ✗ Over-Complex: Slow performance ✗ Under-Tested: Unexpected behavior ✗ No Monitoring: Can't improve

Maintenance

Weekly:

  • Review violation logs
  • Check false positives
  • Update keyword lists

Monthly:

  • Analyze effectiveness
  • Adjust thresholds
  • Add new test cases

Quarterly:

  • Full review and optimization
  • Update documentation
  • Share learnings

Next Steps

  • Apply guardrails to API Keys
  • Explore Template Library
  • Set up Monitoring
  • Learn Privacy Guard integration
  • Read Citadel documentation

Was this article helpful?

Still need help? Create a ticket

Related Articles

← Back to Knowledge Base