Async Self-Reflection

Self-reflection now works in async agents using the unified dispatch path

Self-reflection enables agents to evaluate and improve their responses in async execution, bringing full feature parity with sync agents.

import asyncio
from praisonaiagents import Agent

agent = Agent(
    name="Writer",
    instructions="Write concise product blurbs.",
    self_reflect=True,
    min_reflect=1,
    max_reflect=3,
)

async def main():
    await agent.achat("Write a one-line blurb for a smart mug.")

asyncio.run(main())

The user asks for copy; the agent drafts, self-reflects, and improves the answer before replying.

Quick Start

1. Basic Async Reflection

   Enable reflection in async agents with simple boolean flag:

   import asyncio
   from praisonaiagents import Agent
   
   agent = Agent(
       name="Writer",
       instructions="Write concise product blurbs.",
       self_reflect=True,
       min_reflect=1,
       max_reflect=3,
   )
   
   async def main():
       result = await agent.achat("Write a one-line blurb for a smart mug.")
       print(result)
   
   asyncio.run(main())
   
2. Custom Reflection Criteria

   Configure reflection with custom criteria for async agents:

   import asyncio
   from praisonaiagents import Agent, ReflectionConfig
   
   agent = Agent(
       name="Technical Writer",
       instructions="Create technical documentation.",
       self_reflect=ReflectionConfig(
           min_reflect=2,
           max_reflect=5,
           criteria="Is the response clear, accurate, and complete?"
       )
   )
   
   async def main():
       result = await agent.achat("Explain async/await in Python.")
       print(result)
   
   asyncio.run(main())
   

---

How It Works

Self-reflection in async agents follows the same process as sync agents:

Component	Purpose	Async Behavior
Initial Generation	Create first response	Uses await agent.achat()
Self-Evaluation	Judge response quality	Async LLM call for evaluation
Iterative Improvement	Refine based on feedback	Multiple async iterations
Final Output	Deliver best response	Returns when criteria met

---

Feature Parity

Prior to PR #1704, async agents had limited reflection support:

Before PR #1704: Only legacy custom-LLM async branch supported reflection; the default OpenAI async path skipped it entirely.

After PR #1704: Self-reflection works uniformly in both sync and async agents on all execution paths, including the default unified-dispatch path.

Feature	Sync Agents	Async Agents (Before #1704)	Async Agents (After #1704)
Self-reflection	✅ Full support	❌ Limited/bypassed	✅ Full parity
Custom criteria	✅ Supported	❌ Not available	✅ Supported
Min/max reflect	✅ Configurable	❌ Not configurable	✅ Configurable
Unified dispatch	✅ Works	❌ Bypassed reflection	✅ Full support

Parse-error parity (PR #4253): The async path always bounded parse-error retries at max_reflect. The sync path did not — a reflection response that persistently failed to parse (a structured-output refusal, a content-filter block, or a truncation) looped forever. PR #4253 closes that gap: sync now terminates at max_reflect on parse errors, like async, and returns the un-reflected answer.

This is termination parity, not call-count parity — the sync loop still issues one extra primary completion per reflection round, so sync and async do not cost the same under a persistent-refusal scenario.

---

Configuration Options

All reflection configuration options work identically in async agents:

Option	Type	Default	Description
self_reflect	bool	False	Enable/disable self-reflection
min_reflect	int	1	Minimum reflection iterations
max_reflect	int	3	Maximum reflection iterations
criteria	str	Auto-generated	Custom evaluation criteria

---

Best Practices

Choose Appropriate Limits

Set reasonable min_reflect and max_reflect values to balance quality with performance. Async reflection still involves multiple LLM calls.

Custom Criteria

Provide specific evaluation criteria for better reflection quality. Generic criteria like “Is this good?” are less effective than specific requirements.

Monitor Performance

Reflection increases response time and token usage. Monitor these metrics in production async applications.

Error Handling

Wrap async reflection calls in try-catch blocks to handle potential timeout or API errors gracefully.

---

Related

Async Agents

Complete guide to async agent execution

Self-Reflection Concepts

Core concepts and architecture