Skip to main content

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

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}")

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"]
)

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)

Agent Integration

from praisonaiagents import Agent
from praisonaiagents.policy import PolicyEngine, create_read_only_policy

# Create policy engine
engine = PolicyEngine()
engine.add_policy(create_read_only_policy())

# Agent with policy enforcement
agent = Agent(
    instructions="Research assistant",
    policy_engine=engine  # Enforces policies on tool calls
)

Zero Performance Impact

Policies are only evaluated when explicitly checked:
# No overhead until check() is called
from praisonaiagents.policy import PolicyEngine