multi_agent_state_guide_2025

MultiAgentState Guide - Haive Framework

Date: August 7, 2025
Version: 1.0
Purpose: Comprehensive guide to MultiAgentState schema and patterns

🎯 Overview

MultiAgentState is the core state container for multi-agent workflows in Haive. It provides:

• State isolation between agents without schema flattening
• Direct field updates for structured output agents
• Recompilation tracking for dynamic workflows
• Clean data flow between sequential agents

📋 Core Architecture

Class Definition

from haive.core.schema.prebuilt.multi_agent_state import MultiAgentState
from haive.core.schema.tool_state import ToolState

class MultiAgentState(ToolState):
    """Container state for multi-agent workflows."""
    
    # Agent storage (list or dict)
    agents: list[Any] | dict[str, Any]
    
    # Isolated state for each agent
    agent_states: dict[str, dict[str, Any]]
    
    # Execution tracking
    active_agent: str | None
    agent_outputs: dict[str, Any]  # Legacy message pattern
    agent_execution_order: list[str]
    
    # Recompilation management
    agents_needing_recompile: set[str]
    recompile_count: int
    recompile_history: list[dict[str, Any]]

Key Insight: No Schema Flattening

Unlike previous approaches that tried to merge all agent schemas, MultiAgentState:

• Keeps each agent's schema independent
• Projects state to agents as needed
• Maintains type safety without complex merging

🏗️ State Management Patterns

1. Direct Field Updates (Recommended)

Agents with structured_output_model update container fields directly:

from pydantic import BaseModel

# Define structured outputs
class AnalysisResult(BaseModel):
    score: float
    findings: list[str]
    
class ReportResult(BaseModel):
    summary: str
    recommendations: list[str]

# Create agents with structured output
analyzer = SimpleAgentV3(
    name="analyzer",
    structured_output_model=AnalysisResult
)

reporter = SimpleAgentV3(
    name="reporter",
    structured_output_model=ReportResult
)

# Initialize state
state = MultiAgentState(agents=[analyzer, reporter])

# After analyzer runs, state has 'analyzer' field
# After reporter runs, state has 'reporter' field
# Both are typed and validated!