Guardrail Configuration

Complete reference for custom validation rules and guardrail settings

Guardrail Configuration

This page provides comprehensive documentation for configuring guardrails in PraisonAI, including custom validation rules, safety checks, content filtering, and compliance enforcement.

Guardrail System Overview

Guardrails ensure AI agents operate safely, ethically, and within defined boundaries. They provide multiple layers of protection:

• Input Validation: Validate and sanitize inputs before processing
• Output Filtering: Ensure outputs meet quality and safety standards
• Behavior Control: Prevent unwanted agent behaviors
• Compliance Enforcement: Ensure regulatory compliance

Basic Guardrail Configuration

from praisonaiagents import Agent, Guardrail

# Basic guardrail setup
basic_guardrail = Guardrail(
    name="content_safety",
    rules=[
        {"type": "content_filter", "block": ["harmful", "offensive"]},
        {"type": "length_limit", "max_length": 1000},
        {"type": "format_validation", "format": "json"}
    ]
)

agent = Agent(
    name="SafeAgent",
    guardrails=basic_guardrail,
    guardrail_config={
        "mode": "strict",  # or "permissive", "audit"
        "log_violations": True,
        "fail_on_violation": True
    }
)

Guardrail Presets (Agent-Centric API)

The simplest way to configure guardrails is using string presets:

from praisonaiagents import Agent

# Using string preset
agent = Agent(
    instructions="You are a helpful assistant",
    guardrails="strict"  # Uses strict preset: max_retries=5, on_fail="raise"
)

# Available presets:
# - "strict": max_retries=5, on_fail="raise" - Fail fast on violations
# - "permissive": max_retries=1, on_fail="skip" - Log and continue
# - "safety": max_retries=3, on_fail="retry" - Balanced approach

Preset with Overrides

# Preset with custom overrides
agent = Agent(
    instructions="...",
    guardrails=["strict", {"max_retries": 10}]  # Override max_retries
)

Policy Strings

For advanced policy-based guardrails:

# Multiple policy strings
agent = Agent(
    instructions="...",
    guardrails=["policy:strict", "pii:redact"]
)

LLM-Based Validation

Long strings are treated as LLM validator prompts:

agent = Agent(
    instructions="...",
    guardrails="Ensure the response is helpful, accurate, and does not contain harmful content."
)

GuardrailConfig for Full Control

from praisonaiagents import Agent, GuardrailConfig

agent = Agent(
    instructions="...",
    guardrails=GuardrailConfig(
        validator=my_validator_fn,
        max_retries=5,
        on_fail="raise",
        policies=["policy:strict", "pii:redact"]
    )
)

Custom Validation Rules

Rule Types and Configuration

# Content validation rules
content_rules = {
    "profanity_filter": {
        "type": "content_filter",
        "filters": {
            "profanity": {
                "level": "strict",
                "languages": ["en", "es", "fr"],
                "custom_words": ["specific", "blocked", "terms"]
            },
            "toxicity": {
                "threshold": 0.7,
                "model": "perspective-api",
                "categories": ["SEVERE_TOXICITY", "INSULT", "THREAT"]
            },
            "pii": {
                "detect": ["email", "phone", "ssn", "credit_card"],
                "action": "redact",  # or "block", "warn"
                "redaction_char": "*"
            }
        }
    },
    
    "topic_restrictions": {
        "type": "topic_filter",
        "allowed_topics": ["technology", "science", "business"],
        "blocked_topics": ["politics", "religion", "medical_advice"],
        "classifier": "zero-shot",
        "confidence_threshold": 0.8
    },
    
    "factuality_check": {
        "type": "fact_validation",
        "fact_checker": "custom_fact_checker",
        "min_confidence": 0.85,
        "require_sources": True,
        "allowed_sources": ["peer_reviewed", "official", "verified"]
    }
}

