<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/3-execution-and-control -->

# Execution and Control

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

## Purpose and Scope

This document provides an overview of how PraisonAI executes and controls agent tasks through workflows, process strategies, planning modes, and autonomy mechanisms. It covers the core execution engine, task status management, flow control, and error handling.

For detailed information on specific subsystems:

- Workflow patterns and control flow operators - see Workflow System
- Sequential, hierarchical, and workflow process strategies - see Process Strategies
- Planning agents and plan execution - see Planning System
- Self-reflection and quality improvement - see Reflection System
- Individual agent configuration - see Agent Class
- Task definitions and validation - see Task System

## Execution Architecture

PraisonAI's execution system centers on the `Agents` class, which orchestrates task execution across multiple agents using configurable process strategies. The architecture separates task definition, agent assignment, and execution flow, allowing flexible composition of multi-agent workflows.

```

```

**Key Components**

Sources: [src/praisonai-agents/praisonaiagents/agents/agents.py172-521](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L172-L521) [src/praisonai-agents/praisonaiagents/process/process.py17-36](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/process/process.py#L17-L36) [src/praisonai-agents/praisonaiagents/task/task.py15-115](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/task/task.py#L15-L115)

## Task Status Management

Tasks progress through a lifecycle tracked by the `TaskStatus` enum. The execution engine uses status values to determine task eligibility, manage retries, and coordinate dependencies.

```

```

**Status Definitions**

**Status Checking Logic**

The `Agents` class checks task status to determine execution flow:

```

```

Tasks with status `NOT_STARTED` are candidates for execution. The `Process` class uses `_find_next_not_started_task()` to select the next task based on dependencies and retry limits [process.py204-239](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/process.py#L204-L239)

Sources: [src/praisonai-agents/praisonaiagents/agents/agents.py22-28](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L22-L28) [src/praisonai-agents/praisonaiagents/agents/agents.py610-612](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L610-L612) [src/praisonai-agents/praisonaiagents/process/process.py204-239](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/process/process.py#L204-L239)

## Execution Flow Control

The execution engine supports multiple flow control mechanisms for coordinating task execution across agents.

### Task Dependencies

Tasks specify dependencies through `next_tasks` and `previous_tasks` lists. The engine automatically sets up sequential flow when tasks don't specify explicit dependencies [agents.py446-452](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L446-L452):

```

```

### Context Passing

Task context flows automatically between dependent tasks. The `process_task_context()` helper extracts results from previous tasks and formats them for consumption [agents.py111-170](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L111-L170):

- String context : Passed as-is with "Input Content:" prefix
- Task context : Extracts task.result.raw from completed tasks
- Vector store context : Queries knowledge base with user filters
- List context : Joins items into space-separated string

Context accumulation can be controlled via `task.retain_full_context`:

- False (default): Only includes most recent previous task
- True : Includes all previous tasks in dependency chain

Sources: [src/praisonai-agents/praisonaiagents/agents/agents.py111-170](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L111-L170) [src/praisonai-agents/praisonaiagents/agents/agents.py446-452](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L446-L452) [src/praisonai-agents/praisonaiagents/process/process.py147-202](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/process/process.py#L147-L202)

## Retry and Error Handling

PraisonAI implements multi-level retry logic to handle transient failures and validation errors.

```

```

**Retry Configuration**

**Guardrail Validation Retry**

When a guardrail fails validation, the task stores feedback and retries [task.py88-94](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/task.py#L88-L94):

```

```

The next execution attempt includes this feedback in the task prompt [process.py150-161](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/process.py#L150-L161)

**Fallback Mechanism**

If no valid next task is found, `_find_next_not_started_task()` performs up to 3 fallback attempts to locate an executable task [process.py204-239](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/process.py#L204-L239)

Sources: [src/praisonai-agents/praisonaiagents/agents/agents.py392-398](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L392-L398) [src/praisonai-agents/praisonaiagents/task/task.py88-94](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/task/task.py#L88-L94) [src/praisonai-agents/praisonaiagents/process/process.py17-19](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/process/process.py#L17-L19) [src/praisonai-agents/praisonaiagents/process/process.py150-161](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/process/process.py#L150-L161) [src/praisonai-agents/praisonaiagents/process/process.py204-239](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/process/process.py#L204-L239)

## Planning Mode

Planning mode enables agents to create multi-step plans before execution, improving task decomposition and goal achievement.

### Planning Agent Architecture

```

```

**Planning Configuration**

Planning is enabled via the `Agents` constructor [agents.py462-469](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L462-L469):

**Planning Workflow**

1. Plan Creation : The planning agent analyzes the task and creates a structured plan
2. Plan Approval : If auto_approve_plan=False , waits for human approval
3. Step Execution : Executes each plan step sequentially
4. Context Passing : Previous step results feed into next step
5. Plan Storage : Plan stored in _current_plan for inspection

The planning agent uses the configured `planning_llm` and optional `planning_tools` to research and create plans [agents.py453-469](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L453-L469)

Sources: [src/praisonai-agents/praisonaiagents/agents/agents.py462-469](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L462-L469) [README.md555-579](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L555-L579)

## Process Strategies

The `Process` class implements three execution strategies: sequential, hierarchical, and workflow. Strategy selection affects task ordering, agent selection, and delegation patterns.

```

```

**Strategy Comparison**

**Configuration**

Process strategy is set via the `process` parameter [agents.py399](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L399-L399):

```

```

Detailed implementation and examples are covered in [Process Strategies](/MervinPraison/PraisonAI/3.2-process-strategies).

Sources: [src/praisonai-agents/praisonaiagents/agents/agents.py399](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L399-L399) [src/praisonai-agents/praisonaiagents/process/process.py17-36](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/process/process.py#L17-L36)

## Autonomy Control

The autonomy system prevents infinite loops and controls agent decision-making autonomy through tracking and trigger mechanisms.

### DoomLoopTracker

Monitors task execution patterns to detect infinite loops. Referenced in code but implementation details in Agent class (see [Autonomy and Handoff](/MervinPraison/PraisonAI/2.6-autonomy-and-handoff)).

### Execution Monitoring

The execution engine tracks iterations and enforces limits [agents.py385-395](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L385-L395):

- max_iter : Maximum iterations (default: 10)
- max_retries : Maximum retry attempts (default: 5)

When limits are exceeded, execution terminates with appropriate error status.

### Autonomy Configuration

Autonomy features are configured at both the Agents and Agent level [agents.py189](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L189-L189):

```

```

Sources: [src/praisonai-agents/praisonaiagents/agents/agents.py189](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L189-L189) [src/praisonai-agents/praisonaiagents/agents/agents.py385](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L385-L385) [src/praisonai-agents/praisonaiagents/agents/agents.py395](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L395-L395)

## Execution Lifecycle Hooks

The execution system provides callback hooks for monitoring and intervention at key lifecycle events.

**Available Hooks**

**Configuration**

Hooks are configured via the `hooks` parameter [agents.py293-307](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L293-L307):

```

```

**Completion Checker**

The `completion_checker` validates task completion criteria. Default implementation checks for:

- JSON output if task.output_json is set
- Pydantic output if task.output_pydantic is set
- Non-empty string output otherwise

Custom checkers can implement domain-specific validation [agents.py584-589](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L584-L589)

Sources: [src/praisonai-agents/praisonaiagents/agents/agents.py293-307](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L293-L307) [src/praisonai-agents/praisonaiagents/agents/agents.py395](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L395-L395) [src/praisonai-agents/praisonaiagents/agents/agents.py403-407](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L403-L407) [src/praisonai-agents/praisonaiagents/agents/agents.py584-589](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L584-L589)

## Token Tracking and Telemetry

The execution engine integrates with the telemetry system to track LLM usage and performance metrics.

### Token Collection

When executing tasks, the engine tracks token usage per agent via the LLM instance [agents.py615-689](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L615-L689):

```

```

### Telemetry Integration

The Agents class initializes telemetry on startup [agents.py516-520](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L516-L520):

```

```

Token metrics are attached to `TaskOutput` objects and aggregated for reporting. See [Telemetry](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/Telemetry) for detailed metric collection.

Sources: [src/praisonai-agents/praisonaiagents/agents/agents.py516-520](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L516-L520) [src/praisonai-agents/praisonaiagents/agents/agents.py615-619](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L615-L619) [src/praisonai-agents/praisonaiagents/agents/agents.py686-689](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L686-L689)

## AutoAgents Execution

`AutoAgents` extends the standard execution model with automatic agent and task generation from natural language instructions.

### Generation and Execution Flow

```

```

**Configuration Generation**

AutoAgents uses an LLM to generate agent and task configurations [autoagents.py273-450](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/autoagents.py#L273-L450):

1. Prompt Construction : Builds prompt with available tools and constraints
2. LLM Invocation : Calls LLM with structured output schema
3. Validation : Checks for required fields and proper structure
4. Retry Logic : Up to 3 attempts with previous response feedback
5. Fallback : Uses JSON mode if structured output fails

**Agent Assignment**

Tool assignment follows this priority [autoagents.py215-243](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/autoagents.py#L215-L243):

1. Match tools by name from agent_config.tools list
2. Include tools from all agent's tasks
3. Fallback to all available tools if no matches

The generated agents and tasks are passed to the parent `Agents` class for standard execution [autoagents.py154-168](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/autoagents.py#L154-L168)

Sources: [src/praisonai-agents/praisonaiagents/agents/autoagents.py154-168](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L154-L168) [src/praisonai-agents/praisonaiagents/agents/autoagents.py215-243](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L215-L243) [src/praisonai-agents/praisonaiagents/agents/autoagents.py273-450](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L273-L450)

## Async Execution

All execution methods have async equivalents for non-blocking operation.

**Async Methods**

**Usage Pattern**

```

```

The async implementation uses the same logic as sync but with `await` for agent communication [agents.py591-716](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L591-L716)

Sources: [src/praisonai-agents/praisonaiagents/agents/agents.py591-716](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L591-L716)

## Memory Integration

Task execution integrates with the memory system for persistent context across runs.

### Memory Storage

When memory is enabled, task results are automatically stored [agents.py472-513](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L472-L513):

- Short-term memory : Recent task outputs for context
- Long-term memory : Important findings based on quality scores
- Entity memory : Structured data extracted from outputs
- User memory : User-specific preferences and history

### Shared Memory

The Agents class supports shared memory across all tasks [agents.py510-513](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L510-L513):

```

```

All agents can read and write to the shared memory store, enabling cross-task learning and context accumulation.

### Knowledge Base Queries

Tasks can query the knowledge base via context [agents.py141-168](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/agents.py#L141-L168):

```

```

The execution engine automatically queries the knowledge base and includes results in the task prompt.

Sources: [src/praisonai-agents/praisonaiagents/agents/agents.py141-168](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L141-L168) [src/praisonai-agents/praisonaiagents/agents/agents.py472-513](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L472-L513) [src/praisonai-agents/praisonaiagents/agents/agents.py510-513](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L510-L513)
