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

# Policy Module

> Policy-based execution control for agents

# Policy Module

The policy module provides policy-based execution control for agents, allowing you to define rules for what agents can and cannot do.

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonaiagents
```

## Features

* **Define rules** for what agents can/cannot do
* **Tool execution policies**
* **Resource access control**
* **Rate limiting and quotas**

## Quick Start

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

# Create a policy engine
engine = PolicyEngine()

# Add a policy
policy = Policy(
    name="no_delete",
    rules=[
        PolicyRule(
            action="deny",
            resource="tool:delete_*",
            reason="Delete operations are not allowed"
        )
    ]
)
engine.add_policy(policy)

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

## Classes

### PolicyEngine

Main engine for evaluating policies.

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

engine = PolicyEngine()
```

#### Methods

| Method                     | Description                |
| -------------------------- | -------------------------- |
| `add_policy(policy)`       | Add a policy to the engine |
| `remove_policy(name)`      | Remove a policy by name    |
| `check(resource, context)` | Check if action is allowed |
| `list_policies()`          | List all policies          |

### Policy

A collection of rules.

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

policy = Policy(
    name="security_policy",
    description="Security restrictions",
    rules=[rule1, rule2],
    priority=10
)
```

#### Attributes

| Attribute     | Type               | Description              |
| ------------- | ------------------ | ------------------------ |
| `name`        | `str`              | Policy name              |
| `description` | `str`              | Policy description       |
| `rules`       | `list[PolicyRule]` | List of rules            |
| `priority`    | `int`              | Evaluation priority      |
| `enabled`     | `bool`             | Whether policy is active |

### PolicyRule

A single rule in a policy.

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

rule = PolicyRule(
    action="deny",
    resource="tool:delete_*",
    reason="Delete operations are not allowed",
    conditions={"user_role": "admin"}
)
```

#### Attributes

| Attribute    | Type   | Description                           |
| ------------ | ------ | ------------------------------------- |
| `action`     | `str`  | "allow" or "deny"                     |
| `resource`   | `str`  | Resource pattern (supports wildcards) |
| `reason`     | `str`  | Reason for the rule                   |
| `conditions` | `dict` | Additional conditions                 |

### PolicyResult

Result of a policy check.

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

result = engine.check("tool:delete_file", {})
print(result.allowed)  # True/False
print(result.reason)   # Why allowed/denied
```

#### Attributes

| Attribute     | Type         | Description               |
| ------------- | ------------ | ------------------------- |
| `allowed`     | `bool`       | Whether action is allowed |
| `reason`      | `str`        | Reason for decision       |
| `policy_name` | `str`        | Policy that made decision |
| `rule`        | `PolicyRule` | Rule that matched         |

### PolicyAction

Enumeration of policy actions.

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

PolicyAction.ALLOW   # Allow the action
PolicyAction.DENY    # Deny the action
```

## Convenience Functions

### create\_deny\_tools\_policy

Create a policy that denies specific tools.

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

policy = create_deny_tools_policy(
    name="no_dangerous_tools",
    tools=["delete_file", "execute_command", "rm_rf"]
)
```

### create\_allow\_tools\_policy

Create a policy that only allows specific tools.

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

policy = create_allow_tools_policy(
    name="safe_tools_only",
    tools=["read_file", "search_web", "calculate"]
)
```

### create\_read\_only\_policy

Create a read-only policy.

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

policy = create_read_only_policy(name="read_only")
```

## Usage Examples

### Basic Policy

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

engine = PolicyEngine()

# Deny delete operations
policy = Policy(
    name="no_delete",
    rules=[
        PolicyRule(
            action="deny",
            resource="tool:delete_*",
            reason="Delete operations are blocked"
        )
    ]
)
engine.add_policy(policy)

# Check
result = engine.check("tool:delete_file", {})
print(result.allowed)  # False
```

### With Agent

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

engine = PolicyEngine()
engine.add_policy(create_read_only_policy())

agent = Agent(
    name="Reader",
    policy_engine=engine
)

# Agent can only use read operations
```

### Conditional Rules

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

policy = Policy(
    name="admin_only_delete",
    rules=[
        PolicyRule(
            action="allow",
            resource="tool:delete_*",
            conditions={"user_role": "admin"}
        ),
        PolicyRule(
            action="deny",
            resource="tool:delete_*",
            reason="Only admins can delete"
        )
    ]
)

# Check with context
result = engine.check("tool:delete_file", {"user_role": "user"})
print(result.allowed)  # False

result = engine.check("tool:delete_file", {"user_role": "admin"})
print(result.allowed)  # True
```

### Multiple Policies

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

engine = PolicyEngine()

# High priority security policy
security = Policy(
    name="security",
    priority=100,
    rules=[
        PolicyRule(action="deny", resource="tool:execute_*")
    ]
)

# Lower priority default policy
default = Policy(
    name="default",
    priority=1,
    rules=[
        PolicyRule(action="allow", resource="tool:*")
    ]
)

engine.add_policy(security)
engine.add_policy(default)

# Security policy takes precedence
result = engine.check("tool:execute_command", {})
print(result.allowed)  # False
```

## Best Practices

1. **Use wildcards** - Pattern matching for flexible rules
2. **Set priorities** - Higher priority policies are evaluated first
3. **Provide reasons** - Clear reasons help debugging
4. **Use convenience functions** - Pre-built policies for common cases
5. **Test policies** - Verify rules work as expected

## Related

* [Agent](/docs/sdk/praisonaiagents/agent/agent) - Using policies with agents
* [Hooks](/docs/sdk/praisonaiagents/hooks/hooks) - Event hooks
* [Guardrails](/docs/sdk/praisonaiagents/guardrails/guardrails) - Output validation