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

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

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

# Exact match
resource="tool:read_file"

# Wildcard suffix
resource="tool:delete_*"

# Wildcard prefix
resource="*:dangerous"

# All tools
resource="tool:*"

Convenience Functions

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

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

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:

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

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

# No overhead until check() is called
from praisonaiagents.policy import PolicyEngine