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

# Policy Engine

> Policy-based execution control for agent operations

# Policy Engine

Define and enforce policies that control what agents can and cannot do. Block dangerous operations, require approval for sensitive actions, and implement fine-grained access control.

## Quick Start

### Agent-Centric Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents.policy import PolicyEngine, Policy, PolicyRule, PolicyAction

# Create policy engine with rules
engine = PolicyEngine()
engine.add_policy(Policy(
    name="no_delete",
    rules=[
        PolicyRule(
            action=PolicyAction.DENY,
            resource="tool:delete_*",
            reason="Delete operations blocked"
        )
    ]
))

# Agent with policy enforcement
agent = Agent(
    name="SecureAgent",
    instructions="You are a file management assistant.",
    policy=engine
)

# Policy is enforced during agent operations
agent.start("Help me organize and clean up my files")
# Delete operations will be blocked by policy
```

## Features

* **Rule-Based Control**: Define allow/deny rules with patterns
* **Priority System**: Higher priority policies take precedence
* **Strict Mode**: Deny unknown operations by default
* **Serialization**: Save/load policies as JSON
* **Convenience Functions**: Pre-built common policies

## Policy Rules

### Rule Structure

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.policy import PolicyRule, PolicyAction

rule = PolicyRule(
    name="block_shell",           # Rule identifier
    action=PolicyAction.DENY,     # ALLOW, DENY, or ASK
    resource="tool:shell_*",      # Pattern to match
    reason="Shell commands blocked",  # Explanation
    conditions={"env": "production"}  # Optional conditions
)
```

### Pattern Matching

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Exact match
resource="tool:read_file"

# Wildcard suffix
resource="tool:delete_*"

# Wildcard prefix
resource="*:dangerous"

# All tools
resource="tool:*"
```

## Convenience Functions

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.policy import (
    create_read_only_policy,
    create_deny_tools_policy,
    create_allow_tools_policy
)

# Read-only mode - block all write operations
read_only = create_read_only_policy()

# Block specific tools
deny_dangerous = create_deny_tools_policy(
    ["execute_*", "shell_*", "system_*"],
    reason="System commands are blocked"
)

# Allow only specific tools
allow_safe = create_allow_tools_policy(
    ["read_file", "list_directory", "search"]
)
```

## CLI Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai policy list                  # List policies
praisonai policy check "tool:name"     # Check if allowed
praisonai policy init                  # Create template
```

***

## Low-level API Reference

### PolicyEngine Direct Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.policy import (
    PolicyEngine, Policy, PolicyRule, PolicyAction
)

# Create engine
engine = PolicyEngine()

# Add a policy to block delete operations
policy = Policy(
    name="no_delete",
    rules=[
        PolicyRule(
            action=PolicyAction.DENY,
            resource="tool:delete_*",
            reason="Delete operations are blocked"
        )
    ]
)
engine.add_policy(policy)

# Check if action is allowed
result = engine.check("tool:delete_file", context={})
if not result.allowed:
    print(f"Blocked: {result.reason}")
```

### Strict Mode

In strict mode, any operation not explicitly allowed is denied:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.policy import PolicyEngine, PolicyConfig

engine = PolicyEngine(PolicyConfig(strict_mode=True))

# Unknown operations are denied
result = engine.check("tool:unknown", {})
assert not result.allowed
```

### Policy Serialization

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Save to dict
policy_data = policy.to_dict()

# Load from dict
restored = Policy.from_dict(policy_data)

# Save to JSON file
import json
with open("policies.json", "w") as f:
    json.dump([p.to_dict() for p in engine.policies], f)
```

## Zero Performance Impact

Policies are only evaluated when explicitly checked:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# No overhead until check() is called
from praisonaiagents.policy import PolicyEngine
```