Approval - PraisonAI

Agents can request human approval before running a tool.

Quick Start

Simple Usage

Set approval: true to gate every tool behind an interactive y/n prompt on the terminal.

import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'You can execute commands',
  approval: true  // gate every tool call behind a CLI prompt
});

await agent.chat('Delete the temp files');
// → 🔐 Tool "delete_files" requires approval.
//      Input: { "path": "/tmp" }
//
//    Approve? (y/n):

With an ApprovalManager

Pass an ApprovalManager to add auto-approve / auto-deny rules and a custom handler.

import { Agent, ApprovalManager } from 'praisonai';

const approver = new ApprovalManager();
approver.addAutoApprove(/^(read|list|search)_/);  // safe patterns
approver.addAutoDeny(/^delete_/);                 // dangerous patterns

const agent = new Agent({
  instructions: 'You can execute commands',
  approval: approver
});

approval accepts only boolean | ApprovalManager. Per-tool rules live on the ApprovalManager (via addAutoApprove / addAutoDeny), not on the agent.

User Interaction Flow

How `approval: true` behaves

approval: true builds an ApprovalManager for you and wires createCLIApprovalPrompt() as its handler, so the default is a blocking y/n prompt on stdin. Without a handler, requestApproval() waits on respond() — which nobody calls in a plain CLI session — so it would otherwise stall until the 5-minute default-deny timeout. Wiring the prompt is what keeps the default usable.

Denials are fed back to the model, not thrown. When a call is denied, the agent returns this string as the tool result so the model can course-correct and continue the run:

Error: Tool call "<toolName>" was denied by the approval gate.

Correlation with `toolInvocationId`

The gate passes the LLM’s tool_call.id as toolInvocationId on every approval request. Handlers and out-of-band UIs use it to correlate a decision back to the exact pending call — never positionally. This keeps multiple in-flight tool calls disambiguated.

approver.onApprovalRequest(async (request) => {
  // request.toolInvocationId === the LLM's tool_call.id
  return await askUser(request.toolName, request.input);
});

Custom Handler

Register handlers with onApprovalRequest. The first handler to resolve true approves; if all resolve false, the call is denied.

import { Agent, ApprovalManager } from 'praisonai';

const approver = new ApprovalManager({ defaultTimeout: 60_000 });

approver.onApprovalRequest(async (request) => {
  // request: { requestId, toolInvocationId, toolName, input, timestamp, reason? }
  return await askUserViaSlack(request);
});

approver.addAutoApprove(/^(read|list|search)_/);  // auto-approve safe reads
approver.addAutoDeny(/^delete_/);                 // auto-deny deletions

const agent = new Agent({
  instructions: 'You can execute commands',
  approval: approver
});

Auto-deny is checked first (safety), then auto-approve, then handlers.

Configuration Options

ApprovalManager constructor options:

Option	Type	Default	Description
`defaultTimeout`	`number` (ms)	`300000` (5 min)	Time to wait for a decision before default-denying.

ApprovalManager instance methods:

Method	Signature	Description
`onApprovalRequest`	`(handler: (req) => Promise<boolean>) => void`	Register a handler. First to resolve `true` approves.
`addAutoApprove`	`(toolName: string \| RegExp, inputPattern?) => void`	Auto-approve matching calls. Checked after auto-deny.
`addAutoDeny`	`(toolName: string \| RegExp, inputPattern?) => void`	Auto-deny matching calls. Checked first (safety).
`requestApproval`	`({ toolInvocationId?, toolName, input, reason?, timeout? }) => Promise<boolean>`	The gate itself.
`respond`	`(response) => void`	Answer a pending request from an out-of-band UI.
`getPendingRequests`	`() => ToolApprovalRequest[]`	List requests awaiting a decision.
`cancel`	`(requestId: string) => void`	Cancel one pending request (resolves denied).
`cancelAll`	`() => void`	Cancel all pending requests.

Advanced

Per-tool wrapper: `withApproval`

Wrap a single tool so it gates itself. Throws ToolApprovalDeniedError on deny unless you provide onDenied.

import { withApproval } from 'praisonai';
import { promises as fs } from 'fs';

const deleteFile = withApproval({
  name: 'deleteFile',
  needsApproval: true,
  execute: async (args: { path: string }) => {
    await fs.unlink(args.path);
    return { success: true };
  },
  onDenied: () => ({ success: false })  // optional fallback instead of throwing
});

Global manager: `getApprovalManager` / `setApprovalManager`

withApproval uses a process-global manager when none is passed. Configure it once.

import { getApprovalManager, setApprovalManager, ApprovalManager, createCLIApprovalPrompt } from 'praisonai';

const manager = new ApprovalManager();
manager.onApprovalRequest(createCLIApprovalPrompt());
setApprovalManager(manager);

// later, anywhere in the process
const shared = getApprovalManager();

Dangerous-pattern helpers

Pre-built regexes and checkers flag risky inputs so you can require approval only when needed.

import { isDangerous, createDangerousPatternChecker, DANGEROUS_PATTERNS } from 'praisonai';

isDangerous('rm -rf /');  // → true

const needsApproval = createDangerousPatternChecker([/\bwipe\b/i]);

DANGEROUS_PATTERNS exposes fileDelete, dbDestructive, shellDangerous, and networkSensitive.

Events

ApprovalManager is an event emitter — subscribe with .on(...) to drive an out-of-band UI (e.g. a web dashboard that answers via respond()).

Event	Fired when
`approval-request`	A call awaits a decision.
`approval-response`	`respond()` resolves a request.
`auto-approved`	An `addAutoApprove` rule matched.
`auto-denied`	An `addAutoDeny` rule matched.
`timeout`	No decision arrived before `defaultTimeout`.

Errors

Error	Thrown when
`ToolApprovalDeniedError`	A `withApproval` tool is denied and no `onDenied` is set.
`ToolApprovalTimeoutError`	An approval request exceeds its timeout.

Python parity: the Python approval API exposes ApprovalDecision.scope ("once" | "session" | "always") and ApprovalDecision.feedback. The TypeScript gate re-prompts every call and returns a fixed refusal string — there is no scope or per-decision feedback channel yet.

Best Practices

Auto-approve safe actions

Reading data is usually safe. approver.addAutoApprove(/^(read|list|search)_/) skips the prompt for read-only tools.

Auto-deny dangerous patterns

Auto-deny is checked first. Block deletions and destructive commands with approver.addAutoDeny(/^delete_/).

Set reasonable timeouts

The default is 5 minutes and default-denies on timeout. Lower it for interactive flows: new ApprovalManager({ defaultTimeout: 60_000 }).

Correlate with toolInvocationId

In UIs with concurrent calls, always route decisions by request.toolInvocationId, never by order — positional matching authorises the wrong call.

Guardrails

Input/output validation

Security

Security features

​Quick Start

​User Interaction Flow

​How approval: true behaves

​Correlation with toolInvocationId

​Custom Handler

​Configuration Options

​Advanced

​Per-tool wrapper: withApproval

​Global manager: getApprovalManager / setApprovalManager

​Dangerous-pattern helpers

​Events

​Errors

​Best Practices

​Related

Guardrails

Security

Quick Start

User Interaction Flow

How `approval: true` behaves

Correlation with `toolInvocationId`

Custom Handler

Configuration Options

Advanced

Per-tool wrapper: `withApproval`

Global manager: `getApprovalManager` / `setApprovalManager`

Dangerous-pattern helpers

Events

Errors

Best Practices

Related