<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/2.6-autonomy-and-handoff -->

# Autonomy and Handoff

- api.md
- src/praisonai-agents/praisonaiagents/agent/agent.py
- src/praisonai-agents/praisonaiagents/llm/llm.py

This document covers two interrelated agent control systems in PraisonAI: **autonomy** for managing autonomous agent execution and preventing infinite loops, and **handoff** for enabling agent-to-agent delegation. Both systems provide essential controls for multi-agent coordination and safe autonomous operation.

For information about multi-agent orchestration patterns, see [Multi-Agent Orchestration](/MervinPraison/PraisonAI/2.5-multi-agent-orchestration). For planning and execution strategies, see [Planning System](/MervinPraison/PraisonAI/3.3-planning-system).

## Overview

The autonomy system prevents agents from entering infinite execution loops (doom loops) while allowing configurable levels of autonomous operation. The handoff system enables agents to delegate tasks to other specialized agents, creating dynamic collaboration patterns.

**Key Concepts:**

- Autonomy : Controls how freely an agent can execute without human intervention
- Doom Loop Prevention : Detects and breaks repetitive execution patterns
- Handoff : Structured mechanism for agent-to-agent task delegation
- Verification Hooks : Optional approval gates for autonomous actions

## Autonomy System Architecture

The autonomy system consists of three core components that work together to manage agent execution safety and control.

```

```

**Autonomy System: Core components managing autonomous execution safety**

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py1044-1045](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1044-L1045) [src/praisonai-agents/praisonaiagents/agent/agent.py433](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L433-L433) [src/praisonai-agents/praisonaiagents/agent/agent.py488-491](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L488-L491)

### DoomLoopTracker

`DoomLoopTracker` monitors agent execution patterns to detect infinite loops. It analyzes sequences of tool calls, outputs, and state changes to identify repetitive behavior.

**Detection Criteria:**

**Configuration:**

```

```

**Behavior:**

1. Tracks execution history (tool calls, arguments, outputs)
2. Calculates pattern similarity using text comparison
3. Identifies repetitive sequences
4. Triggers escalation when threshold exceeded

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py1044-1045](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1044-L1045)

### AutonomyTrigger

`AutonomyTrigger` manages escalation logic when doom loops or execution limits are detected. It determines when to break autonomous execution and seek human intervention.

**Escalation Strategies:**

```

```

**AutonomyTrigger: Escalation decision flow based on detected patterns**

**Trigger Types:**

**Example Configuration:**

```

```

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py433](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L433-L433) [src/praisonai-agents/praisonaiagents/agent/agent.py488-491](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L488-L491)

### run_autonomous Method

The `run_autonomous()` method enables fully autonomous agent operation with built-in safety controls. Unlike `start()` which executes a single task, `run_autonomous()` allows continuous operation with doom loop protection.

**Method Signature:**

```

```

**Parameters:**

**Execution Flow:**

```

```

**run_autonomous: Execution flow with safety checks at each iteration**

**Example Usage:**

```

```

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py1044-1045](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1044-L1045)

### Verification Hooks Integration

Verification hooks provide approval gates for autonomous operations, allowing human oversight at critical decision points.

```

```

**Hook Events:**

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py434](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L434-L434) [src/praisonai-agents/praisonaiagents/agent/agent.py492](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L492-L492)

## Handoff System Architecture

The handoff system enables structured agent-to-agent delegation, allowing specialized agents to handle specific subtasks while maintaining conversation context and state.

```

```

**Handoff System: Agent-to-agent delegation with context transfer**

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py418](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L418-L418) [src/praisonai-agents/praisonaiagents/agent/agent.py151-152](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L151-L152)

### Handoff Class

The `Handoff` class defines a delegation relationship between agents. It specifies which agent to hand off to and under what conditions.

**Class Structure:**

```

```

**Handoff Properties:**

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py151-152](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L151-L152)

### HandoffConfig

`HandoffConfig` provides advanced configuration options for handoff behavior, including custom decision functions and context management.

```

```

**Configuration Options:**

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py151-152](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L151-L152)

### HandoffResult

After delegation, the target agent returns a `HandoffResult` containing the execution outcome and metadata.

**Result Structure:**

```

```

**Example:**

```

```

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py151-152](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L151-L152)

### Handoff Execution Flow

The following diagram shows how handoffs are executed during agent task processing.

```

```

**Handoff Execution: Sequence of operations during agent delegation**

**Execution Steps:**

1. Condition Evaluation : Coordinator checks if task matches handoff conditions
2. Context Transfer : Conversation history, state, and tools packaged for target
3. Delegation : Target agent receives task with full context
4. Execution : Target agent processes task independently
5. Result Return : HandoffResult returned to coordinator
6. Context Merge : State updates merged back into coordinator context

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py418](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L418-L418) [src/praisonai-agents/praisonaiagents/agent/agent.py151-152](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L151-L152)

## Integration: Autonomy and Handoff

Autonomy and handoff systems work together to enable safe, collaborative multi-agent execution.

```

```

**Integration: Combined autonomy and handoff control flow**

**Shared Configuration:**

```

```

**Iteration Counting:**

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py433](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L433-L433) [src/praisonai-agents/praisonaiagents/agent/agent.py418](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L418-L418)

## Configuration Reference

Complete configuration options for autonomy and handoff systems.

### Autonomy Parameter

```

```

### Handoff Parameter

```

```

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py433](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L433-L433) [src/praisonai-agents/praisonaiagents/agent/agent.py418](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L418-L418) [src/praisonai-agents/praisonaiagents/agent/agent.py488-491](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L488-L491) [src/praisonai-agents/praisonaiagents/agent/agent.py461](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L461-L461)

## Common Patterns

### Pattern 1: Safe Autonomous Operation

```

```

### Pattern 2: Specialist Delegation

```

```

### Pattern 3: Hierarchical Autonomy

```

```

### Pattern 4: Escalation with Human-in-the-Loop

```

```

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py1044-1045](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1044-L1045) [src/praisonai-agents/praisonaiagents/agent/agent.py418](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L418-L418)
