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)

Since PraisonAI PR #6060, on_fail only accepts "retry" (the default). on_fail="raise", on_fail="skip", or any other value raises ValueError at Agent(...) construction.

Presets set the retry budget. Pair a preset with a validator in list form:

from praisonaiagents import Agent

def my_validator_fn(output):
    return (len(output.raw) < 2000, output)

agent = Agent(
    instructions="You are a helpful assistant",
    guardrails=["strict", {"validator": my_validator_fn}],  # max_retries=5
)

Preset	max_retries	on_fail
"strict"	5	— (default "retry")
"permissive"	1	— (default "retry")
"safety"	3	— (default "retry")

A preset with no validator (guardrails=["strict"]) only sets max_retries — nothing is enforced.

​

Preset with Overrides

agent = Agent(
    instructions="...",
    guardrails=["strict", {"validator": my_validator_fn, "max_retries": 10}],
)

​

Policy Strings (removed)

Since PraisonAI PR #3790, policy-string guardrails such as guardrails=["policy:strict", "pii:redact"] raise ValueError at Agent(...) construction time. For tool allow/deny enforcement, use Agent(policy=PolicyEngine(...)) instead — see Policy Engine.

​

LLM-Based Validation

A bare string is always an LLM-validation prompt — never a preset lookup. guardrails="strict" validates against the literal word “strict”, so write real criteria:

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 defaults to "retry", the only supported value
    )
)

​

Observing Blocked Responses

When retries run out, the agent returns None and stores the last rejection reason on agent.last_guardrail_error. Use this in place of the old on_fail="raise":

answer = agent.start("Summarise the incident report")
if answer is None and agent.last_guardrail_error:
    raise RuntimeError(f"Blocked by guardrail: {agent.last_guardrail_error}")

​

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"
                    }
                ]
            }
        ],
        
        # 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"

# 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