> ## 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.

# HierarchicalStructuredCommunicationFramework

> A multi-agent framework implementing structured communication and hierarchical evaluation based on the 'Talk Structurally, Act Hierarchically' approach

## 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

```bash theme={null}
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

## Attributes

<ParamField path="name" type="str" default="HierarchicalStructuredCommunicationFramework">
  Name of the framework instance
</ParamField>

<ParamField path="supervisor" type="Optional[Union[Agent, Callable, Any]]" default="None">
  Main supervisor agent that coordinates the workflow. If not provided, a default `Agent` supervisor is created automatically.
</ParamField>

<ParamField path="generators" type="Optional[List[Union[Agent, Callable, Any]]]" default="None">
  List of generator agents for creating initial content. If not provided, a single default generator agent is created automatically.
</ParamField>

<ParamField path="evaluators" type="Optional[List[Union[Agent, Callable, Any]]]" default="None">
  List of evaluator agents for assessing content quality. If not provided (and `enable_hierarchical_evaluation=True`), a single default evaluator agent is created automatically.
</ParamField>

<ParamField path="refiners" type="Optional[List[Union[Agent, Callable, Any]]]" default="None">
  List of refiner agents for improving content based on feedback. If not provided, a single default refiner agent is created automatically.
</ParamField>

<ParamField path="evaluation_supervisor" type="Optional[Union[Agent, Callable, Any]]" default="None">
  Dedicated supervisor that coordinates the hierarchical evaluation phase. Created automatically if not provided.
</ParamField>

<ParamField path="max_loops" type="int" default="3">
  Maximum number of refinement loops
</ParamField>

<ParamField path="output_type" type="OutputType" default="dict-all-except-first">
  Format applied to the conversation history.
</ParamField>

<ParamField path="supervisor_name" type="str" default="Supervisor">
  Display name for the main supervisor agent.
</ParamField>

<ParamField path="evaluation_supervisor_name" type="str" default="EvaluationSupervisor">
  Display name for the evaluation supervisor agent.
</ParamField>

<ParamField path="enable_structured_communication" type="bool" default="True">
  Enable the structured communication protocol with Message (M\_ij), Background (B\_ij), and Intermediate Output (I\_ij)
</ParamField>

<ParamField path="enable_hierarchical_evaluation" type="bool" default="True">
  Enable hierarchical evaluation with supervisor coordination
</ParamField>

<ParamField path="shared_memory" type="bool" default="True">
  Enable shared memory between agents
</ParamField>

<ParamField path="model_name" type="str" default="gpt-5.4">
  LLM model name to use for the agents
</ParamField>

<ParamField path="verbose" type="bool" default="False">
  Enable verbose logging
</ParamField>

<ParamField path="use_ollama" type="bool" default="False">
  Route agent calls through a local Ollama server instead of a hosted provider.
</ParamField>

<ParamField path="ollama_base_url" type="str" default="http://localhost:11434/v1">
  Base URL for the Ollama server when `use_ollama=True`.
</ParamField>

<ParamField path="ollama_api_key" type="str" default="ollama">
  API key sent to the Ollama server when `use_ollama=True`.
</ParamField>

## Methods

### run()

Execute the complete workflow for a given task, looping up to `max_loops` times (set at construction).

```python theme={null}
def run(self, task: str, img: str = None, *args, **kwargs) -> dict
```

**Parameters:**

* `task` (str): The task to execute
* `img` (str, optional): Optional image input

**Returns:** A dictionary containing `final_result`, `total_loops`, `conversation_history`, `evaluation_results`, and `intermediate_outputs`

<Note>
  `run()` does not accept a `max_loops` override — the number of refinement loops is fixed by the `max_loops` value passed to the constructor.
</Note>

### step()

Execute a single workflow step (generate, evaluate, refine).

```python theme={null}
def step(self, task: str, img: str = None, *args, **kwargs) -> dict
```

**Parameters:**

* `task` (str): The task to execute for one step
* `img` (str, optional): Optional image input

**Returns:** A dictionary with `generator_result`, `evaluation_results`, `refined_result`, and `conversation_history` (or an `error` key on failure)

### send\_structured\_message()

Send a structured communication message between agents, following the Message (M\_ij) / Background (B\_ij) / Intermediate Output (I\_ij) protocol.

```python theme={null}
def send_structured_message(
    self,
    sender: str,
    recipient: str,
    message: str,
    background: str = "",
    intermediate_output: str = "",
) -> StructuredMessage
```

**Parameters:**

* `sender` (str): Name of the sending agent
* `recipient` (str): Name of the receiving agent
* `message` (str): Specific task message (M\_ij)
* `background` (str, optional): Background context (B\_ij)
* `intermediate_output` (str, optional): Intermediate output (I\_ij)

**Returns:** The `StructuredMessage` that was appended to `conversation_history`

### run\_hierarchical\_evaluation()

Run the hierarchical evaluation system with supervisor coordination.

```python theme={null}
def run_hierarchical_evaluation(
    self, content: str, evaluation_criteria: List[str] = None
) -> List[EvaluationResult]
```

**Parameters:**

* `content` (str): Content to evaluate
* `evaluation_criteria` (List\[str], optional): Criteria to evaluate against. Defaults to `["accuracy", "completeness", "clarity", "relevance"]`.

**Returns:** A list of `EvaluationResult` objects, one per evaluator

## Usage Examples

### Quick Start

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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="claude-sonnet-4-6",
    verbose=True
)

# Run the task (loops up to the max_loops set above)
result = framework.run(
    "Analyze the impact of climate change on global agriculture"
)
```

## 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](https://github.com/kyegomez/swarms/blob/master/swarms/structs/hierarchical_structured_communication_framework.py)