Skip to main content
Approval pauses an agent before it runs a risky tool and asks a human (or another channel) to allow or deny it.
Behaviour change (PR #2122): Approval is enabled by default. YAML configs that omitted the approval key previously got enabled: false; they now get the prompting policy. Set approval: false to keep the old behaviour.
Sync and Async Parity: Approval checks now work uniformly in both sync and async tool execution paths. Previously, async calls bypassed approval prompts.

​
Quick Start

1

Simple Usage

Approval is on by default. To disable:
from praisonaiagents import Agent

agent = Agent(name="Admin", instructions="Manage the server", approval=False)
agent.start("Clean up old logs")
2

Per-tool approval

agent = Agent(
    name="Admin",
    instructions="...",
    approval={
        "enabled": True,
        "default_policy": "prompt",
        "approve_tools": {"shell": "critical", "read_file": "low"},
    },
)
3

Pick Backend

agent = Agent(name="Admin", instructions="...", approval="slack")
4

Full Configuration

agent = Agent(
    name="Admin",
    instructions="...",
    approval={
        "enabled": True,
        "backend": "slack",
        "approve_all_tools": False,
        "timeout": 120,
        "approve_level": "high",
    },
)

​
How users approve

​
Configuration

The default console backend requires a sync call stack. If you decorate a tool with @require_approval and invoke it from an async agent (achat, astart, async tools, async callbacks), the call now raises PermissionError. Configure a non-console backend (HTTP, Slack, webhook) or drive the agent from sync code.
OptionTypeDefaultDescription
enabledbooltrueTurn approval on/off — safe by default
backendstr"console"One of: console, slack, telegram, discord, webhook, http, agent, auto, none
approve_all_toolsboolfalseIf true, every tool needs approval (not just risky ones)
timeoutfloatnullSeconds to wait for a decision; null = no timeout
approve_levelApprovalLevel | nullnullAuto-approve up to this risk level: low, medium, high, critical
guardrailsstrnullFree-text guardrail description
default_policy"deny" | "prompt" | "allow""prompt"Policy when no per-tool entry matches
approve_toolsDict[str, ApprovalLevel] | nullnullPer-tool granularity, e.g. {"shell": "critical"}
permissionsDict[str, Any]nullDeclarative allow/deny/ask rules. See Declarative Permissions.
Approval backends decide how to ask a human (Slack, console, …). Declarative permissions decide whether to ask at all in non-interactive runs.

​
YAML

agents:
  admin:
    role: Server admin
    approval:
      enabled: true
      backend: slack
      timeout: 120
      approve_level: high
      default_policy: prompt
      approve_tools:
        shell: critical
        read_file: low

​
Hook installation

Register a before_tool hook that enforces the policy: 
from praisonai._approval_spec import ApprovalSpec

spec = ApprovalSpec(
    enabled=True,
    default_policy="prompt",
    approve_tools={"shell": "critical"},
)
spec.install_hook()
Shorthands: approval: true (console), approval: slack (named backend), approval: false / null (off).
Unknown keys raise ValueError — typos like approve_levels: will fail loudly.

​
CLI

praisonai "deploy" --approval slack --approval-timeout 120 --approve-level high
CLI flagYAML / Python field
--trustbackend: auto
--approval <name>backend: <name>
--approve-all-toolsapprove_all_tools: true
--approval-timeout <s>timeout: <s>
--approve-level <l>approve_level: <l>
--allow <pattern>permissions: { "<pattern>": allow }
--deny <pattern>permissions: { "<pattern>": deny }
--permissions <file>Load rules from YAML/JSON file
--permission-default <action>permissions: { "*": <action> }
--guardrail "<txt>"guardrails: "<txt>"

​
Using approval with async agents

When using async agents (.achat(), .astart(), or async tools), the default console backend will fail with PermissionError. Configure a non-console backend: 
from praisonaiagents import Agent
from praisonaiagents.approval import get_approval_registry, WebhookBackend

# Configure webhook backend for async compatibility
get_approval_registry().set_backend(
    WebhookBackend(url="http://localhost:8080/approve")
)

agent = Agent(
    name="AsyncBot",
    instructions="Process requests asynchronously",
    approval=True
)

# This now works with async agents
await agent.astart("Delete old files")
Available non-console backends: webhook, http, slack, telegram, discord, agent.

​
Troubleshooting

ErrorCauseFix
PermissionError: Approval request failed for <tool>Async agent with console backendConfigure a non-console backend
RuntimeError: Tool '<tool>' requires approval but cannot use console I/O from async context.Same root cause, surfaced earlierSame fix

​
Best practices

No env vars needed; you see the prompt directly in the terminal.
Routes approval requests to a channel humans already watch.
Without a timeout, the agent blocks indefinitely waiting for a decision.
approve_level: high lets safe tools run without prompts and only gates the dangerous ones.

All backend protocols (Slack, Telegram, Discord, Webhook, HTTP, Agent)

Full CLI flag reference