# Format validation rules
format_rules = {
    "json_validation": {
        "type": "format",
        "format": "json",
        "schema": {
            "type": "object",
            "required": ["result", "confidence"],
            "properties": {
                "result": {"type": "string"},
                "confidence": {"type": "number", "minimum": 0, "maximum": 1}
            }
        }
    },
    
    "regex_validation": {
        "type": "regex",
        "patterns": {
            "email": r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$",
            "url": r"^https?://(?:www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b"
        },
        "require_match": True
    },
    
    "structure_validation": {
        "type": "structure",
        "rules": {
            "max_depth": 5,
            "max_array_length": 100,
            "allowed_types": ["string", "number", "boolean", "object", "array"],
            "forbidden_keys": ["password", "secret", "token"]
        }
    }
}

# Business logic rules
business_rules = {
    "transaction_limits": {
        "type": "business_logic",
        "rules": [
            {
                "condition": "transaction.amount > 10000",
                "action": "require_approval",
                "approver": "senior_manager"
            },
            {
                "condition": "daily_total > 50000",
                "action": "block",
                "message": "Daily limit exceeded"
            }
        ]
    },
    
    "rate_limiting": {
        "type": "rate_limit",
        "limits": {
            "per_minute": 10,
            "per_hour": 100,
            "per_day": 1000
        },
        "by": "user_id",
        "action": "throttle"  # or "block", "queue"
    }
}

Custom Validation Functions

import time

def custom_validation_rule(input_data, context, config):
    """
    Custom validation function with complex logic
    
    Args:
        input_data: The data to validate
        context: Contextual information
        config: Rule configuration
    
    Returns:
        tuple: (is_valid, error_message, metadata)
    """
    # Implement custom validation logic
    if not isinstance(input_data, dict):
        return False, "Input must be a dictionary", {}
    
    # Check custom business rules
    if context.get("user_tier") == "free":
        word_count = len(input_data.get("text", "").split())
        if word_count > config.get("free_tier_limit", 100):
            return False, "Word limit exceeded for free tier", {"word_count": word_count}
    
    # Validate against external service
    if config.get("external_validation"):
        validation_result = external_validator.validate(input_data)
        if not validation_result.is_valid:
            return False, validation_result.error, validation_result.metadata
    
    return True, None, {"validation_time": time.time()}

# Register custom validation
custom_rule = {
    "type": "custom",
    "function": custom_validation_rule,
    "config": {
        "free_tier_limit": 100,
        "external_validation": True
    }
}

Advanced Guardrail Patterns

Layered Guardrails

# Multiple layers of protection
layered_guardrails = {
    "input_layer": {
        "priority": 1,
        "rules": [
            {"type": "sanitization", "remove": ["script_tags", "sql_injection"]},
            {"type": "length_check", "min": 1, "max": 10000},
            {"type": "encoding_validation", "allowed": ["utf-8"]}
        ],
        "fail_fast": True
    },
    
    "processing_layer": {
        "priority": 2,
        "rules": [
            {"type": "resource_limit", "max_memory": "1GB", "max_time": "60s"},
            {"type": "api_compliance", "standards": ["GDPR", "CCPA"]},
            {"type": "audit_logging", "level": "detailed"}
        ],
        "continue_on_warning": True
    },
    
    "output_layer": {
        "priority": 3,
        "rules": [
            {"type": "quality_check", "min_quality_score": 0.8},
            {"type": "consistency_check", "compare_with": "input"},
            {"type": "final_sanitization", "remove_internal_refs": True}
        ],
        "retry_on_failure": True
    }
}

Conditional Guardrails

