Async Self-Reflection

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

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())

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.

Async Agents

Complete guide to async agent execution

Self-Reflection Concepts

Core concepts and architecture

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Async Self-Reflection

Quick Start

How It Works

Feature Parity

Configuration Options

Best Practices

Async Agents

Self-Reflection Concepts

​Quick Start

​How It Works

​Feature Parity

​Configuration Options

​Best Practices

​Related

Async Agents

Self-Reflection Concepts

Quick Start

How It Works

Feature Parity

Configuration Options

Best Practices

Related