Agent Reflection

Enable agents to evaluate and improve their own responses through self-reflection

Reflection enables agents to critically evaluate their outputs and iteratively improve them before delivering the final response.

Quick Start

1. Enable Reflection

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Reflective Agent",
       instructions="You write high-quality content",
       reflection=True  # Enable self-reflection
   )
   
   agent.start("Write a compelling product description")
   
2. With Configuration

   from praisonaiagents import Agent, ReflectionConfig
   
   agent = Agent(
       name="Quality Agent",
       instructions="You produce accurate, well-researched content",
       reflection=ReflectionConfig(
           min_iterations=1,    # Minimum reflection cycles
           max_iterations=3,    # Maximum reflection cycles
           llm="gpt-4o",        # Model for reflection
       )
   )
   

---

How Reflection Works

Streaming behaviour: Reflection regeneration always runs non-streaming, even when stream=True on the agent. The final answer still streams normally. This keeps AgentTeam and sync LLM adapters reliable during regeneration passes.

The Reflection Process

Phase	What Happens	Purpose
Generate	Create initial response	First attempt
Evaluate	Assess quality, accuracy, completeness	Find issues
Improve	Refine based on feedback	Better output
Repeat	Continue until satisfactory or max iterations	Quality assurance

---

Configuration Options

from praisonaiagents import ReflectionConfig

config = ReflectionConfig(
    min_iterations=1,     # Minimum reflection cycles
    max_iterations=3,     # Maximum reflection cycles
    llm="gpt-4o",         # LLM for reflection (optional)
    prompt="Evaluate...", # Custom reflection prompt (optional)
)

Option	Type	Default	Description
min_iterations	int	1	Minimum reflection cycles
max_iterations	int	3	Maximum reflection cycles
llm	str	None	LLM for reflection (uses agent’s LLM if not set)
prompt	str	None	Custom reflection prompt

---

Reflection Depth

Light Reflection

# Single pass - quick check
agent = Agent(
    instructions="You answer questions",
    reflection=ReflectionConfig(
        min_iterations=1,
        max_iterations=1,
    )
)

Standard Reflection

# Default - good balance
agent = Agent(
    instructions="You write articles",
    reflection=True  # Uses defaults: min=1, max=3
)

Thorough Reflection

# Deep reflection for critical content
agent = Agent(
    instructions="You write legal documents",
    reflection=ReflectionConfig(
        min_iterations=2,
        max_iterations=5,
        llm="gpt-4o",  # Use powerful model
    )
)

---

Custom Reflection Prompts

Customize what the agent evaluates:

agent = Agent(
    instructions="You write technical documentation",
    reflection=ReflectionConfig(
        prompt="""Evaluate this response for:
1. Technical accuracy - Are all facts correct?
2. Completeness - Is anything missing?
3. Clarity - Is it easy to understand?
4. Code examples - Are they correct and runnable?

If any issues found, provide specific improvements."""
    )
)

---

When to Use Reflection

✅ Use Reflection For

• Content writing
• Code generation
• Technical documentation
• Research summaries
• Customer-facing content

❌ Skip Reflection For

• Real-time chat
• Simple lookups
• Time-critical responses
• Trivial questions

---

Reflection vs Planning

Aspect	Planning	Reflection
When	Before execution	After generation
Purpose	Decompose task	Improve output
Focus	Strategy	Quality
Iterations	Once	Multiple

---

Best Practices

Set appropriate iteration limits

More iterations = better quality but slower. Use max_iterations=3 for most tasks, increase for critical content.

Use custom prompts for domain-specific evaluation

Generic reflection may miss domain-specific issues. Customize the prompt for your use case.

Combine with planning for complex tasks

Use planning to break down the task, then reflection to ensure quality output.

Can I combine reflection=True with stream=True?

Yes. Only the intermediate reflection passes are forced to non-streaming; the framework handles this for you and the final response still streams when stream=True.

---

Related

Planning

Think before acting

Guardrails

Validate outputs