# Context-dependent guardrails
conditional_guardrails = {
    "conditions": [
        {
            "if": {"context.environment": "production"},
            "then": {
                "rules": [
                    {"type": "strict_validation", "level": "maximum"},
                    {"type": "comprehensive_logging", "include_pii": False}
                ]
            }
        },
        {
            "if": {"context.user_type": "internal"},
            "then": {
                "rules": [
                    {"type": "relaxed_limits", "multiplier": 2},
                    {"type": "debug_mode", "enabled": True}
                ]
            }
        },
        {
            "if": {"context.region": "EU"},
            "then": {
                "rules": [
                    {"type": "gdpr_compliance", "strict": True},
                    {"type": "data_residency", "allowed_regions": ["EU"]}
                ]
            }
        }
    ],
    "default_rules": [
        {"type": "basic_validation", "level": "standard"}
    ]
}

Dynamic Guardrails

class DynamicGuardrailManager:
    """Dynamically adjust guardrails based on runtime conditions"""
    
    def __init__(self, base_config):
        self.base_config = base_config
        self.metrics = {}
        self.thresholds = {
            "error_rate": 0.05,
            "avg_response_time": 1000,
            "resource_usage": 0.8
        }
    
    def evaluate_and_adjust(self, metrics):
        """Adjust guardrails based on system metrics"""
        adjustments = {}
        
        # Tighten guardrails if error rate is high
        if metrics.get("error_rate", 0) > self.thresholds["error_rate"]:
            adjustments["validation_level"] = "strict"
            adjustments["retry_limit"] = 1
            adjustments["timeout"] = self.base_config["timeout"] * 0.8
        
        # Relax guardrails if system is performing well
        elif all(metrics.get(k, 0) < v * 0.5 for k, v in self.thresholds.items()):
            adjustments["validation_level"] = "relaxed"
            adjustments["parallel_processing"] = True
            adjustments["cache_aggressively"] = True
        
        return adjustments

dynamic_config = {
    "manager": DynamicGuardrailManager,
    "evaluation_interval": 60,  # seconds
    "metrics_window": 300,      # 5 minutes
    "auto_adjust": True
}

Compliance and Regulatory Guardrails

GDPR Compliance

gdpr_guardrails = {
    "data_minimization": {
        "type": "data_filter",
        "retain_only": ["necessary_fields"],
        "anonymize": ["user_id", "ip_address"],
        "retention_period": 90  # days
    },
    
    "consent_verification": {
        "type": "consent_check",
        "required_consents": ["data_processing", "marketing"],
        "verify_method": "token_validation",
        "audit_trail": True
    },
    
    "right_to_deletion": {
        "type": "deletion_capability",
        "cascade_delete": True,
        "verification_required": True,
        "completion_notification": True
    },
    
    "data_portability": {
        "type": "export_capability",
        "formats": ["json", "csv"],
        "include_metadata": True,
        "encryption_required": True
    }
}

Financial Compliance

financial_guardrails = {
    "aml_checks": {
        "type": "anti_money_laundering",
        "rules": [
            {"check": "suspicious_patterns", "threshold": 10000},
            {"check": "rapid_transactions", "window": "24h", "count": 10},
            {"check": "sanctioned_entities", "lists": ["OFAC", "EU"]}
        ],
        "reporting": "automatic"
    },
    
    "kyc_verification": {
        "type": "know_your_customer",
        "required_documents": ["id", "address_proof"],
        "verification_levels": {
            "basic": {"limit": 1000},
            "enhanced": {"limit": 10000},
            "full": {"limit": "unlimited"}
        }
    },
    
    "transaction_monitoring": {
        "type": "continuous_monitoring",
        "rules": {
            "unusual_activity": {"deviation": 3, "action": "flag"},
            "high_risk_countries": {"action": "manual_review"},
            "pattern_detection": {"ml_model": "fraud_detection_v2"}
        }
    }
}

Performance and Optimization

Guardrail Performance Configuration

