Approval Protocol

Extensible tool-execution approval system for agents

Agents can require human approval before executing dangerous tools. Set approval=True on any agent to auto-approve, or pass a custom backend for console, webhook, Slack, or any approval channel.

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Ask before destructive tools.", approval=True)
agent.start("List files in the current directory.")

For unified ApprovalSpec configuration (YAML/CLI/Python), see the Approval documentation. Backend selection uses the same string values in --approval and YAML backend: fields.

The user enables approval on an agent; each dangerous tool call pauses until the configured backend allows or denies it.

Quick Start

1. Auto-Approve (Bots / Trusted Envs)

   from praisonaiagents import Agent
   
   agent = Agent(
       name="bot",
       instructions="You are a helpful assistant.",
       approval=True
   )
   agent.start("List files in current directory")

2. Custom Approval Backend

   from praisonaiagents import Agent
   from praisonaiagents.approval import ApprovalRequest, ApprovalDecision
   
   from typing import Optional
   
   class WebhookBackend:
       async def request_approval(self, request: ApprovalRequest) -> ApprovalDecision:
           # POST to your approval service
           return ApprovalDecision(approved=True, approver="webhook")
   
       def request_approval_sync(self, request: ApprovalRequest, timeout: Optional[float] = None) -> ApprovalDecision:
           return ApprovalDecision(approved=True, approver="webhook")
   
   agent = Agent(
       name="bot",
       instructions="You are a helpful assistant.",
       approval=WebhookBackend()
   )
   agent.start("List files in current directory")

3. Default (Console Prompt)

   from praisonaiagents import Agent
   
   # No approval= param → dangerous tools prompt in terminal
   agent = Agent(
       name="interactive",
       instructions="You are a helpful assistant.",
   )
   agent.start("Delete temporary files")

How It Works

ApprovalRequest fields

The request object a backend receives, describing the tool call awaiting approval.

ApprovalDecision fields

The decision object a backend returns. Denials can carry a feedback string to steer the agent’s next turn, and a decision may instead be a deferral carrying escalate=True that hands the call to a human.

Configuration Options

Since PR #4878, the PRAISONAI_AUTO_APPROVE env rung is checked even when a backend is attached — not just for bare-SDK use.

Agent Parameter (Recommended)

Other Methods

Built-in Backends

TypeScript imports

The four core backends have TypeScript parity in praisonai-ts — import them flat from praisonai. See Approval Backends (TypeScript).

Install a TypeScript backend with setApprovalBackend(backend, manager?); the chat/channel backends (SlackApproval, TelegramApproval, …) are Python/CLI-only.

GatewayApprovalBackend webhook payload

GatewayApprovalBackend(notify_url="https://your-consumer/hook") POSTs a JSON payload to the URL:

{
  "request_id": "f3a2…",
  "status": "pending",
  "tool_name": "execute_command",
  "arguments": {"command": "rm -rf /tmp/cache"},
  "agent_name": "ops",
  "risk_level": "high"
}

