agents.base.agent_structured_output_mixin

Mixin for adding structured output capabilities to agents.

This mixin provides class methods for creating agents with structured output, enabling any agent to be composed with a StructuredOutputAgent for type-safe output conversion.

Classes

StructuredOutputMixin

Mixin that adds structured output capabilities to any agent.

Module Contents

class agents.base.agent_structured_output_mixin.StructuredOutputMixin

Mixin that adds structured output capabilities to any agent.

classmethod as_structured_tool(output_model, name=None, description=None, **agent_kwargs)

Convert agent to a tool that returns structured output.

This creates a tool that: 1. Runs the agent 2. Converts output to structured format 3. Returns the Pydantic model instance

Parameters:

  • output_model (type[T]) – The Pydantic model for output

  • name (str | None) – Optional tool name

  • description (str | None) – Optional tool description

  • **agent_kwargs – Arguments for agent construction

Returns:

LangChain tool that returns structured output

Return type:

Any

Examples

Create structured tool:

research_tool = ResearchAgent.as_structured_tool(
    output_model=ResearchResult,
    name="research_tool",
    description="Research topics and return structured results"
)

# Use in another agent
coordinator = ReactAgent(
    name="coordinator",
    tools=[research_tool]
)
ensure_structured_output(output, output_model, handle_errors=True)

Ensure agent output conforms to a structured model.

This instance method can be used to validate/convert output after execution, handling various output formats gracefully.

Parameters:

  • output (Any) – The output to structure (str, BaseMessage, dict, etc.)

  • output_model (type[T]) – The Pydantic model to convert to

  • handle_errors (bool) – Whether to return None on errors (vs raising)

Returns:

Structured output instance or None if error and handle_errors=True

Return type:

T | None

Examples

In agent implementation:

def run(self, input_text: str) -> Any:
    # Get raw output
    raw_output = self.engine.invoke(input_text)

    # Ensure it's structured
    return self.ensure_structured_output(
        raw_output,
        self.output_schema
    )
classmethod with_structured_output(output_model, name=None, custom_context=None, custom_prompt=None, **agent_kwargs)

Create an agent paired with a StructuredOutputAgent for structured output.

This method creates a two-agent workflow where: 1. The original agent produces unstructured output 2. A StructuredOutputAgent converts it to the specified model

The agents are designed to work in sequence in a multi-agent workflow, with the structured output agent reading from messages state.

Parameters:

  • output_model (type[T]) – The Pydantic model to structure output into

  • name (str | None) – Optional name for the agent (defaults to class name)

  • custom_context (str | None) – Optional context for extraction

  • custom_prompt (langchain_core.prompts.ChatPromptTemplate | None) – Optional custom prompt template

  • **agent_kwargs – Arguments passed to the original agent constructor

Returns:

Tuple of (original_agent, structured_output_agent)

Return type:

tuple[TAgent, haive.agents.base.agent.Agent]

Examples

Basic usage:

# Create ReactAgent with structured output
planner, structurer = ReactAgent.with_structured_output(
    output_model=PlanOutput,
    name="planner"
)

# Use in multi-agent workflow
agents = [planner, structurer]

Custom extraction:

analyzer, structurer = SimpleAgent.with_structured_output(
    output_model=AnalysisResult,
    custom_context="Focus on quantitative metrics",
    temperature=0.7
)

In state definition:

class WorkflowState(MultiAgentState):
    # AnalysisResult fields will be populated
    summary: str = ""
    metrics: Dict[str, float] = Field(default_factory=dict)
    confidence: float = 0.0