<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/8-configuration-system -->

# Configuration System

- src/praisonai-agents/praisonaiagents/__init__.py
- src/praisonai-agents/praisonaiagents/agent/agent.py
- src/praisonai-agents/praisonaiagents/llm/llm.py

The Configuration System provides a unified, type-safe approach to configuring agents and their features. It handles parameter resolution, preset management, environment variable integration, and config file loading. The system enables flexible configuration through multiple input formats (bool, string, dict, config objects) while maintaining backward compatibility and performance.

For information about specific feature configurations (memory, knowledge, planning, etc.), see [Consolidated Parameters](/MervinPraison/PraisonAI/8.1-consolidated-parameters). For preset definitions and defaults, see [Presets and Defaults](/MervinPraison/PraisonAI/8.2-presets-and-defaults). For environment variable control, see [Environment Variables](/MervinPraison/PraisonAI/8.3-environment-variables).

## Architecture Overview

The configuration system consists of four main layers: presets (named configurations), config classes (typed configuration objects), resolution logic (parameter normalization), and defaults (file-based and environment-based).

**Configuration System Architecture**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agent/agent.py125-136](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L125-L136) [src/praisonai-agents/praisonaiagents/config/param_resolver.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/config/param_resolver.py) [src/praisonai-agents/praisonaiagents/config/presets.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/config/presets.py) [src/praisonai-agents/praisonaiagents/config/feature_configs.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/config/feature_configs.py)

## Configuration Resolution System

The `resolve()` function provides unified parameter resolution, converting diverse input types into standardized config objects. It handles bool, string (preset names), dict, config objects, and pre-configured instances.

### Resolution Priority

The resolver follows this precedence chain:

1. Instance passthrough - Pre-configured objects (e.g., Memory instance, Knowledge instance)
2. Config object - Typed config classes (e.g., OutputConfig , MemoryConfig )
3. Dict - Configuration dictionaries converted to config objects
4. String - Preset names or special strings (URLs, paths, model names)
5. Bool - True uses defaults, False disables feature
6. Array - Lists processed based on ArrayMode strategy
7. Default - Fallback when value is None

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

### The resolve() Function

Located in [src/praisonai-agents/praisonaiagents/config/param_resolver.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/config/param_resolver.py) the `resolve()` function signature:

```

```

Key parameters:

- value - Input to resolve (any type)
- config_class - Target config class (e.g., OutputConfig )
- presets - Preset dictionary for string lookups
- url_schemes - URL schemes for database URLs (e.g., {"sqlite://", "postgresql://"} )
- instance_check - Function to detect pre-configured instances
- array_mode - Strategy for handling list inputs
- string_mode - Special string interpretation (e.g., "llm_model" , "path_as_source" )
- default - Fallback value when input is None

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

### ArrayMode Strategies

The `ArrayMode` enum defines how lists are processed:

Example resolution with `ArrayMode.SOURCES`:

```

```

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

### Fast Path Optimization

The Agent class implements fast path optimization for common configuration patterns to minimize overhead. This avoids calling `resolve()` for typical cases.

**Fast Path Decision Tree**

```

```

Fast path implementation examples from [src/praisonai-agents/praisonaiagents/agent/agent.py619-900](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L619-L900):

**OUTPUT Fast Path:**

```

```

**EXECUTION Fast Path:**

```

```

**MEMORY Fast Path:**

```

```

This optimization reduces parameter resolution overhead from ~10-20ms to <1ms for common patterns (silent mode, default execution, no memory).

**Sources:** [src/praisonai-agents/praisonaiagents/agent/agent.py619-900](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L619-L900)

## Preset System

Presets provide named configurations for common use cases. Each preset is a dictionary that maps to config class fields.

### Preset Dictionaries

Located in [src/praisonai-agents/praisonaiagents/config/presets.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/config/presets.py):

#### OUTPUT_PRESETS

Controls agent output verbosity and format:

Default: `"silent"` (can be overridden via `PRAISONAI_OUTPUT` env var)

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

#### EXECUTION_PRESETS

Controls execution limits and timing:

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

#### MEMORY_PRESETS

Controls memory backend and features:

URL schemes supported: `{"sqlite://", "postgresql://", "mysql://", "mem0://", "supabase://"}`

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

#### PLANNING_PRESETS

Controls planning behavior:

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

#### REFLECTION_PRESETS

