Hierarchical Crew Architecture

HornetHive uses a hybrid CrewAI architecture that leverages hierarchical process for complex coordination tasks while maintaining sequential execution for simpler workflows.

How It Works

Sequential Process (Default)

In sequential mode, agents execute tasks one after another in a predefined order:

Agent A → Agent B → Agent C → Final Output

Best for:

• Simple, linear workflows
• 2-3 agent crews
• Speed-critical tasks
• Single-purpose operations

Hierarchical Process

In hierarchical mode, a Manager Agent coordinates worker agents, delegating tasks and synthesizing outputs:

                    ┌─────────────────┐
                    │  Manager Agent  │
                    │    (GPT-4o)     │
                    └────────┬────────┘
                             │
           ┌─────────────────┼─────────────────┐
           │                 │                 │
           ▼                 ▼                 ▼
    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
    │   Worker A   │  │   Worker B   │  │   Worker C   │
    │ (GPT-4o-mini)│  │ (GPT-4o-mini)│  │ (GPT-4o-mini)│
    └──────────────┘  └──────────────┘  └──────────────┘

Best for:

• Complex multi-agent workflows (4+ agents)
• Tasks requiring synthesis of multiple outputs
• Quality-critical deliverables
• PRD generation, market analysis, content campaigns

Cost Optimization

The hierarchical architecture provides significant cost savings:

Role	Model	Cost (per 1M tokens)
Manager	GPT-4o	$5 input / $15 output
Workers	GPT-4o-mini	$0.15 input / $0.60 output

Estimated savings: 60-70% on worker token costs while maintaining quality through manager coordination.

Crews Using Hierarchical Mode

HivePilot PRD Generation

The 7-agent PRD crew uses hierarchical mode by default:

• Manager: Coordinates all agents, synthesizes final PRD
• Workers: Market Analyst, User Researcher, Requirements Spec, Technical Architect, Risk Assessor, QA Lead, PRD Writer

# Automatically enabled for HivePilot PRD
process=Process.hierarchical
manager_llm=ChatOpenAI(model="gpt-4o", temperature=0.3)

HiveWriter Full Crew

Content creation with 5+ agents uses hierarchical mode:

• Manager: Coordinates content strategy and synthesis
• Workers: Content Strategist, SEO Specialist, Writer, Editor, Social Media Expert

When Hierarchical is Auto-Enabled

The system automatically selects hierarchical mode when:

Condition	Threshold
Agent count	4 or more agents
Synthesis required	3+ agents with requires_synthesis=True
Quality priority	3+ agents with quality_priority=True

Configuration

Enabling Hierarchical Mode

Via Environment Variable:

HIVEPILOT_MANAGER_MODEL=gpt-4o

Via Code Configuration:

from app.crews.base.crew_orchestrator import CrewExecutionConfig, CrewProcessType

config = CrewExecutionConfig(
    process_type=CrewProcessType.HIERARCHICAL,
    use_hierarchical=True,
    manager_model="gpt-4o",
    requires_synthesis=True
)

Decision Helper

Use the built-in helper to determine the optimal process:

from app.crews.base.cost_effective_llm import should_use_hierarchical

# Returns True for 4+ agents
should_use_hierarchical(agent_count=7)  # True

# Returns True for synthesis workflows
should_use_hierarchical(agent_count=3, requires_synthesis=True)  # True

# Returns False for simple crews
should_use_hierarchical(agent_count=2)  # False

CrewAI Flows (Multi-Crew Orchestration)

For workflows requiring multiple crews, HornetHive provides CrewAI Flows:

Content Optimization Flow (2 Crews)

Content Creation Crew → SEO Optimization Crew → Final Content

Market Analysis Flow (3 Crews)

Market Research → Competitor Analysis → Strategy Synthesis

Product Launch Flow (5 Crews)

Market Research ─┬→ Content Creation ─┬→ Launch Coordination
                 └→ Campaign Planning ─┘
Technical Readiness ────────────────────┘

Performance Metrics

From production testing:

Metric	Sequential	Hierarchical
PRD Generation Time	~5 min	~10 min
Token Usage	150k	275k
Quality Score	7.5/10	9/10
Cost per PRD	$2.50	$1.80

The increased time is offset by:

• Higher quality output
• Better synthesis across agents
• Lower per-token cost with worker agents

Best Practices

1. Use Hierarchical for Complex Outputs

PRDs, comprehensive analyses, and multi-channel campaigns benefit most from manager coordination.

2. Keep Sequential for Speed

Quick responses, single-format content, and real-time interactions should use sequential.

3. Monitor Token Usage

Track tokens via the outcome metadata to optimize costs:

{
  "metadata": {
    "process_type": "hierarchical",
    "tokens_used": {
      "total_tokens": 274152,
      "prompt_tokens": 250251,
      "completion_tokens": 23901
    }
  }
}

4. Test Both Modes

Compare quality and cost for your specific use cases before committing to one approach.

Troubleshooting

Hierarchical Mode Not Activating

• Check use_hierarchical=True in config
• Verify agent count meets threshold (4+)
• Ensure OPENAI_API_KEY is set for manager LLM

Higher Than Expected Costs

• Manager uses GPT-4o which costs more per token
• Expected if manager makes many coordination calls
• Consider if sequential would suffice for simpler tasks

Slower Execution

• Hierarchical adds coordination overhead
• Normal for complex workflows
• Consider sequential for time-critical tasks

---

Related Documentation:

• Crew Configuration
• HivePilot
• API Reference