agents.reflection.message_transformer¶

Reflection patterns using Message Transformer V2.

This module implements reflection patterns that integrate with the message transformation system, following the patterns described in: - project_docs/active/patterns/reflection_agent_pattern.md (lines 565-594) - packages/haive-core/src/haive/core/graph/node/message_transformation_v2.py

Key difference from structured output: This uses message transformation to add reflection context to conversations, enabling more natural reflection flows.

Classes¶

`ConversationalReflectionAgent`	Reflection agent that maintains conversational flow with reflection context.
`MessageTransformerReflectionAgent`	Reflection agent using message transformer v2 pattern.
`ReflectionMessageFlow`	Manages reflection flow using message transformations.
`SimpleReflectionTransformer`	Simple reflection transformer for when message_transformation_v2 is not available.

Functions¶

`create_conversational_reflection_agent`(base_agent[, ...])	Create a conversational reflection agent.
`create_message_transformer_reflection_agent`([name, ...])	Create a message transformer reflection agent.
`create_reflection_context_transformer`(messages)	Create a reflection context transformer function.
`create_reflection_message_flow`(primary_agent[, ...])	Create a reflection message flow system.
`example_conversational_reflection`()	Example: Conversational reflection with context injection.
`example_message_transformer_reflection`()	Example: Reflection using message transformer patterns.
`example_reflection_message_flow`()	Example: Complete reflection message flow system.
`main`()	Run all message transformer reflection examples.

Module Contents¶

class agents.reflection.message_transformer.ConversationalReflectionAgent(base_agent, name='conversational_reflection', reflection_frequency=3)¶

Reflection agent that maintains conversational flow with reflection context.

This integrates message transformation to create natural reflection patterns within conversations, rather than separate analysis steps.

Initialize conversational reflection agent.

Parameters:

base_agent (haive.agents.simple.agent.SimpleAgent) – The base agent to add reflection to
name (str) – Name for the reflection system
reflection_frequency (int) – How often to inject reflection (every N messages)

async run_with_reflection(input_data)¶

Run the base agent with reflection context injection.

Parameters:: input_data (str | dict[str, Any]) – Input for the base agent
Returns:: Agent result with reflection context applied
Return type:: dict[str, Any]

class agents.reflection.message_transformer.MessageTransformerReflectionAgent(name='transformer_reflection_agent', temperature=0.3, preserve_first_message=True)¶

Reflection agent using message transformer v2 pattern.

Instead of structured output extraction, this uses message transformation to add reflection context directly to conversations, following the pattern from reflection_agent_pattern.md lines 565-594.

Initialize message transformer reflection agent.

Parameters:

name (str) – Name for the agent
temperature (float) – Temperature for LLM generation
preserve_first_message (bool) – Whether to preserve first message in transformation

async reflect_on_conversation(messages, original_query=None)¶

Perform reflection analysis using message transformation.

Parameters:

messages (list[langchain_core.messages.BaseMessage]) – The conversation messages to reflect on
original_query (str | None) – Optional original query for context

Returns:

Dict containing reflection analysis and transformed messages

Return type:

dict[str, Any]

class agents.reflection.message_transformer.ReflectionMessageFlow(primary_agent, reflection_agent=None, name='reflection_flow')¶

Manages reflection flow using message transformations.

This creates a workflow where reflection insights are naturally integrated into message flows rather than separate analysis steps.

Initialize reflection message flow.

Parameters:

primary_agent (haive.agents.simple.agent.SimpleAgent) – Main agent for primary responses
reflection_agent (haive.agents.simple.agent.SimpleAgent | None) – Optional dedicated reflection agent
name (str) – Name for the flow system

async run_primary_with_reflection(query, include_reflection=True)¶

Run primary agent and optionally add reflection insights.

Parameters:

query (str) – Input query
include_reflection (bool) – Whether to include reflection analysis

Returns:

Combined results with optional reflection insights

Return type:

dict[str, Any]

class agents.reflection.message_transformer.SimpleReflectionTransformer(preserve_first_message=True)¶

Simple reflection transformer for when message_transformation_v2 is not available.

Init .

Parameters:: preserve_first_message (bool) – [TODO: Add description]

agents.reflection.message_transformer.create_conversational_reflection_agent(base_agent, name='conv_reflector', reflection_frequency=3)¶

Create a conversational reflection agent.

Parameters:

base_agent (haive.agents.simple.agent.SimpleAgent)
name (str)
reflection_frequency (int)

Return type:

ConversationalReflectionAgent

agents.reflection.message_transformer.create_message_transformer_reflection_agent(name='mt_reflector', temperature=0.3, **kwargs)¶

Create a message transformer reflection agent.

Parameters:

name (str)
temperature (float)

Return type:

MessageTransformerReflectionAgent

agents.reflection.message_transformer.create_reflection_context_transformer(messages)¶

Create a reflection context transformer function.

This function adds reflection insights to conversation context, following the pattern from reflection_agent_pattern.md.

Parameters:: messages (list[langchain_core.messages.BaseMessage]) – Input messages to transform
Returns:: Messages with reflection context added
Return type:: list[langchain_core.messages.BaseMessage]

agents.reflection.message_transformer.create_reflection_message_flow(primary_agent, reflection_agent=None, name='reflection_flow')¶

Create a reflection message flow system.

Parameters:

primary_agent (haive.agents.simple.agent.SimpleAgent)
reflection_agent (haive.agents.simple.agent.SimpleAgent | None)
name (str)

Return type:

ReflectionMessageFlow

async agents.reflection.message_transformer.example_conversational_reflection()¶: Example: Conversational reflection with context injection.

async agents.reflection.message_transformer.example_message_transformer_reflection()¶: Example: Reflection using message transformer patterns.

async agents.reflection.message_transformer.example_reflection_message_flow()¶: Example: Complete reflection message flow system.

async agents.reflection.message_transformer.main()¶: Run all message transformer reflection examples.