Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.swarms.world/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Hierarchical Structured Communication Framework implements the “Talk Structurally, Act Hierarchically” approach for LLM multi-agent systems, based on the research paper arXiv:2502.11098. It provides structured communication protocols with specialized agent classes for content generation, evaluation, refinement, and supervision.

​
Installation

pip install -U swarms

​
Key Components

​
Agent Classes

  • HierarchicalStructuredCommunicationGenerator - Creates initial content
  • HierarchicalStructuredCommunicationEvaluator - Evaluates content quality
  • HierarchicalStructuredCommunicationRefiner - Improves content based on feedback
  • HierarchicalStructuredCommunicationSupervisor - Coordinates workflow

​
Main Framework

  • HierarchicalStructuredCommunicationFramework - Main orchestrator class
  • HierarchicalStructuredCommunicationSwarm - Convenience alias

​
Attributes

​
name
str
default:"HierarchicalStructuredCommunicationFramework"
Name of the framework instance
​
supervisor
HierarchicalStructuredCommunicationSupervisor
Main supervisor agent that coordinates the workflow
​
generators
List[HierarchicalStructuredCommunicationGenerator]
required
List of generator agents for creating initial content
​
evaluators
List[HierarchicalStructuredCommunicationEvaluator]
required
List of evaluator agents for assessing content quality
​
refiners
List[HierarchicalStructuredCommunicationRefiner]
required
List of refiner agents for improving content based on feedback
​
max_loops
int
default:"3"
Maximum number of refinement loops
​
enable_structured_communication
bool
default:"True"
Enable the structured communication protocol with Message (M_ij), Background (B_ij), and Intermediate Output (I_ij)
​
enable_hierarchical_evaluation
bool
default:"True"
Enable hierarchical evaluation with supervisor coordination
​
shared_memory
bool
default:"False"
Enable shared memory between agents
​
model_name
str
LLM model name to use for the agents
​
verbose
bool
default:"False"
Enable verbose logging

​
Methods

​
run()

Execute the complete workflow for a given task. 
def run(self, task: str, max_loops: int = None) -> dict
Parameters:
  • task (str): The task to execute
  • max_loops (int, optional): Override the default max_loops for this run
Returns: A dictionary containing the workflow results, including final_result

​
step()

Execute a single workflow step. 
def step(self, task: str) -> dict
Parameters:
  • task (str): The task to execute for one step
Returns: Result of a single step

​
send_structured_message()

Send a structured communication message between agents. 
def send_structured_message(self) -> None

​
run_hierarchical_evaluation()

Run the hierarchical evaluation system with supervisor coordination. 
def run_hierarchical_evaluation(self) -> dict
Returns: Evaluation results

​
Usage Examples

​
Quick Start

from swarms.structs.hierarchical_structured_communication_framework import (
    HierarchicalStructuredCommunicationFramework,
    HierarchicalStructuredCommunicationGenerator,
    HierarchicalStructuredCommunicationEvaluator,
    HierarchicalStructuredCommunicationRefiner,
    HierarchicalStructuredCommunicationSupervisor
)

# Create specialized agents
generator = HierarchicalStructuredCommunicationGenerator(
    agent_name="ContentGenerator"
)

evaluator = HierarchicalStructuredCommunicationEvaluator(
    agent_name="QualityEvaluator"
)

refiner = HierarchicalStructuredCommunicationRefiner(
    agent_name="ContentRefiner"
)

supervisor = HierarchicalStructuredCommunicationSupervisor(
    agent_name="WorkflowSupervisor"
)

# Create the framework
framework = HierarchicalStructuredCommunicationFramework(
    name="MyFramework",
    supervisor=supervisor,
    generators=[generator],
    evaluators=[evaluator],
    refiners=[refiner],
    max_loops=3
)

# Run the workflow
result = framework.run("Create a comprehensive analysis of AI trends in 2024")

​
Basic Usage with Default Supervisor

from swarms.structs.hierarchical_structured_communication_framework import (
    HierarchicalStructuredCommunicationFramework,
    HierarchicalStructuredCommunicationGenerator,
    HierarchicalStructuredCommunicationEvaluator,
    HierarchicalStructuredCommunicationRefiner
)

# Create agents with custom names
generator = HierarchicalStructuredCommunicationGenerator(agent_name="ContentGenerator")
evaluator = HierarchicalStructuredCommunicationEvaluator(agent_name="QualityEvaluator")
refiner = HierarchicalStructuredCommunicationRefiner(agent_name="ContentRefiner")

# Create framework with default supervisor
framework = HierarchicalStructuredCommunicationFramework(
    generators=[generator],
    evaluators=[evaluator],
    refiners=[refiner],
    max_loops=3,
    verbose=True
)

# Execute task
result = framework.run("Write a detailed report on renewable energy technologies")
print(result["final_result"])

​
Advanced Configuration

from swarms.structs.hierarchical_structured_communication_framework import (
    HierarchicalStructuredCommunicationFramework
)

# Create framework with custom configuration
framework = HierarchicalStructuredCommunicationFramework(
    name="AdvancedFramework",
    max_loops=5,
    enable_structured_communication=True,
    enable_hierarchical_evaluation=True,
    shared_memory=True,
    model_name="gpt-4o",
    verbose=True
)

# Run with custom parameters
result = framework.run(
    "Analyze the impact of climate change on global agriculture",
    max_loops=3
)

​
Integration with Other Swarms

from swarms.structs.hierarchical_structured_communication_framework import (
    HierarchicalStructuredCommunicationFramework
)
from swarms import AutoSwarmBuilder

# Use HierarchicalStructuredCommunicationFramework for content generation
framework = HierarchicalStructuredCommunicationFramework(
    max_loops=2,
    verbose=True
)

# Integrate with AutoSwarmBuilder
builder = AutoSwarmBuilder()
swarm = builder.create_swarm(
    swarm_type="HierarchicalStructuredCommunicationFramework",
    task="Generate a comprehensive business plan"
)

​
How It Works

The framework operates through a structured multi-phase workflow:
  1. Generation Phase: Generator agents create initial content based on the task
  2. Evaluation Phase: Evaluator agents assess the quality of generated content using structured communication protocols
  3. Refinement Phase: Refiner agents improve content based on evaluation feedback
  4. Supervision: The supervisor agent coordinates the entire workflow, deciding when to iterate or finalize
  5. Iteration: Steps 1-4 repeat up to max_loops times until quality thresholds are met

​
Structured Communication Protocol

The framework uses a formal communication protocol with three components:
  • Message (M_ij): Direct communication between agents
  • Background (B_ij): Contextual information shared between agents
  • Intermediate Output (I_ij): Partial results passed between workflow stages

​
Features

  • Structured Communication: Formal protocol for inter-agent messaging
  • Hierarchical Evaluation: Multi-level quality assessment with supervisor oversight
  • Iterative Refinement: Content improves through generate-evaluate-refine loops
  • Specialized Agents: Purpose-built agent classes for each workflow role
  • Configurable: Flexible configuration for communication, evaluation, and memory
  • Shared Memory: Optional shared memory between agents for context retention

​
Source Code

View the source code on GitHub