<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/3.1-workflow-system -->

# Workflow System

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

## Purpose and Scope

The Workflow System provides deterministic, multi-step execution pipelines with advanced control flow patterns for orchestrating agents and tasks. It enables sequential, conditional, parallel, and iterative execution patterns through both programmatic (Python) and declarative (YAML) interfaces.

This document covers the `Workflow` class, control flow constructs (`route()`, `parallel()`, `loop()`, `repeat()`), workflow context management, and YAML-based workflow definitions. For information about high-level process strategies (sequential/hierarchical/parallel), see [Process Strategies](/MervinPraison/PraisonAI/3.2-process-strategies). For AI-driven planning capabilities, see [Planning System](/MervinPraison/PraisonAI/3.3-planning-system). For multi-agent coordination patterns, see [Multi-Agent Orchestration](/MervinPraison/PraisonAI/2.5-multi-agent-orchestration).

## Core Architecture

The workflow system is built around the `Workflow` class which orchestrates execution of steps with support for agents, tasks, and custom functions. Each step can be an `Agent`, `Task`, or control flow pattern.

### Workflow Class Structure

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/workflows/workflows.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/workflows/workflows.py) [api.md206-226](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L206-L226) [README.md774-877](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L774-L877)

The `Workflow` class accepts a list of `steps`, each of which can be:

- An Agent instance (executes with input as prompt)
- A Task instance (executes with assigned agent)
- A control flow pattern ( Route , Parallel , Loop , Repeat )
- A callable function

### Workflow Initialization Parameters

