Policy Engine

Define allow/deny rules so agents cannot run dangerous tools — attach a PolicyEngine before the agent starts.

from praisonaiagents import Agent
from praisonaiagents.policy import PolicyEngine, Policy, PolicyRule, PolicyAction

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

agent = Agent(
    name="SecureAgent",
    instructions="You are a file management assistant.",
)
agent.policy = engine
agent.start("Help me organise my project files")

The user requests a risky action; policy rules allow or deny tools before execution.

Quick Start

Simple Usage

Block delete tools on a file-management agent:

from praisonaiagents import Agent
from praisonaiagents.policy import (
    PolicyEngine, Policy, PolicyRule, PolicyAction,
    create_read_only_policy,
)

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

agent = Agent(name="Assistant", instructions="Manage files safely.")
agent.policy = engine
agent.start("List files in the current directory")

With Configuration

Use strict mode and custom deny lists:

from praisonaiagents import Agent
from praisonaiagents.policy import (
    PolicyEngine, PolicyConfig, create_deny_tools_policy,
)

engine = PolicyEngine(PolicyConfig(strict_mode=True))
engine.add_policy(create_deny_tools_policy(
    ["execute_*", "shell_*"],
    reason="System commands are blocked",
))

agent = Agent(name="Reviewer", instructions="Read and summarise code only.")
agent.policy = engine

Denial in action

Attach a deny policy and watch the tool call get blocked before it runs:

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

def delete_file(path: str) -> str:
    """Delete a file at the given path."""
    return f"Deleted {path}"

engine = PolicyEngine()
engine.add_policy(create_deny_tools_policy(
    ["delete_*"], reason="Delete operations are blocked",
))

agent = Agent(
    name="ReadOnly",
    instructions="You are a read-only assistant.",
    tools=[delete_file],
)
agent.policy = engine

# The agent's tool call is denied by the policy before delete_file runs
agent.start("Please delete /etc/passwd")

Policy denials return an error to the model before the tool executes — the same pre-dispatch check applies to native and MCP tools alike. Guardrails run at this same hook: GuardrailChain.validate_tool_call / LLMGuardrail.validate_tool_call can veto a tool call before dispatch (see the Guardrails card below).

Read-only preset — what it blocks

create_read_only_policy() returns a Policy at priority 100 with 11 deny rules — 2 file-resource rules and 9 tool-name rules — covering the SDK’s built-in mutating tools.

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="Reviewer",
    instructions="Read and summarise the repo — never modify anything.",
)
agent.policy = engine

# Any of these, if attached as tools, are denied before dispatch:
#   write_file, delete_file, edit_file, apply_patch, copy_file,
#   move_file, append_file, atomic_write, hard_delete, ...
agent.start("Summarise src/main.py in five bullet points")

The preset matches by both prefix (tool:write_*) and suffix (tool:*_write*), so custom-named tools like atomic_write and file_write are caught too.

Rule name	Resource pattern	What it blocks
`deny_write`	`file:write`	`check_file()` write path
`deny_delete`	`file:delete`	`check_file()` delete path
`deny_write_tools`	`tool:write_*`	`write_file`, `write_json`, etc.
`deny_write_tools_suffix`	`tool:_write`	`file_write`, `atomic_write`, etc.
`deny_delete_tools`	`tool:delete_*`	`delete_file`, `delete_row`, etc.
`deny_delete_tools_suffix`	`tool:_delete`	`soft_delete`, `hard_delete`, etc.
`deny_edit_tools`	`tool:edit_*`	`edit_file`, `edit_json`, etc.
`deny_patch_tools`	`tool:apply_patch*`	`apply_patch`, `apply_patch_batch`, etc.
`deny_copy_tools`	`tool:copy_*`	`copy_file`, `copy_folder`, etc.
`deny_move_tools`	`tool:move_*`	`move_file`, `move_folder`, etc.
`deny_append_tools`	`tool:append_*`	`append_file`, `append_json`, etc.

An explicit ALLOW rule at higher priority still wins — a deny does not silently override it. Add ALLOW rules for any specific tool you need to permit.

Upgrade note (PraisonAI PR #3632): earlier releases shipped create_read_only_policy() with glob patterns that never matched the SDK’s real tool names. If you relied on the preset as a safety net before this release, your agent could still call write_file / delete_file / edit_file / etc. Upgrade to the fixed release and re-run your safety tests.

How It Works

Component	Purpose
`PolicyRule`	Wildcard resource patterns with `ALLOW`, `DENY`, `ASK`, or `LOG`
`PolicyEngine`	Evaluates rules by priority; optional strict mode
`agent.policy`	Attach the engine before `start()`

Pattern examples: tool:read_file, tool:delete_*, tool:*.

Configuration Options

Option	Type	Default	Description
`strict_mode`	`bool`	`False`	Deny operations not explicitly allowed
`action`	`PolicyAction`	—	`ALLOW`, `DENY`, `ASK`, `LOG`, `RATE_LIMIT`
`resource`	`str`	`None`	Glob pattern (e.g. `tool:shell_*`)
`priority`	`int`	`0`	Higher priority rules evaluate first

Best Practices

Attach policy before the first turn

Set agent.policy = engine immediately after creating the agent.

Start with read-only presets

create_read_only_policy() blocks the SDK’s built-in mutating tools — write_*, delete_*, edit_*, apply_patch*, copy_*, move_*, append_*, and the *_write* / *_delete* suffix forms. Attach it, then add explicit ALLOW rules at higher priority for any specific tool you need to permit.

Use wildcards sparingly

Prefer tool:delete_* over tool:* deny rules so read tools keep working.

Enable strict mode in production

PolicyConfig(strict_mode=True) blocks unknown tool names by default.

Guardrails

Validate agent output before returning to users

Approval

Require human confirmation for sensitive actions

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

Read-only preset — what it blocks

How It Works

Configuration Options

Best Practices

Guardrails

Approval

​Quick Start

​Read-only preset — what it blocks

​How It Works

​Configuration Options

​Best Practices

​Related

Guardrails

Approval

Quick Start

Read-only preset — what it blocks

How It Works

Configuration Options

Best Practices

Related