agents.structured_output.agent

Generalized Structured Output Agent for enhancing any agent with structured output parsing.

Classes

StructuredOutputAgent

Agent that adds structured output parsing to any other agent.

Module Contents

class agents.structured_output.agent.StructuredOutputAgent(/, **data)

Bases: haive.agents.simple.agent.SimpleAgent

Agent that adds structured output parsing to any other agent.

This agent acts as a post-processor that takes the output from any agent and ensures it conforms to a structured format. It can work standalone or as part of a sequential multi-agent chain.

Key features: - Works with any agent type (SimpleAgent, ReactAgent, etc.) - Preserves original context and input - Uses PydanticToolsParser for robust parsing - Can be chained sequentially with any agent - Supports multiple output models

Example

# Enhance any agent with structured output
enhanced_agent = StructuredOutputAgent.enhance_agent(
base_agent=my_agent,
output_models=[SearchResult, AnalysisResult]
)

# Or use as standalone post-processor
processor = StructuredOutputAgent.create_processor(
output_models=[ResultModel],
include_original_input=True
)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

classmethod create_processor(output_models, name='structured_output_processor', include_original_input=True, system_message=None, **kwargs)

Create a standalone structured output processor.

Parameters:

  • output_models (list[type[pydantic.BaseModel]]) – List of Pydantic models for output formats

  • name (str) – Name for the processor

  • include_original_input (bool) – Include original input for context

  • system_message (str | None) – Custom system message (auto-generated if not provided)

  • **kwargs – Additional configuration

Returns:

Configured StructuredOutputAgent instance

Return type:

StructuredOutputAgent

classmethod create_reflection_processor(reflection_models, name='reflection_processor', **kwargs)

Create a processor specifically for reflection patterns.

This is optimized for reflection/reflexion agents that need to analyze their own outputs and provide structured feedback.

Parameters:

  • reflection_models (list[type[pydantic.BaseModel]]) – Models for reflection (e.g., Critique, Improvement)

  • name (str) – Name for the processor

  • **kwargs – Additional configuration

Returns:

StructuredOutputAgent configured for reflection

Return type:

StructuredOutputAgent

classmethod create_validation_processor(validation_models, name='validation_processor', **kwargs)

Create a processor for validation patterns.

Parameters:

  • validation_models (list[type[pydantic.BaseModel]]) – Models for validation results

  • name (str) – Name for the processor

  • **kwargs – Additional configuration

Returns:

StructuredOutputAgent configured for validation

Return type:

StructuredOutputAgent

classmethod enhance_agent(base_agent, output_models, name=None, include_original_input=True, **kwargs)

Enhance any agent with structured output capabilities.

Creates a sequential multi-agent that runs: 1. Base agent (processes input normally) 2. StructuredOutputAgent (ensures output is structured)

Parameters:

  • base_agent (haive.agents.base.agent.Agent) – The agent to enhance

  • output_models (list[type[pydantic.BaseModel]]) – List of Pydantic models for output formats

  • name (str | None) – Name for the enhanced agent

  • include_original_input (bool) – Include original input for context

  • **kwargs – Additional arguments for the structured output agent

Returns:

ProperMultiAgent configured for sequential execution

Return type:

haive.agents.multi.experiments.implementations.proper_base.ProperMultiAgent

process_with_context(content, original_input=None)

Process content with optional original context.

Parameters:

  • content (str) – The content to structure

  • original_input (str | None) – Original task/query for context

Returns:

Structured output result

Return type:

dict[str, Any]

setup_agent()

Setup hook to configure structured output state.

Return type:

None