**Sources:** [README.md796-809](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L796-L809) [src/praisonai/README.md796-809](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/README.md?plain=1#L796-L809)

## Control Flow Patterns

The workflow system provides four control flow patterns as helper functions that return specialized step objects.

### Pattern Overview

```

```

**Sources:** [api.md223-226](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L223-L226) [README.md811-876](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L811-L876)

### route() - Conditional Branching

The `route()` function creates conditional execution paths based on the previous step's output.

```

```

**Execution Logic:**

1. Previous step output is analyzed (string matching or LLM classification)
2. Output is matched against route keys (case-insensitive substring matching)
3. Matched route's step list is executed
4. Falls back to "default" route if no match

**Code Entity:** `Route` class in [src/praisonai-agents/praisonaiagents/workflows/workflows.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/workflows/workflows.py)

**Sources:** [README.md817-828](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L817-L828) [src/praisonai/README.md817-828](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/README.md?plain=1#L817-L828)

### parallel() - Concurrent Execution

The `parallel()` function executes multiple steps concurrently using asyncio.

```

```

**Execution Logic:**

1. All steps are executed concurrently using asyncio.gather()
2. Results are collected in order
3. Next step receives combined results from all parallel steps

**Code Entity:** `Parallel` class in [src/praisonai-agents/praisonaiagents/workflows/workflows.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/workflows/workflows.py)

**Sources:** [README.md830-838](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L830-L838) [src/praisonai/README.md830-838](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/README.md?plain=1#L830-L838)

### loop() - Iteration Over Collections

The `loop()` function repeats a step for each item in a collection.

```

```

**Parameters:**

**Code Entity:** `Loop` class and `loop()` function in [src/praisonai-agents/praisonaiagents/workflows/workflows.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/workflows/workflows.py)

**Sources:** [README.md840-847](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L840-L847) [api.md223](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L223-L223)

### repeat() - Evaluator-Optimizer Pattern

The `repeat()` function executes a step iteratively until a condition is met (evaluator-optimizer pattern).

```

```

**Parameters:**

**Execution Logic:**

1. Execute step
2. Evaluate until() condition with current context
3. If True or max_iterations reached, stop
4. Otherwise, repeat from step 1

**Code Entity:** `Repeat` class and `repeat()` function in [src/praisonai-agents/praisonaiagents/workflows/workflows.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/workflows/workflows.py)

**Sources:** [README.md849-856](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L849-L856) [api.md225](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L225-L225)

## Workflow Context and Variables

The `WorkflowContext` object maintains execution state and enables data flow between steps.

### WorkflowContext Structure

```

```

**Sources:** [api.md18](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L18-L18)

### Variable Interpolation

Workflow variables support template interpolation using `{{variable}}` syntax:

```

```

**Sources:** [README.md879-948](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L879-L948) [README.md991-1042](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L991-L1042)

### Context Data Flow

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/workflows/workflows.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/workflows/workflows.py)

## YAML Workflow System

The workflow system supports declarative workflow definitions via YAML files, enabling no-code workflow creation.

### YAML Workflow Parser Architecture

```

```

**Sources:** [README.md950-971](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L950-L971) [api.md reference to YAMLWorkflowParser and WorkflowManager](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md reference to YAMLWorkflowParser and WorkflowManager)

### YAML Workflow Schema

```

```

**Sources:** [README.md973-1042](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L973-L1042) [src/praisonai/README.md973-1042](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/README.md?plain=1#L973-L1042)

### YAML Control Flow Patterns

#### Route Pattern in YAML

```

```

#### Parallel Pattern in YAML

```

```

#### Loop Pattern in YAML

```

```

#### Repeat Pattern in YAML

```

```

**Sources:** [README.md898-936](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L898-L936) [README.md1369-1400](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1369-L1400)

### Loading and Executing YAML Workflows

```

```

**Code Entities:**

- YAMLWorkflowParser class in src/praisonai-agents/praisonaiagents/workflows/
- WorkflowManager class in src/praisonai-agents/praisonaiagents/workflows/

**Sources:** [README.md950-971](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L950-L971) [api.md mentions of YAMLWorkflowParser and WorkflowManager](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md mentions of YAMLWorkflowParser and WorkflowManager)

## Workflow Execution Lifecycle

### Synchronous Execution Flow

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/workflows/workflows.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/workflows/workflows.py)

### Asynchronous Execution

The `Workflow` class supports asynchronous execution via `workflow.astart()`:

```

```

This enables:

- Non-blocking workflow execution
- Integration with async web frameworks
- Concurrent workflow execution

**Sources:** [README.md872](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L872-L872) [src/praisonai/README.md872](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/README.md?plain=1#L872-L872)

### Status Tracking

```

```

**Status Values:**

- workflow.status : "not_started" | "running" | "completed"
- workflow.step_statuses : Dict[str, str] mapping step names to status

**Sources:** [README.md875-876](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L875-L876) [src/praisonai/README.md875-876](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/README.md?plain=1#L875-L876)

## CLI Integration

The workflow system integrates with the PraisonAI CLI for no-code workflow execution.

### Workflow CLI Commands

**CLI Flags:**

- --workflow-var key=value : Set workflow variable
- --var key=value : Set variable (YAML workflows)
- --tools <tools> : Comma-separated tool list
- --planning : Enable planning mode
- --reasoning : Enable reasoning mode
- --memory : Enable memory
- --save : Save output to file

**Sources:** [README.md1698-1788](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1698-L1788) [src/praisonai/README.md1698-1788](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/README.md?plain=1#L1698-L1788)

### Inline Workflows

The CLI supports inline workflow definitions without YAML files:

```

```

**Sources:** [README.md1724-1728](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1724-L1728)

### Auto-Generated Workflows

The CLI can auto-generate workflows from natural language descriptions:

```

```

**Supported Patterns:**

- sequential : Linear step-by-step execution
- parallel : Concurrent execution of steps
- routing : Classifier routes to specialists
- loop : Iterate over collection
- orchestrator-workers : Central orchestrator delegates to workers
- evaluator-optimizer : Iterative refinement with quality checks

**Sources:** [README.md1749-1771](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1749-L1771) [src/praisonai/README.md1749-1771](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/README.md?plain=1#L1749-L1771)

## Integration with Agents and Tasks

### Agent as Workflow Step

When an `Agent` is used as a workflow step, the workflow calls `agent.start(input)` where `input` is:

- For first step: The workflow input data
- For subsequent steps: The previous step's result ( ctx.previous_result )

```

```

**Sources:** [README.md774-802](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L774-L802)

### Task as Workflow Step

When a `Task` is used as a workflow step, the workflow calls `agent.execute(task)`:

```

```

**Sources:** [api.md214-222](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L214-L222)

### Context Dependencies

Tasks can declare dependencies on previous steps using the `context` field in YAML:

```

```

This enables the task to access outputs from specific previous steps rather than just the immediate predecessor.

**Sources:** [README.md1030-1032](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1030-L1032)

## Advanced Features

### Workflow Checkpoints

The workflow system supports checkpointing for resumable execution:

```

```

**Sources:** [README.md1942-1956](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1942-L1956) [src/praisonai/README.md1942-1956](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/README.md?plain=1#L1942-L1956)

### Conditional Step Execution

Steps can include conditional execution logic via `when` conditions (evaluated against workflow context):

```

```

**Sources:** [api.md216](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L216-L216)

### Early Termination

Workflows can terminate early based on conditions or step results. This is achieved through:

- repeat() pattern with until condition
- Custom logic in step callbacks
- Raising exceptions in steps

**Sources:** [README.md249](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L249-L249)

### Workflow Templates

Pre-defined workflow templates are available via CLI:

```

```

**Sources:** [README.md1745-1747](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1745-L1747)

## Best Practices

### When to Use Workflows vs Process Types

### Workflow Composition Patterns

**Pattern 1: Research-Write-Review**

```

```

**Pattern 2: Classify-Route-Aggregate**

```

```

**Pattern 3: Parallel-Research-Synthesize**

```

```

**Sources:** [README.md811-856](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L811-L856)

### Performance Considerations

- Parallel execution : Use parallel() for I/O-bound steps (API calls, web searches)
- Loop optimization : Use parallel=True in loop() for independent iterations
- Context size : Large all_results can impact memory; use output_variable to store specific results
- Async execution : Use workflow.astart() for non-blocking execution in async applications

**Sources:** [api.md223](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L223-L223)

## Related Systems

- Process Strategies : High-level multi-agent process types (sequential, hierarchical, parallel)
- Planning System : AI-driven dynamic plan generation and execution
- Multi-Agent Orchestration : AgentTeam coordination and state management
- Task System : Task definition, execution, and lifecycle management
