Tool Approval

Declare that a tool needs human sign-off before it runs

Declare a tool needs human approval directly on the @tool decorator; every runtime honours it.

from praisonaiagents import Agent, tool

@tool(approval=True)
def delete_account(user_id: str) -> str:
    """Permanently delete a user account."""
    return f"Deleted {user_id}"

agent = Agent(
    name="Support",
    instructions="Help users. Ask before doing anything destructive.",
    tools=[delete_account],
)
agent.start("Delete account u_42")

The tool carries its own approval requirement — the agent pauses and asks a human before delete_account runs.

Quick Start

1. One-line, high-risk default

   approval=True registers the tool at "high" risk:

   from praisonaiagents import Agent, tool
   
   @tool(approval=True)
   def refund(order_id: str) -> str:
       """Issue a refund on an order."""
       return f"Refunded {order_id}"
   
   agent = Agent(
       name="Support",
       instructions="Help support agents process refunds.",
       tools=[refund],
   )
   agent.start("Refund order O-101")

2. Explicit risk level

   Pass a string to choose the level explicitly:

   from praisonaiagents import tool
   
   @tool(approval="critical")
   def deploy(env: str) -> str:
       """Deploy to an environment."""
       return f"Deployed to {env}"

3. Renamed tool

   Registration keys off the resolved tool name — not the function name:

   from praisonaiagents import tool
   
   @tool(name="danger_op", approval=True)
   def internal_fn(payload: str) -> str:
       """Run a dangerous operation."""
       return f"Ran {payload}"
   
   # The approval requirement is registered under "danger_op".

How It Works

Registration happens once at import time; enforcement happens on every call.

Choose your level

Scope of a skill grant

When a skill’s allowed-tools frontmatter grants approval for a tool, the grant is scoped to the agent instance that activated the skill. It does not leak onto other agents in the same process — even other unnamed agents that share the default display name "Agent". Each Agent gets a unique per-instance approval-scope id at construction, and skill grants are keyed by that id rather than the display name.

from praisonaiagents import Agent, tool

@tool(approval=True)
def destructive_delete(path: str) -> str:
    """Delete a file."""
    return f"Deleted {path}"

reviewer = Agent(skills=["./skills/file-reviewer"])   # grants read_file via allowed-tools
deleter  = Agent(tools=[destructive_delete])          # separate agent; still gated

# `deleter` cannot inherit `reviewer`'s skill grant, even though both default to name="Agent".

Configuration Options

Accepted values for approval (canonical):

Deprecated alias: requires_approval

requires_approval= is the old spelling. It still works but emits a DeprecationWarning — migrate to approval=.

from praisonaiagents import tool

@tool(requires_approval=True)          # works, but warns
def legacy_delete(user_id: str) -> str:
    """Delete a user account."""
    return f"Deleted {user_id}"
# DeprecationWarning: use approval= instead of requires_approval=

Attributes on the returned FunctionTool:

Common Patterns

Mark one tool critical alongside safe tools

from praisonaiagents import Agent, tool

@tool
def get_balance(account_id: str) -> str:
    """Read an account balance."""
    return f"{account_id}: $1,240.00"

@tool(approval="critical")
def wire_transfer(account_id: str, amount: float) -> str:
    """Wire money out of an account — irreversible."""
    return f"Wired ${amount} from {account_id}"

agent = Agent(
    name="Finance",
    instructions="Help with account questions. Confirm before moving money.",
    tools=[get_balance, wire_transfer],
)
agent.start("What's the balance on acct-9 and wire $500 out")

Rename a tool and keep it gated

from praisonaiagents import tool

@tool(name="prod_deploy", approval="critical")
def deploy(env: str) -> str:
    """Deploy to production."""
    return f"Deployed to {env}"

# The registry key is "prod_deploy" — the name the LLM and agent see.

Compose with agent-level approval config

The decorator declares what needs approval; the agent config decides how to ask.

from praisonaiagents import Agent, tool

@tool(approval=True)
def refund(order_id: str) -> str:
    """Issue a refund."""
    return f"Refunded {order_id}"

agent = Agent(
    name="AsyncSupport",
    instructions="Process refunds.",
    tools=[refund],
    approval={"backend": "slack"},   # decorator says gate it; agent says ask via Slack
)
agent.start("Refund order O-101")

User interaction flow

A real run looks like this:

1. You run the agent: agent.start("Delete account u_42").
2. The LLM decides to call delete_account.
3. The console approval prompt appears with five choices: [o] once, [s] session, [a] always, [n] no, [d] deny & redirect.
4. You pick — the tool runs, or is skipped.

See Interactive Tool Approval for the full prompt semantics.

Best Practices

Related