Guardrails

Validate agent output quality and safety before it is accepted — automatic retry on failure

from praisonaiagents import Agent

agent = Agent(name="safe-assistant", instructions="Be helpful and stay within policy.")
agent.start("Draft a customer-facing reply")

Guardrails validate agent output against your criteria and automatically retry if the output fails.

The user sends a prompt; guardrails validate input and output before the agent responds or calls tools.

Quick Start

1. Simple Usage

   Pass a validation function to an agent:

   from praisonaiagents import Agent
   
   def validate_length(output):
       word_count = len(output.raw.split())
       if word_count < 100:
           return False, f"Too short: {word_count} words (need 100+)"
       return True, output
   
   agent = Agent(
       name="Writer",
       instructions="Write detailed articles",
       guardrails=validate_length
   )
   
   result = agent.start("Write about renewable energy")
   
2. With Configuration

   Use GuardrailConfig for LLM-based validation with retry settings:

   from praisonaiagents import Agent, GuardrailConfig
   
   agent = Agent(
       name="Writer",
       instructions="Write professional articles",
       guardrails=GuardrailConfig(
           llm_validator="Ensure the response is professional, accurate, and at least 150 words",
           max_retries=3,
           on_fail="retry",
       )
   )
   
   result = agent.start("Write about machine learning trends")
   

---

Which Validator Should I Use?

Pick a validator strategy based on how you need to check the output.

---

How It Works

Guardrails work identically in sync (.start(), .chat()) and async (.astart(), .achat()) execution paths.

---

Configuration Options

GuardrailConfig SDK Reference

Full parameter reference for GuardrailConfig

Precedence ladder — choose the level you need:

# Level 1: Callable (function validator)
agent = Agent(guardrails=my_validator_fn)

# Level 2: String (natural language criteria)
agent = Agent(guardrails="Ensure response is professional and helpful")

# Level 3: List (policy strings)
agent = Agent(guardrails=["policy:strict", "pii:redact"])

# Level 4: GuardrailConfig (full control)
agent = Agent(guardrails=GuardrailConfig(
    validator=my_validator_fn,
    max_retries=3,
    on_fail="retry",
))

from praisonaiagents import Agent, GuardrailConfig

agent = Agent(
    instructions="...",
    guardrails=GuardrailConfig(
        validator=my_function,
        llm_validator="Natural language validation criteria",
        max_retries=3,
        on_fail="retry",
    )
)

Option	Type	Default	Description
validator	Callable | None	None	Function (output) -> (bool, Any) for programmatic validation
llm_validator	str | None	None	Natural language criteria for LLM-based validation
max_retries	int	3	Maximum retry attempts on validation failure
on_fail	str	"retry"	Action on failure: "retry", "skip", or "raise"
policies	List[str]	[]	Policy strings like ["policy:strict", "pii:redact"]

---

Common Patterns

Function-Based Validation

from praisonaiagents import Agent

def validate_json(output):
    import json
    try:
        json.loads(output.raw)
        return True, output
    except json.JSONDecodeError as e:
        return False, f"Invalid JSON: {e}"

agent = Agent(
    name="DataAgent",
    instructions="Always respond with valid JSON",
    guardrails=validate_json
)

result = agent.start("Give me a list of 3 fruits as JSON")

Natural Language Validation

from praisonaiagents import Agent

agent = Agent(
    name="Writer",
    instructions="Write product descriptions",
    guardrails="Must be professional, 100-200 words, include a call to action, and contain no pricing"
)

result = agent.start("Write a description for our premium coffee mug")

Multi-Agent with Guardrails

from praisonaiagents import Agent, Task, PraisonAIAgents

def check_accuracy(output):
    if "estimate" in output.raw.lower() or "approximately" in output.raw.lower():
        return False, "Response must use exact values, not estimates"
    return True, output

researcher = Agent(name="Researcher", instructions="Research and provide exact facts")
writer = Agent(name="Writer", instructions="Write clear summaries")

task1 = Task(
    description="Find the population of Tokyo",
    agent=researcher,
    guardrails=check_accuracy,
    expected_output="Exact population figure"
)
task2 = Task(
    description="Write a summary using the research",
    agent=writer,
    expected_output="One-paragraph summary"
)

agents = PraisonAIAgents(agents=[researcher, writer], tasks=[task1, task2])
result = agents.start()

---

Best Practices

Write specific, measurable criteria

Vague guardrails like “be good” are hard to enforce. Use concrete criteria: “must be between 100 and 200 words” or “must contain a JSON array”.

Use function validators for structured data

When validating JSON, code, or data formats, use a function validator. LLM validators are slower and better suited for qualitative criteria like tone or completeness.

Return helpful error messages on failure

The (False, "reason") message is passed back to the agent as feedback. Make it actionable — tell the agent exactly what to fix.

Set max_retries conservatively

Start with max_retries=2. Increasing retries adds latency and cost. If the agent fails repeatedly, the validator criteria or instructions may need refinement.

---

Guardrails validate an agent’s output and can retry. To block an action before it happens (a tool call, an inbound message, or an LLM request), see Blocking Plugins in Plugins.

---

Related

Approval

Add human-in-the-loop approval steps

Hooks

Intercept and modify agent behavior at lifecycle points

Gateway Self-Lifecycle Guard

Block agent commands that would stop or restart this gateway