<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/6.2-human-approval-system -->

# Human Approval System

- README.md
- api.md
- src/praisonai/README.md

The Human Approval System provides a human-in-the-loop safety mechanism for controlling the execution of potentially dangerous tools in PraisonAI agents. This system requires explicit human approval before executing high-risk operations such as command execution, file modifications, or code execution.

For information about general safety features and output validation, see [Guardrails](/MervinPraison/PraisonAI/4.2-knowledge-management). For tool integration patterns, see [Tool Integration](/MervinPraison/PraisonAI/5.1-tool-integration).

## Purpose and Scope

The Human Approval System addresses the critical safety requirement of preventing autonomous agents from executing dangerous operations without human oversight. It implements a decorator-based approval framework that:

- Classifies tools by risk level (critical, high, medium, low)
- Requires explicit approval before executing dangerous operations
- Provides context management to prevent repeated approval requests
- Supports both interactive console approval and programmatic approval callbacks
- Integrates seamlessly with the agent execution pipeline

## System Architecture

The approval system is implemented as a standalone module that integrates with the agent execution flow through decorators and callback mechanisms.

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/approval.py1-263](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/approval.py#L1-L263)

## Core Components

### ApprovalDecision Class

The `ApprovalDecision` class represents the result of an approval request:

**Sources:** [src/praisonai-agents/praisonaiagents/approval.py31-36](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/approval.py#L31-L36)

### Approval Decorator

The `@require_approval` decorator marks functions as requiring human approval:

```

```

The decorator:

- Registers the tool in APPROVAL_REQUIRED_TOOLS
- Records the risk level in TOOL_RISK_LEVELS
- Intercepts function calls to request approval
- Manages approval context to prevent double approval

**Sources:** [src/praisonai-agents/praisonaiagents/approval.py61-126](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/approval.py#L61-L126)

### Context Management

The approval system uses `ContextVar` to track approved tools in the current execution context:

**Sources:** [src/praisonai-agents/praisonaiagents/approval.py46-59](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/approval.py#L46-L59)

## Risk Levels and Tool Classification

The system defines four risk levels for tool classification:

```

```

**Default Tool Classifications:**

**Sources:** [src/praisonai-agents/praisonaiagents/approval.py218-242](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/approval.py#L218-L242)

## Approval Workflow

The approval workflow follows this sequence when a decorated tool is executed:

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/approval.py72-125](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/approval.py#L72-L125) [src/praisonai-agents/praisonaiagents/approval.py184-216](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/approval.py#L184-L216)

## Integration with Agents

The approval system integrates with the agent execution pipeline through the `execute_tool` method:

```

```

**Integration Points:**

1. Tool Decoration : Dangerous tools are decorated with @require_approval
2. Agent Execution : The agent.execute_tool() method triggers approval checks
3. Context Management : Agents automatically mark approved tools in their execution context

**Sources:** [src/praisonai/tests/unit/test_approval_agent_integration.py20-62](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/tests/unit/test_approval_agent_integration.py#L20-L62) [src/praisonai/tests/unit/test_approval_basic.py184-209](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/tests/unit/test_approval_basic.py#L184-L209)

## Console Approval Callback

The default `console_approval_callback` provides interactive approval through the terminal:

```

```

**Features:**

- Rich console formatting with risk-level color coding
- Argument truncation for long values
- Keyboard interrupt handling
- Detailed approval reasoning

**Sources:** [src/praisonai-agents/praisonaiagents/approval.py128-182](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/approval.py#L128-L182)

## Configuration and Customization

### Custom Approval Callbacks

You can implement custom approval logic by setting a custom callback:

```

```

### Dynamic Tool Registration

Tools can be dynamically added or removed from approval requirements:

**Sources:** [src/praisonai-agents/praisonaiagents/approval.py244-260](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/approval.py#L244-L260)

### Auto-Approval for Testing

For automated testing, you can implement auto-approval callbacks:

```

```

**Sources:** [src/praisonai/tests/unit/test_approval_agent_integration.py84-94](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/tests/unit/test_approval_agent_integration.py#L84-L94)

## Testing and Validation

The approval system includes comprehensive testing approaches:

### Unit Tests

- Basic functionality : Decorator application, context management
- Tool integration : Verification that dangerous tools require approval
- Callback system : Testing approval and denial scenarios

### Integration Tests

- Agent execution : Testing approval through agent.execute_tool()
- Interactive testing : Manual approval testing with user input
- Auto-approval : Automated testing with programmatic callbacks

### Test Categories

**Sources:** [src/praisonai/tests/unit/test_approval_basic.py1-286](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/tests/unit/test_approval_basic.py#L1-L286) [src/praisonai/tests/unit/test_approval_interactive.py1-281](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/tests/unit/test_approval_interactive.py#L1-L281) [src/praisonai/tests/unit/test_approval_agent_integration.py1-380](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/tests/unit/test_approval_agent_integration.py#L1-L380)