Controls self-reflection iterations:

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

#### WEB_PRESETS

Controls web search and fetch:

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

#### CACHING_PRESETS

Controls prompt caching:

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

#### CONTEXT_PRESETS

Controls context management:

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

### Preset Usage

Presets work with all input methods:

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agent/agent.py619-900](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L619-L900) [src/praisonai-agents/praisonaiagents/config/presets.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/config/presets.py)

## Feature Config Classes

Feature config classes provide type-safe configuration with validation. All classes are Pydantic models located in [src/praisonai-agents/praisonaiagents/config/feature_configs.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/config/feature_configs.py)

### Core Config Classes

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

### Config Class Usage

Config classes support multiple input patterns:

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/config/feature_configs.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/config/feature_configs.py) [src/praisonai-agents/praisonaiagents/agent/agent.py399-523](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L399-L523)

### Enum Types

Config classes use enums for validation:

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

## Environment Variables

Environment variables provide global defaults and runtime control. They're cached at the class level for performance.

### Core Environment Variables

**Sources:** [src/praisonai-agents/praisonaiagents/agent/agent.py188-216](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L188-L216) [src/praisonai-agents/praisonaiagents/llm/llm.py355-356](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/llm/llm.py#L355-L356)

### Environment Variable Resolution

Environment variables are resolved with caching for performance:

```

```

This caching reduces repeated environment lookups from O(n) per agent to O(1) amortized.

**Sources:** [src/praisonai-agents/praisonaiagents/agent/agent.py158-201](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L158-L201)

## Config File Loading

Config files provide project-level and user-level defaults. The system searches for config files in multiple locations.

### Config File Locations

Search order (first found wins):

1. ./praisonai.yaml - Project-local config
2. ./praisonai.yml - Project-local config (alt)
3. $PRAISONAI_CONFIG_DIR/config.yaml - User config
4. ~/.praison/config.yaml - User config (default)

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

### Config File Structure

Example `praisonai.yaml`:

```

```

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

### Config Loading Functions

Located in [src/praisonai-agents/praisonaiagents/config/loader.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/config/loader.py):

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

### Config-Driven Defaults in Agent

Config file defaults are applied before parameter resolution in [src/praisonai-agents/praisonaiagents/agent/agent.py544-586](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L544-L586):

```

```

This ensures precedence: **Explicit params > Config file > Built-in defaults**

**Sources:** [src/praisonai-agents/praisonaiagents/agent/agent.py544-586](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L544-L586)

## Parameter Resolution Flow

The complete parameter resolution flow shows how inputs are transformed into runtime values.

**Parameter Resolution Flow (output= example)**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agent/agent.py544-704](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L544-L704) [src/praisonai-agents/praisonaiagents/config/param_resolver.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/config/param_resolver.py)

## Configuration Examples

### Example 1: Simple Agent with Presets

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agent/agent.py399-523](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L399-L523)

### Example 2: Config Objects for Type Safety

```

```

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

### Example 3: Preset Override with Array

```

```

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

### Example 4: Environment Variable Control

```

```

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agent/agent.py188-201](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L188-L201)

### Example 5: Config File Defaults

Create `praisonai.yaml`:

```

```

```

```

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

### Example 6: Database URL for Memory

```

```

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

### Example 7: File Path for Output

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agent/agent.py96-119](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L96-L119)

## Performance Considerations

### Caching Strategies

The configuration system uses multiple caching layers:

1. Class-level env var cache - agent.py 158-201 - Environment variables cached at class level
2. Module-level preset cache - presets.py - Preset dictionaries are module constants
3. Instance-level formatted tools cache - agent.py 1361-1363 - Tool definitions cached per agent

### Fast Path Impact

Fast path optimization reduces parameter resolution overhead:

Total agent initialization time with fast paths: ~20ms (down from ~420ms without optimization)

**Sources:** [src/praisonai-agents/praisonaiagents/agent/agent.py12-13](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L12-L13)

### Lazy Loading

Configuration system components use lazy loading:

- Rich console - Only imported when output=verbose agent.py 24-38
- Display functions - Only imported when needed agent.py 51-75
- LLM module - Only imported when using LiteLLM backend agent.py 40-49

This keeps import time under 20ms for silent mode.

**Sources:** [src/praisonai-agents/praisonaiagents/agent/agent.py12-95](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L12-L95)
