Praison AI

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

python
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)

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

python
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
)
Presetmax_retrieson_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

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

Policy Strings (removed)

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:

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

GuardrailConfig for Full Control

python
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":

python
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

python
# 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

python
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

python
# 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

python
# 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

python
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

python
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

python
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

python
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

python
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

bash
# 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