Skip to main content
Enable reflection=True on an agent and it critiques its own answer before returning — improving quality within the same task.
The user asks a question; the agent drafts an answer, reflects on quality, then returns the improved response.

​
Quick Start

1

Simple Usage

2

With Configuration

​
How It Works

After each response, the agent runs one or more reflection passes (between min_iterations and max_iterations). Each pass asks whether the answer meets quality criteria; if not, the agent revises before returning. If a reflection response cannot be parsed (for example, an OpenAI structured-output refusal, a content-filter block, or a truncation), the agent retries that pass. Retries are bounded by max_iterations — after that many failed passes, the agent returns the current draft un-reflected instead of continuing to retry.

​
Troubleshooting

Persistent parse failures terminate cleanly at max_iterations instead of looping forever.
When the reflection LLM keeps returning an unparseable response (a structured-output refusal, a content-filter block, or a finish_reason="length" truncation), the agent stops after max_iterations failed passes and returns the current draft un-reflected.With verbose=True, look for this log line on the terminating pass:Maximum reflection count reached after repeated parse errors, returning current responseIf you see it often:
  • Lower max_iterations to fail fast.
  • Switch the reflection LLM with ReflectionConfig(llm=...) to one less prone to refusals.
  • Narrow the prompt so the reflection response fits the required JSON shape.
If a guardrail is configured and its validation raises on that draft, chat() returns None and the chat history is rolled back to the pre-turn state.

​
Configuration Options

ReflectionConfig SDK Reference

Full parameter reference for ReflectionConfig
Precedence ladder — choose the level you need:

​
Choosing Reflection Strength

​
Best Practices

Reflection adds an extra LLM pass per turn. Set reflection=False on agents that call tools frequently to keep latency down.
Use ReflectionConfig(llm="gpt-4o") when the main model is fast but you want a stronger critic.
reflection improves this answer within the task. self_improve captures reusable skills for next time — they compose independently.
Cap max_iterations in production to avoid runaway loops on open-ended prompts. It also bounds parse-error retries — if the reflection LLM keeps returning an unparseable response, the agent stops after max_iterations failed passes and returns the current draft un-reflected.

Self Improve

Capture reusable skills after each task

Guardrails

Validate agent outputs with policies

Planning Mode

Let agents plan before acting

Execution Systems

Configure agent execution limits