> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Guardrails Module

> Input/output validation and safety mechanisms for task outputs

# Guardrails

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

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

| Feature               | Usage                                        | Example                               |
| --------------------- | -------------------------------------------- | ------------------------------------- |
| **String preset**     | `guardrails="strict"`                        | Use predefined config                 |
| **Array + overrides** | `guardrails=["strict", {"max_retries": 10}]` | Preset with customization             |
| **LLM prompt**        | `guardrails="Ensure response is safe..."`    | Natural language validation           |
| **Callable**          | `guardrails=my_validator_fn`                 | Function `(output) -> (bool, result)` |
| **Config instance**   | `guardrails=GuardrailConfig(...)`            | Full control                          |
| **Policy strings**    | `guardrails=["policy:strict", "pii:redact"]` | Policy-based validation               |

## Presets & Options

| Preset         | max\_retries | on\_fail | Description                    |
| -------------- | ------------ | -------- | ------------------------------ |
| `"strict"`     | 5            | raise    | Fail hard on validation errors |
| `"permissive"` | 1            | skip     | Skip on failure, continue      |
| `"safety"`     | 3            | retry    | Retry on failure               |

## Precedence Ladder

<Info>
  **Resolution Order**: Instance > Config > Array > Dict > String > Bool > Default

  When 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
</Info>

## Usage Forms

### String Preset

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(description="...", guardrails="strict")
```

### Array with Overrides

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(description="...", guardrails=["strict", {"max_retries": 10}])
```

### LLM Prompt (String)

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(
    description="Write content",
    guardrails="Ensure the response is factually accurate and contains no harmful content"
)
```

### Callable Function

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import GuardrailConfig

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

## Classes

### GuardrailResult

Result of a guardrail validation.

| Attribute | Type                | Description             |
| --------- | ------------------- | ----------------------- |
| `success` | `bool`              | Whether check passed    |
| `result`  | `str \| TaskOutput` | Result or error message |
| `error`   | `str`               | Error message if failed |

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

## Related

* [Task](/docs/sdk/praisonaiagents/task/task) - Task configuration with guardrails
* [Agent](/docs/sdk/praisonaiagents/agent/agent) - Agent configuration