Skip to main content

​
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

pip install praisonaiagents

​
Features

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

​
Quick Start

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. 
from praisonaiagents.policy import PolicyEngine

engine = PolicyEngine()

​
Methods

MethodDescription
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. 
from praisonaiagents.policy import Policy, PolicyRule

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

​
Attributes

AttributeTypeDescription
namestrPolicy name
descriptionstrPolicy description
ruleslist[PolicyRule]List of rules
priorityintEvaluation priority
enabledboolWhether policy is active

​
PolicyRule

A single rule in a policy. 
from praisonaiagents.policy import PolicyRule

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

​
Attributes

AttributeTypeDescription
actionstr”allow” or “deny”
resourcestrResource pattern (supports wildcards)
reasonstrReason for the rule
conditionsdictAdditional conditions

​
PolicyResult

Result of a policy check. 
from praisonaiagents.policy import PolicyResult

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

​
Attributes

AttributeTypeDescription
allowedboolWhether action is allowed
reasonstrReason for decision
policy_namestrPolicy that made decision
rulePolicyRuleRule that matched

​
PolicyAction

Enumeration of policy actions. 
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. 
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. 
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. 
from praisonaiagents.policy import create_read_only_policy

policy = create_read_only_policy(name="read_only")

​
Usage Examples

​
Basic Policy

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

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

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

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