Skip to main content

​
Guardrails

Validation and safety mechanisms for agent outputs. Supports function-based, LLM-based, and preset guardrails.

​
Quick Start

from praisonaiagents import Agent

# Simple LLM guardrail (string prompt)
agent = Agent(
    description="Write content",
    guardrails="Ensure content is safe and accurate"
)

# Function guardrail
def validate(output):
    if len(output.raw) < 100:
        return (False, "Too short")
    return (True, output)

agent = Agent(description="Write content", guardrails=validate)

​
Feature Usage Table

FeatureUsageExample
String presetguardrails="strict"Use predefined config
Array + overridesguardrails=["strict", {"max_retries": 10}]Preset with customization
LLM promptguardrails="Ensure response is safe..."Natural language validation
Callableguardrails=my_validator_fnFunction (output) -> (bool, result)
Config instanceguardrails=GuardrailConfig(...)Full control
Policy stringsguardrails=["policy:strict", "pii:redact"]Policy-based validation

​
Presets & Options

Presetmax_retrieson_failDescription
"strict"5raiseFail hard on validation errors
"permissive"1skipSkip on failure, continue
"safety"3retryRetry on failure

​
Precedence Ladder

Resolution Order: Instance > Config > Array > Dict > String > Bool > DefaultWhen you pass guardrails=, the resolver checks in this order:
  1. Callable - Function? Use as validator
  2. Config - GuardrailConfig instance? Use as-is
  3. Array - ["preset", {"override": value}]? Apply overrides
  4. Dict - {"key": value}? Convert to config
  5. String - Preset name or LLM prompt? Look up or use as prompt
  6. Bool - True? Use defaults. False? Disable

​
Usage Forms

​
String Preset

agent = Agent(description="...", guardrails="strict")

​
Array with Overrides

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

​
LLM Prompt (String)

agent = Agent(
    description="Write content",
    guardrails="Ensure the response is factually accurate and contains no harmful content"
)

​
Callable Function

def content_length_guardrail(task_output):
    if len(task_output.raw) < 100:
        return (False, "Content too short")
    return (True, task_output)

agent = Agent(description="...", guardrails=content_length_guardrail)

​
Config Instance

from praisonaiagents import GuardrailConfig

agent = Agent(
    description="...",
    guardrails=GuardrailConfig(max_retries=5, on_fail="raise")
)

​
Classes

​
GuardrailResult

Result of a guardrail validation.
AttributeTypeDescription
successboolWhether check passed
resultstr | TaskOutputResult or error message
errorstrError message if failed
from praisonaiagents import GuardrailResult

# From tuple
result = GuardrailResult.from_tuple((True, task_output))
result = GuardrailResult.from_tuple((False, "Validation failed"))

​
LLMGuardrail

LLM-powered guardrail using natural language. 
from praisonaiagents import LLMGuardrail

guardrail = LLMGuardrail(
    description="Ensure content is safe and accurate",
    llm="gpt-4o-mini"
)

# Use in agent
agent = Agent(description="...", guardrails=guardrail)

​
Common Recipes

​
Function-based Guardrail

from praisonaiagents import Agent, Task, AgentTeam

def validate_length(output):
    if len(output.raw) < 100:
        return (False, "Too short")
    return (True, output)

agent = Agent(description="Write content", guardrails=validate_length)

​
LLM-based Guardrail

from praisonaiagents import Agent, Task, AgentTeam, LLMGuardrail

# Create an LLM-powered guardrail
quality_guardrail = LLMGuardrail(
    description="The content must be professional, factually accurate, and free of grammatical errors",
    llm="gpt-4o-mini"
)

agent = Agent(
    name="Writer",
    role="Content Writer",
    goal="Write high-quality content"
)

task = Task(
    description="Write a professional article about machine learning",
    expected_output="A well-written article",
    agent=agent,
    guardrails=quality_guardrail
)

agents = AgentTeam(agents=[agent], tasks=[task])
result = agents.start()

​
Multiple Guardrails

from praisonaiagents import Agent, Task, AgentTeam, LLMGuardrail

def length_check(task_output):
    if len(task_output.raw) < 200:
        return (False, "Content must be at least 200 characters")
    return (True, task_output)

def no_profanity(task_output):
    profanity_list = ["bad", "inappropriate"]  # simplified example
    for word in profanity_list:
        if word.lower() in task_output.raw.lower():
            return (False, f"Content contains inappropriate language: {word}")
    return (True, task_output)

# Chain guardrails
def combined_guardrail(task_output):
    # Check length first
    success, result = length_check(task_output)
    if not success:
        return (success, result)
    
    # Then check profanity
    return no_profanity(task_output)

task = Task(
    description="Write content",
    expected_output="Clean, detailed content",
    agent=agent,
    guardrails=combined_guardrail
)

​
Best Practices

  1. Keep guardrails focused - Each guardrail should check one specific aspect
  2. Provide clear error messages - Help users understand why validation failed
  3. Use LLM guardrails for complex validation - When rules are hard to express programmatically
  4. Chain guardrails for multiple checks - Combine simple guardrails for comprehensive validation
  5. Handle errors gracefully - Guardrails should not crash the application
  • Task - Task configuration with guardrails
  • Agent - Agent configuration