performance_config = {
    "caching": {
        "cache_validation_results": True,
        "cache_ttl": 300,  # 5 minutes
        "cache_key_strategy": "hash",
        "max_cache_size": 10000
    },
    
    "parallel_validation": {
        "enabled": True,
        "max_workers": 5,
        "timeout_per_rule": 5,
        "fail_fast": True
    },
    
    "optimization": {
        "rule_ordering": "by_cost",  # Execute cheap rules first
        "skip_on_previous_pass": True,
        "batch_processing": True,
        "batch_size": 100
    },
    
    "monitoring": {
        "track_rule_performance": True,
        "slow_rule_threshold": 100,  # ms
        "alert_on_degradation": True
    }
}

Complete Guardrail Configuration Example

from praisonaiagents import Agent, Guardrail

# Comprehensive guardrail configuration
comprehensive_guardrail = Guardrail(
    name="enterprise_guardrail",
    config={
        # Validation rules
        "rules": [
            # Input validation
            {
                "type": "input_validation",
                "rules": {
                    "format": "json",
                    "max_size": "1MB",
                    "required_fields": ["action", "data"],
                    "sanitize": True
                }
            },
            
            # Content safety
            {
                "type": "content_safety",
                "filters": {
                    "toxicity": {"threshold": 0.8},
                    "pii": {"action": "redact"},
                    "inappropriate": {"block": True}
                }
            },
            
            # Business logic
            {
                "type": "business_rules",
                "rules": [
                    {
                        "name": "transaction_limit",
                        "condition": "amount > 5000",
                        "action": "require_2fa"
                    }
                ]
            },
            
            # Compliance
            {
                "type": "compliance",
                "standards": ["GDPR", "SOC2", "HIPAA"],
                "audit": True
            }
        ],
        
        # Execution settings
        "execution": {
            "mode": "strict",
            "parallel": True,
            "timeout": 30,
            "retry_on_timeout": False
        },
        
        # Error handling
        "error_handling": {
            "log_all_violations": True,
            "fail_on_critical": True,
            "warning_threshold": 3,
            "notification_webhook": "https://api.company.com/guardrail-alerts"
        },
        
        # Performance
        "performance": {
            "cache_enabled": True,
            "batch_size": 50,
            "async_validation": True
        }
    }
)

# Create agent with guardrails
secure_agent = Agent(
    name="SecureEnterpriseAgent",
    guardrails=comprehensive_guardrail,
    guardrail_config={
        "enforcement_level": "strict",
        "bypass_allowed": False,
        "audit_all_actions": True,
        "real_time_monitoring": True
    }
)

Environment Variables

# Guardrail mode
export PRAISONAI_GUARDRAIL_MODE="strict"
export PRAISONAI_GUARDRAIL_LOG_VIOLATIONS="true"

# Validation settings
export PRAISONAI_GUARDRAIL_TIMEOUT="30"
export PRAISONAI_GUARDRAIL_MAX_RETRIES="2"

# Content filtering
export PRAISONAI_GUARDRAIL_TOXICITY_THRESHOLD="0.8"
export PRAISONAI_GUARDRAIL_BLOCK_PII="true"

# Compliance
export PRAISONAI_GUARDRAIL_COMPLIANCE="GDPR,SOC2"
export PRAISONAI_GUARDRAIL_AUDIT_ENABLED="true"

# Performance
export PRAISONAI_GUARDRAIL_CACHE="true"
export PRAISONAI_GUARDRAIL_PARALLEL="true"

Best Practices

1. Layer your guardrails - Use multiple layers for defense in depth
2. Fail fast on critical violations - Don’t waste resources on invalid requests
3. Cache validation results - Improve performance for repeated checks
4. Monitor guardrail performance - Ensure guardrails don’t become bottlenecks
5. Use appropriate enforcement levels - Balance security with usability
6. Implement graceful degradation - Have fallback behaviors for guardrail failures
7. Regular rule updates - Keep validation rules current with threats
8. Comprehensive logging - Maintain audit trails for compliance

See Also

• Guardrail Concepts - Understanding guardrail patterns
• Agent Configuration - Agent guardrail settings
• Best Practices - Configuration guidelines