agents.reflection.structured_output

Structured output reflection agents and examples.

This module provides reflection agents that use structured output models combined with a post-processing hook pattern for extracting results.

Classes

ReflectionLoop	Manages iterative reflection and improvement process.
StructuredImprovementAgent	Agent that improves responses based on reflection feedback.
StructuredReflectionAgent	Agent that performs reflection with structured output extraction.

Functions

create_improvement_agent([name, temperature])	Create a structured improvement agent.
create_reflection_agent([name, temperature])	Create a structured reflection agent.
create_reflection_loop([max_iterations, ...])	Create a complete reflection loop system.
example_basic_reflection()	Example: Basic response reflection with structured analysis.
example_iterative_reflection()	Example: Iterative reflection until quality threshold is met.
example_reflection_with_improvement()	Example: Full reflection loop with improvement.
extract_structured_output(agent_result, model_class)	Generic post-processing hook to extract structured output from agent results.
main()	Run all structured reflection examples.

Module Contents

class agents.reflection.structured_output.ReflectionLoop(reflector, improver, max_iterations=3, quality_threshold=0.8)

Manages iterative reflection and improvement process.

Initialize the reflection loop.

Parameters:

• reflector (StructuredReflectionAgent) – The reflection agent

• improver (StructuredImprovementAgent) – The improvement agent

• max_iterations (int) – Maximum iterations before stopping

• quality_threshold (float) – Quality score to stop iterating

async iterate(query, initial_response)

Run iterative reflection and improvement.

Parameters:

• query (str) – The original query

• initial_response (str) – Starting response to improve

Returns:

Dictionary with final response, iterations, and quality progression

Return type:

dict[str, Any]

class agents.reflection.structured_output.StructuredImprovementAgent(name='improvement_agent', temperature=0.5)

Agent that improves responses based on reflection feedback.

Initialize the improvement agent.

Parameters:

• name (str) – Name for the agent

• temperature (float) – Temperature for LLM generation

async improve(query, response, reflection)

Improve a response based on reflection feedback.

Parameters:

• query (str) – The original query

• response (str) – The response to improve

• reflection (agents.reflection.models.ReflectionResult) – The reflection analysis

Returns:

Improved response text

Return type:

str

class agents.reflection.structured_output.StructuredReflectionAgent(name='reflection_agent', system_prompt=None, temperature=0.3)

Agent that performs reflection with structured output extraction.

Initialize the structured reflection agent.

Parameters:

• name (str) – Name for the agent

• system_prompt (str | None) – Custom system prompt (optional)

• temperature (float) – Temperature for LLM generation

async reflect(query, response)

Perform reflection analysis on a response.

Parameters:

• query (str) – The original query

• response (str) – The response to analyze

Returns:

ReflectionResult with structured analysis, or None if extraction fails

Return type:

agents.reflection.models.ReflectionResult | None

agents.reflection.structured_output.create_improvement_agent(name='improver', temperature=0.5, **kwargs)

Create a structured improvement agent.

Parameters:

• name (str)

• temperature (float)

Return type:

StructuredImprovementAgent

agents.reflection.structured_output.create_reflection_agent(name='reflector', temperature=0.3, **kwargs)

Create a structured reflection agent.

Parameters:

• name (str)

• temperature (float)

Return type:

StructuredReflectionAgent

agents.reflection.structured_output.create_reflection_loop(max_iterations=3, quality_threshold=0.8, reflector_name='reflector', improver_name='improver')

Create a complete reflection loop system.

Parameters:

• max_iterations (int)

• quality_threshold (float)

• reflector_name (str)

• improver_name (str)

Return type:

ReflectionLoop

async agents.reflection.structured_output.example_basic_reflection()

Example: Basic response reflection with structured analysis.

async agents.reflection.structured_output.example_iterative_reflection()

Example: Iterative reflection until quality threshold is met.

async agents.reflection.structured_output.example_reflection_with_improvement()

Example: Full reflection loop with improvement.

agents.reflection.structured_output.extract_structured_output(agent_result, model_class)

Generic post-processing hook to extract structured output from agent results.

Parameters:

• agent_result (dict[str, Any]) – The dict returned by agent.arun()

• model_class (type[T]) – The Pydantic model class to extract

Returns:

Instance of the model class, or None if not found

Return type:

T | None

async agents.reflection.structured_output.main()

Run all structured reflection examples.