<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/3.4-reflection-system -->

# Reflection System

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

The Reflection System provides self-assessment capabilities for AI agents, allowing them to evaluate and iteratively improve their outputs before finalizing task results. The system implements quality-driven iteration where agents analyze their work against task requirements and reflection criteria, then attempt to enhance outputs that fall below quality thresholds.

For information about task execution control, see [Process Strategies](/MervinPraison/PraisonAI/3.2-process-strategies). For agent-level safety validation, see [Guardrails](/MervinPraison/PraisonAI/6.1-guardrails). For long-term quality tracking, see [Memory Management](/MervinPraison/PraisonAI/4.1-memory-management).

## Overview

The Reflection System operates as a post-execution evaluation layer that intercepts agent outputs, evaluates them against quality criteria, and triggers re-generation when outputs are insufficient. Unlike guardrails which enforce hard constraints, reflection focuses on iterative quality improvement through self-critique.

### Key Components

Sources: [praisonaiagents/agents/agents.py193](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/agents/agents.py#L193-L193) [praisonaiagents/agents/autoagents.py81](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/agents/autoagents.py#L81-L81) [praisonaiagents/memory/memory.py501-534](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/memory/memory.py#L501-L534)

## Reflection Configuration

### Consolidated Reflection Parameter

The reflection system uses a unified parameter that accepts multiple input formats with precedence-based resolution:

```
reflection: Union[bool, str, dict, list, ReflectionConfig]
```

**Precedence Order:**

1. ReflectionConfig instance (highest)
2. Dictionary with reflection config
3. List: [preset_name, overrides_dict]
4. String: LLM model name or preset name
5. Boolean: True enables with defaults, False disables

**Configuration Diagram**

```

```

Sources: [praisonaiagents/agents/agents.py193](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/agents/agents.py#L193-L193) [praisonaiagents/agents/autoagents.py81](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/agents/autoagents.py#L81-L81) [praisonaiagents/config/param_resolver.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/config/param_resolver.py)

### Legacy Parameters (Deprecated)

The following parameters are maintained for backward compatibility but superseded by the `reflection` parameter:

When both consolidated and legacy parameters are provided, the consolidated `reflection` parameter takes precedence.

Sources: [praisonaiagents/agents/autoagents.py52-72](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/agents/autoagents.py#L52-L72)

## Reflection Levels

The Reflection System supports three predefined quality levels that configure iteration depth and evaluation rigor:

### Minimal Reflection

**Configuration:**

```

```

**Characteristics:**

- max_reflect : 1 iteration
- min_reflect : 0 (optional)
- threshold : 0.5 (50% quality score)
- criteria : Basic output requirements

**Use Case:** Fast execution where basic quality checks suffice. Suitable for non-critical tasks or when compute budget is limited.

### Standard Reflection (Default)

**Configuration:**

```

```

**Characteristics:**

- max_reflect : 3 iterations
- min_reflect : 1 (always attempts once)
- threshold : 0.7 (70% quality score)
- criteria : Comprehensive evaluation of completeness, relevance, clarity

**Use Case:** General-purpose tasks requiring reliable output quality. Balances quality and performance.

### Thorough Reflection

**Configuration:**

```

```

**Characteristics:**

- max_reflect : 5 iterations
- min_reflect : 2 (always attempts at least twice)
- threshold : 0.85 (85% quality score)
- criteria : Strict evaluation including factual accuracy verification

**Use Case:** Critical tasks where output quality is paramount. Suitable for research, analysis, and decision-making tasks.

Sources: [praisonaiagents/config/presets.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/config/presets.py)

## Quality Evaluation

### Quality Metrics Calculation

The reflection system evaluates outputs across four dimensions using LLM-based assessment:

**Quality Dimensions:**

```

```

**Default Weights:**

- Completeness: 25%
- Relevance: 25%
- Clarity: 25%
- Accuracy: 25%

**Implementation:**

The `calculate_quality_metrics` method in `Memory` class performs LLM-based evaluation:

```
LLM Prompt Template:
  Task: {task_description}
  Output: {agent_output}
  
  Evaluate on scale 0.0-1.0:
  1. Completeness: Does it address all requirements?
  2. Relevance: Is it aligned with the task?
  3. Clarity: Is it well-structured and clear?
  4. Accuracy: Is it factually correct?
```

The LLM returns structured scores which are combined using the weighted formula:

```
quality_score = (completeness x 0.25) + (relevance x 0.25) + 
                (clarity x 0.25) + (accuracy x 0.25)
```

Sources: [praisonaiagents/memory/memory.py501-534](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/memory/memory.py#L501-L534) [praisonaiagents/memory/memory.py1040-1200](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/memory/memory.py#L1040-L1200)

## Reflection Workflow

### Execution Flow

```

```

Sources: [praisonaiagents/agents/agents.py591-717](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/agents/agents.py#L591-L717) [praisonaiagents/memory/memory.py315-386](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/memory/memory.py#L315-L386) [praisonaiagents/task/task.py257-386](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/task/task.py#L257-L386)

### Reflection Feedback Loop

The reflection system builds iterative context by providing critiques from previous attempts:

**Iteration N Context:**

```
Previous attempt (Iteration N-1):
  Output: {previous_output}
  Quality Score: {score}
  Critique:
    - Completeness: {completeness_feedback}
    - Relevance: {relevance_feedback}
    - Clarity: {clarity_feedback}
    - Accuracy: {accuracy_feedback}

Please improve the output addressing these specific issues.
```

**Stopping Conditions:**

1. Quality score meets or exceeds threshold
2. Maximum reflection attempts reached ( max_reflect )
3. No quality improvement detected across iterations
4. Agent explicitly signals completion

Sources: [praisonaiagents/memory/memory.py1040-1200](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/memory/memory.py#L1040-L1200) [praisonaiagents/process/process.py147-202](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/process/process.py#L147-L202)

## Integration with Agent System

### Multi-Agent Reflection Propagation

```

```

The `Agents` class stores the reflection configuration and propagates it to all contained agents:

**Propagation Flow:**

1. Agents.__init__ receives reflection parameter
2. Stores as self._reflection for later propagation
3. When agents execute tasks, reflection config is applied
4. Each agent inherits parent's reflection settings unless overridden

Sources: [praisonaiagents/agents/agents.py193](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/agents/agents.py#L193-L193) [praisonaiagents/agents/agents.py223](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/agents/agents.py#L223-L223) [praisonaiagents/agents/autoagents.py163](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/agents/autoagents.py#L163-L163)

### AutoAgents Reflection

The `AutoAgents` class extends reflection to automatically generated agents:

**AutoAgent Reflection Application:**

```
AutoAgents(
    instructions="...",
    reflection="standard",  # Applied to all generated agents
    max_agents=3
)
```

Each auto-generated agent inherits the reflection configuration:

Sources: [praisonaiagents/agents/autoagents.py42-168](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/agents/autoagents.py#L42-L168) [praisonaiagents/agents/autoagents.py452-511](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/agents/autoagents.py#L452-L511)

## Reflection vs. Guardrails

The Reflection System and Guardrails serve complementary quality assurance roles:

**Combined Usage Example:**

```

```

**Execution Order:**

1. Agent generates initial output
2. Guardrails validate for safety (fail fast)
3. Reflection evaluates quality
4. If below threshold, reflection triggers re-generation
5. Re-generated output goes through guardrails again
6. Process repeats until quality threshold or max attempts

Sources: [praisonaiagents/task/task.py161-214](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/task/task.py#L161-L214) [praisonaiagents/guardrails/llm_guardrail.py14-130](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/guardrails/llm_guardrail.py#L14-L130) [examples/guardrail_example_fixed.py11-142](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/examples/guardrail_example_fixed.py#L11-L142)

## Configuration Examples

### Example 1: Boolean Activation

```

```

**Result:** Standard reflection with 3 max attempts, 0.7 threshold

### Example 2: Custom LLM Model

```

```

**Result:** Standard reflection using GPT-4 for quality assessment

### Example 3: Dictionary Configuration

```

```

**Result:** Custom reflection with Claude Opus, high quality bar, specific criteria

### Example 4: List with Preset Override

```

```

**Result:** Thorough preset with increased max attempts from 5 to 7

### Example 5: ReflectionConfig Instance

```

```

**Result:** Full control over all reflection parameters

Sources: [praisonaiagents/agents/agents.py193](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/agents/agents.py#L193-L193) [praisonaiagents/agents/autoagents.py81](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/agents/autoagents.py#L81-L81)

## Reflection with Memory Integration

### Quality Score Storage

The reflection system integrates with the Memory system to persist quality metrics:

```

```

**Storage Thresholds:**

- Short-term memory : All outputs (quality_score >= 0.0)
- Long-term memory : High-quality outputs only (quality_score >= 0.7)
- Quality metrics DB : All attempts with full metric breakdown

**Query Capabilities:**

```

```

Sources: [praisonaiagents/memory/memory.py539-596](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/memory/memory.py#L539-L596) [praisonaiagents/memory/memory.py745-834](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/memory/memory.py#L745-L834) [praisonaiagents/task/task.py315-386](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/task/task.py#L315-L386)

## Performance Considerations

### Computational Cost

Reflection introduces additional LLM calls proportional to iteration attempts:

**Cost Formula:**

```
Total LLM Calls = 1 (initial) + N (reflections) + N (evaluations)
                = 1 + 2N

where N = actual reflection iterations (1 to max_reflect)
```

**Example Costs:**

- Minimal (max=1): 1 + 2(1) = 3 LLM calls
- Standard (max=3, avg=2): 1 + 2(2) = 5 LLM calls
- Thorough (max=5, avg=3): 1 + 2(3) = 7 LLM calls

### Optimization Strategies

**Example: Fast Reflection Configuration**

```

```

Sources: [praisonaiagents/memory/memory.py1040-1200](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/memory/memory.py#L1040-L1200) [praisonaiagents/llm/llm.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/llm/llm.py)

## Error Handling

### Reflection Failure Scenarios

**Exception Handling Flow:**

```

```

Sources: [praisonaiagents/memory/memory.py1040-1200](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/memory/memory.py#L1040-L1200) [praisonaiagents/task/task.py257-386](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents/task/task.py#L257-L386)