The status field (added in PR #5916) says which lifecycle event fired:

• The "timed_out" POST is sent only after the "pending" POST has completed, so it never arrives before the card it settles.
• No notify_url ⇒ no webhook is sent, on creation or on timeout.
• A human Approve/Deny does not fire a webhook — only "pending" and "timed_out" are emitted.
• The agent still receives a fail-closed DENY on timeout (approver="gateway:timeout").

Gateway-wired approvals

Setting channels.<platform>.allow_shell: true with auto_approve_shell: false on a gateway channel wires one of these backends automatically — no Python required. If none of them resolve, the gateway installs a CallbackBackend that denies shell tools (execute_command, shell_command, acp_execute_command) so shell never silently auto-approves. See Fail-closed behaviour.

The gateway also routes through this same backend precedence when auto_approve_shell: true is downgraded on exposed / multi-user surfaces (see Bot Shell Execution → Exposure-aware auto-approval). The precedence itself is unchanged — only the trigger.

The routing precedence, exactly as implemented:

approval_mode == "gateway"                → GatewayApprovalBackend()
approval_mode == "http"                   → HTTPApproval(host, port)
approval_mode == "webhook" OR
  approval_webhook_url is set             → WebhookApproval(webhook_url)
                                             ↳ webhook mode with NO url:
                                               warn + fall through to gateway
channel_type == "slack"    + resolved id  → SlackApproval(...)
channel_type == "telegram" + resolved id  → PresentationApprovalBackend(target=chat_id)
channel_type == "discord"  + resolved id  → DiscordApproval(...)
otherwise                                 → GatewayApprovalBackend()  (fallback)

On gateway Telegram channels, the gateway installs PresentationApprovalBackend and renders / resolves taps through the channel adapter — not TelegramApproval, whose own getUpdates loop would conflict with the running bot. See Telegram Durable Approval → Gateway mode.

Custom Backend

Implement request_approval (async) and optionally request_approval_sync to create any approval channel:

from typing import Optional

from praisonaiagents import Agent
from praisonaiagents.approval import ApprovalRequest, ApprovalDecision

class SlackBackend:
    async def request_approval(self, request: ApprovalRequest) -> ApprovalDecision:
        approved = await self._ask_slack(
            f"Approve {request.tool_name} for {request.agent_name}?"
        )
        return ApprovalDecision(
            approved=approved,
            approver="slack",
            metadata={"channel": "#approvals"},
        )

    def request_approval_sync(self, request: ApprovalRequest, timeout: Optional[float] = None) -> ApprovalDecision:
        # Sync fallback for non-async tool execution.
        # `timeout` is optional: None waits indefinitely, > 0 is a per-call limit.
        # Never mutate a shared `self._timeout` here — use the passed value.
        return ApprovalDecision(approved=True, approver="slack")

agent = Agent(
    name="slack-bot",
    instructions="You are a helpful assistant.",
    approval=SlackBackend()
)

A custom backend may also return ApprovalDecision(approved=False, escalate=True) to signal a deferral to a human. Consumers that only check approved still fail-closed correctly, since escalate=True forces approved=False.

Slack Approval

Route tool approvals to Slack — get a rich message with tool details and reply yes or no to approve or deny.

1. Install

   pip install praisonai

2. Set Token

   export SLACK_BOT_TOKEN=xoxb-your-token

3. Use It

   from praisonaiagents import Agent
   from praisonai.bots import SlackApproval
   
   agent = Agent(
       name="assistant",
       instructions="You are a helpful assistant.",
       tools=[execute_command],
       approval=SlackApproval(channel="#approvals")
   )
   agent.start("Delete old log files")

Configuration

Make Slack approvals restart-safe by adding store=:

from praisonai.bots import SlackApproval, ApprovalStore

slack = SlackApproval(
    channel="#approvals",
    store=ApprovalStore(path="~/.praisonai/state/approvals.sqlite"),
)

Approval Keywords

from praisonaiagents import Agent
from praisonai.bots import Bot, SlackApproval

agent = Agent(
    name="assistant",
    instructions="You are a helpful assistant.",
    approval=SlackApproval(channel="U0ABPEV1HK8")  # DM to admin
)

# Users talk via Telegram; dangerous tools approved in Slack
bot = Bot("telegram", agent=agent)
bot.run()

Telegram Approval

Route tool approvals to Telegram — get a message with inline keyboard buttons.

from praisonaiagents import Agent
from praisonai.bots import TelegramApproval

agent = Agent(
    name="assistant",
    tools=[execute_command],
    approval=TelegramApproval(chat_id="YOUR_CHAT_ID")  # token from TELEGRAM_BOT_TOKEN env
)

Discord Approval

Route tool approvals to Discord — get a rich embed and reply yes or no.

from praisonaiagents import Agent
from praisonai.bots import DiscordApproval

agent = Agent(
    name="assistant",
    tools=[execute_command],
    approval=DiscordApproval(channel_id="YOUR_CHANNEL_ID")  # token from DISCORD_BOT_TOKEN env
)

Webhook Approval

POST approval requests to any HTTP endpoint and poll for decisions. Ideal for enterprise dashboards, CI/CD, and custom integrations.

import os
from praisonaiagents import Agent
from praisonai.bots import WebhookApproval

agent = Agent(
    name="assistant",
    tools=[execute_command],
    approval=WebhookApproval(
        webhook_url="https://your-app.com/api/approvals",
        headers={"Authorization": f"Bearer {os.environ['APPROVAL_WEBHOOK_TOKEN']}"},
    ),
)

Agent Approval

Delegate approval decisions to another AI agent. The reviewer sees the tool name and arguments as untrusted data and returns one of APPROVE, DENY, or ESCALATE.

from praisonaiagents import Agent
from praisonaiagents.approval import AgentApproval

# Security reviewer agent
reviewer = Agent(
    name="security-reviewer",
    instructions="Only approve low-risk read operations. Deny anything destructive.",
)

worker = Agent(
    name="assistant",
    tools=[execute_command],
    approval=AgentApproval(approver_agent=reviewer),
)

The reviewer prompt is hardened against prompt injection:

• The tool name and arguments are wrapped in an <arguments>…</arguments> untrusted-data block; forged <arguments>/</arguments> tags in the tool name or values are neutralised to ‹arguments›.
• Command-like argument values (keys in {command, cmd, commands, script, shell, code, source, program}) have any trailing # … shell comment stripped before the reviewer sees them; other args pass through unchanged.
• The reviewer replies with one of APPROVE / DENY / ESCALATE. Parsing is fail-closed: empty, ambiguous, mixed, or negated (“DO NOT APPROVE”) responses → DENY; ESCALATE yields ApprovalDecision(approved=False, escalate=True).

The sanitiser only cleans the copy shown to the reviewer — the arguments the tool actually receives are unchanged.

Handling ESCALATE

When the reviewer is uncertain it returns escalate=True — route the request to a human instead of guessing.

decision = await backend.request_approval(request)

if decision.approved:
    run_tool()
elif decision.escalate:
    # Reviewer deferred to a human — route to a HITL channel
    route_to_human(request, decision)
else:
    deny(decision.reason)

See AgentApproval Hardening for the full security model.

HTTP Approval

Serve a local web dashboard for approvals. Open the URL in your browser and click Approve or Deny.

from praisonaiagents import Agent
from praisonai.bots import HTTPApproval

agent = Agent(
    name="assistant",
    tools=[execute_command],
    approval=HTTPApproval(host="127.0.0.1", port=8899),
)
# When a tool needs approval, open http://127.0.0.1:8899/approve/<request_id>

Multi-Agent Example

Different agents can have different approval policies:

from praisonaiagents import Agent
from praisonaiagents.approval import AgentApproval
from praisonai.bots import SlackApproval, TelegramApproval, HTTPApproval

# Bot agent: auto-approve everything
bot = Agent(name="bot", approval=True)

# Interactive agent: console prompt (default)
interactive = Agent(name="interactive")

# Slack-approved agent
slack_agent = Agent(name="slack-approved", approval=SlackApproval(channel="#approvals"))

# Telegram-approved agent
telegram_agent = Agent(name="tg-approved", approval=TelegramApproval(chat_id="123456"))

# AI-reviewed agent (no human needed)
reviewer = Agent(name="reviewer", instructions="Only approve safe read operations")
ai_agent = Agent(name="ai-reviewed", approval=AgentApproval(approver_agent=reviewer))

# Local dashboard agent
http_agent = Agent(name="dashboard", approval=HTTPApproval(port=8899))

Registry (Advanced)

For global or centralized approval control, use the registry directly:

from praisonaiagents import Agent, AutoApproveBackend
from praisonaiagents.approval import get_approval_registry

registry = get_approval_registry()

# Global auto-approve
registry.set_backend(AutoApproveBackend())

# Per-agent override via registry
registry.set_backend(AutoApproveBackend(), agent_name="trusted-bot")

Dangerous Tools (Default)

These tools require approval by default:

Add or remove requirements:

from praisonaiagents.approval import get_approval_registry

registry = get_approval_registry()
registry.add_requirement("my_dangerous_tool", risk_level="high")
registry.remove_requirement("crawl")

ApprovalStoreProtocol

Optional persistence layer for pending approvals — orthogonal to approval backends. Implement persist, list_pending, and resolve to survive restarts.

from praisonaiagents.approval import ApprovalStoreProtocol, ApprovalRequest, ApprovalDecision

class MyStore:
    async def persist(self, approval_id: str, request: ApprovalRequest, *, expires_at: float) -> None: ...
    async def list_pending(self): ...
    async def resolve(self, approval_id: str, decision: ApprovalDecision) -> None: ...

The wrapper ships ApprovalStore (SQLite) in praisonai.bots. See Durable Approvals.

Live-Authority Binding

Since PraisonAI #4950, every approval that flows through the core ApprovalRegistry is bound to the liveness of the originating turn. If the user hits /stop (or a superseding turn takes over) while an approval is parked on a human — a Telegram tap, a Slack reply, a webhook decision, a local dashboard click — the resolution that lands afterwards is dropped fail-closed at the resolution boundary:

• The tool does not run.
• No session or always grant is persisted for the abandoned turn.
• The returned decision is ApprovalDecision(approved=False, reason="Turn no longer live (stopped or superseded)").

This is inherited automatically by every backend that goes through the registry — the built-ins listed on this page, PresentationApprovalBackend, and any custom third-party backend. It also applies when a backend is attached directly to the Agent via approval=... (the direct-backend path).

Backward-compatibility

ApprovalRequest.liveness defaults to None, and both approve_sync / approve_async accept liveness=None. Existing code that constructs an ApprovalRequest by hand and calls the registry keeps the old always-live behaviour. A liveness probe that raises is treated as live (fail-open on the probe, never on the decision) so a buggy predicate can never wedge the approval path.

What the registry does

The predicate the SDK supplies follows the effective per-turn cancel token — the same authority an explicit cancel_token= argument or a /stop targets — and falls back to the agent’s interrupt controller when no per-turn token is registered. When neither is attached the request stays always-live, preserving today’s behaviour.

Context Isolation

Approvals are scoped to the Python context they are granted in. An approval granted inside an asyncio task, a copy_context().run(...) worker, or a thread spawned with asyncio.to_thread(...) stays in that worker — it does not appear in the parent task, and it does not appear in sibling workers copied from the same parent.

import asyncio
from praisonaiagents import Agent

agent = Agent(name="ops", instructions="Run shell commands", tools=["execute_command"])

async def main():
    # Worker A approves `execute_command` for its own context only.
    # Worker B still gets its own approval prompt — the approval does not leak.
    await asyncio.gather(
        asyncio.to_thread(agent.start, "list /tmp"),
        asyncio.to_thread(agent.start, "list /var/log"),
    )

asyncio.run(main())

This is the behaviour you want for anything that fans out: a single human approval must not silently unlock every parallel branch.

Fixed in PraisonAI PR #5757. Before #5757, mark_approved mutated the set stored in the per-context approval cache in place; because contextvars.copy_context() copies the mapping and not the set, an approval granted in a child context appeared in the parent and in every sibling copied from it. Multi-threaded and asyncio.to_thread users of approval= therefore saw a sibling worker’s approval silently unlock their own tool call. The registry now stores a new set each time, so approvals stay in the context that granted them.

Garbage-collected agents are safe

Letting an Agent be collected without calling .close() is safe on any thread. Agent.__del__ releases the agent’s process-global registry grants (auto_approve_tool entries, session-scoped targets) but never writes the per-context approval cache — a finalizer can run on any thread, in any context, so touching a ContextVar from there would clobber an unrelated worker’s approvals.

• Agent.close() / Agent.aclose() — called by your code on the context that owned the agent — still evict that context’s approval cache for the agent’s scope. Interactive behaviour is unchanged.
• Agent.__del__ — called by the garbage collector on an unspecified thread — leaves every context’s cache alone, and reclaims only the process-global grants.

from praisonaiagents import Agent

# OK on any thread, in any context — finalizer only reclaims
# process-global grants, never writes a ContextVar.
agent = Agent(name="worker", instructions="…", tools=["execute_command"])
agent.start("…")
del agent

# Explicit close() still clears this context's approval cache for the agent's scope.
agent2 = Agent(name="worker", instructions="…", tools=["execute_command"])
try:
    agent2.start("…")
finally:
    agent2.close()

Fixed in PraisonAI PR #5757. The pre-fix finalizer rewrote the per-context approval cache from inside the garbage collector, which could wipe an unrelated context’s approval cache.

Best Practices

Related