Reflection

Let agents critique and improve their own responses before delivering them

Reflection makes agents review and refine their own answers, catching mistakes and improving quality automatically.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a precise technical writer.",
    reflection=True,
)

agent.start("Explain how TCP/IP handshakes work.")

The user asks a question; the agent drafts, self-reviews, and refines before returning the final answer.

Quick Start

1. Level 1 — Bool (simplest)

   Turn on self-review with a single flag.

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Writer",
       instructions="You are a technical writer.",
       reflection=True,
   )
   agent.start("Write clear documentation for a REST API authentication flow.")
   
2. Level 2 — Config class (tune iterations and LLM)

   Use ReflectionConfig to control how many review passes run and which LLM critiques.

   from praisonaiagents import Agent, ReflectionConfig
   
   agent = Agent(
       name="Writer",
       instructions="You are a technical writer.",
       reflection=ReflectionConfig(
           min_iterations=1,
           max_iterations=3,
           llm="gpt-4o",
       ),
   )
   agent.start("Write a detailed security review of OAuth 2.0.")
   
3. Level 3 — Config with a custom review prompt

   Pass a domain-specific prompt to steer what the self-review checks for.

   from praisonaiagents import Agent, ReflectionConfig
   
   agent = Agent(
       name="Reviewer",
       instructions="You are a code reviewer.",
       reflection=ReflectionConfig(
           max_iterations=2,
           prompt="Evaluate your response for: accuracy, completeness, and clarity. Improve if needed.",
       ),
   )
   agent.start("Review this Python function for bugs and performance issues.")
   

---

How It Works

Phase	What happens
1. Draft	Agent generates initial response
2. Evaluate	Reflection checks quality against criteria
3. Improve	Agent rewrites based on self-critique
4. Deliver	Final polished response returned to user

---

Configuration Options

Full list of options, types, and defaults — ReflectionConfig

Option	Type	Default	Description
min_iterations	int	1	Minimum reflection passes (always runs at least once)
max_iterations	int	3	Maximum reflection passes
llm	str | None	None	LLM for reflection (defaults to agent’s LLM)
prompt	str | None	None	Custom reflection evaluation prompt

---

Common Patterns

Pattern 1 — Quality-focused writing

from praisonaiagents import Agent, ReflectionConfig

agent = Agent(
    instructions="You are a professional copywriter.",
    reflection=ReflectionConfig(min_iterations=2, max_iterations=3),
)
response = agent.start("Write an engaging product description for a smart home speaker.")
print(response)

Pattern 2 — Factual accuracy check

from praisonaiagents import Agent, ReflectionConfig

agent = Agent(
    instructions="You are a fact-checking assistant.",
    reflection=ReflectionConfig(
        max_iterations=2,
        prompt="Check for factual inaccuracies, missing context, or ambiguous statements.",
    ),
)
agent.start("Summarize the key events of the Apollo 11 mission.")

---

Best Practices

When to use reflection

Enable reflection for writing tasks, technical explanations, and any output where quality matters more than speed. Skip it for simple lookups, calculations, or real-time applications.

Set max_iterations to control cost

Each reflection pass costs an additional LLM call. Set max_iterations=1 for light review, 2 for thorough review, and only go to 3 for high-stakes content. The default is 3.

Use a custom prompt for domain-specific review

Default reflection uses general quality criteria. Pass a prompt tailored to your domain — e.g., “Check for HIPAA compliance language” for medical agents or “Verify all code is PEP 8 compliant” for coding agents.

---

Related

Planning — plan before acting on complex requests

Self-Reflection Deep Dive — advanced reflection patterns