Hierarchical Workflows

Hierarchical workflows add a manager agent that validates each step’s output before the next step runs, stopping gracefully with a clear reason if a step fails.

This page covers AgentFlow(process="hierarchical") — where a manager validates each step’s output before the next step runs. If you want a manager that delegates tasks to agents by name (the classic PraisonAIAgents(agents=[...], tasks=[...], process="hierarchical") flow), see Hierarchical Process.

Steps inside hierarchical mode inherit the same max_retries, guardrails, and output_file policies as top-level steps. See Nested workflows → Retry, guardrails, and output_file.

from praisonaiagents import Agent, AgentFlow

researcher = Agent(name="researcher", role="Research topics")
writer = Agent(name="writer", role="Write content")
workflow = AgentFlow(
    steps=[researcher, writer],
    process="hierarchical",
    manager_llm="gpt-4o-mini",
)
workflow.start("Summarise quantum computing for executives")

The user submits a multi-step brief; the manager validates each agent output before the workflow continues.

How It Works

Sequential (Default)

Steps run one after another without validation

Hierarchical

Manager validates each step before proceeding

Quick Start

Simple Usage

Python
YAML

from praisonaiagents import AgentFlow, Agent

researcher = Agent(name="researcher", role="Research topics")
writer = Agent(name="writer", role="Write content")

workflow = AgentFlow(
    steps=[researcher, writer],
    process="hierarchical",  # Enable manager validation
    manager_llm="gpt-4o-mini"  # LLM for manager agent
)

result = workflow.start("Write about AI trends")

if result["status"] == "failed":
    print(f"Workflow failed: {result['failure_reason']}")
else:
    print(f"Output: {result['output']}")

name: research-workflow
process: hierarchical
manager_llm: gpt-4o-mini

agents:
  researcher:
    role: Research Analyst
    goal: Research topics thoroughly
    backstory: Expert researcher
  
  writer:
    role: Content Writer
    goal: Write engaging content
    backstory: Professional writer

steps:
  - agent: researcher
    action: Research the topic
  
  - agent: writer
    action: Write article based on research

With Configuration

Define the same workflow in YAML with process: hierarchical and a manager_llm — see the YAML tab.

Parameters

string

default:"sequential"

Workflow execution mode:

sequential - Steps run without validation (default)
hierarchical - Manager validates each step

string

default:"null"

LLM model for the manager agent. If not specified, uses the workflow’s default_llm.

Manager Validation

The manager agent evaluates each step’s output based on:

Task Completion

Does the output address the task?

Quality Check

Is the output meaningful (not an error)?

Expected Output

Does it meet the step’s expected output criteria?

Handling Failures

result = workflow.start("My task")

if result["status"] == "failed":
    # Workflow was rejected by manager
    print(f"Reason: {result['failure_reason']}")
    
    # Check which step failed
    for step in result["steps"]:
        if step["status"] == "failed":
            print(f"Failed step: {step['step']}")
elif result["status"] == "completed":
    print("All steps validated successfully!")

def on_step_error(workflow, step, error):
    print(f"Step '{step.name}' failed: {error}")

workflow = AgentFlow(
    steps=[agent1, agent2],
    process="hierarchical",
    hooks={"on_step_error": on_step_error}
)

Result Structure

{
    "output": "Final output from last step",
    "steps": [
        {"step": "researcher", "output": "...", "status": "completed"},
        {"step": "writer", "output": "...", "status": "failed", "failure_reason": "..."}
    ],
    "variables": {...},
    "status": "failed",  # or "completed"
    "failure_reason": "Manager rejected step 'writer': Output lacks detail"
}

When to Use

Quality-Critical Workflows

When each step must meet quality standards before proceeding.

Multi-Agent Pipelines

When agents depend on validated output from previous agents.

Production Workflows

When you need graceful failure handling with clear reasons.

Forcing Tool Usage

When agents have tools assigned, the LLM may skip calling them even with explicit instructions. Use tool_choice: required to force the LLM to call a tool before responding.

YAML
Python

agents:
  researcher:
    role: Research Specialist
    goal: Find latest information
    tools:
      - search_web
    tool_choice: required  # Forces tool usage
    llm: gpt-4o-mini

from praisonaiagents import Agent

researcher = Agent(
    name="researcher",
    role="Research Specialist",
    tools=["search_web"],
    llm="gpt-4o-mini"
)
# Set tool_choice for YAML workflows
researcher._yaml_tool_choice = "required"

string

default:"auto"

Controls when the LLM calls tools:

auto - LLM decides whether to call tools (default)
required - LLM must call a tool before responding
none - LLM cannot call tools

Always use tool_choice: required for agents with tools in hierarchical workflows. This ensures the manager can validate that tools were actually used.

Comparison

Feature	Sequential	Hierarchical
Validation	None	After each step
Failure Handling	Continues on error	Stops with reason
Performance	Faster	Slightly slower
Use Case	Simple pipelines	Quality-critical flows

Use hierarchical mode when you need guaranteed quality at each step. Use sequential mode for faster execution when validation isn’t critical.

Real-World Examples

Research & Writing Pipeline

from praisonaiagents import AgentFlow, Agent

researcher = Agent(
    name="researcher",
    role="Research Analyst",
    goal="Find accurate, up-to-date information",
    backstory="Expert researcher with attention to detail",
    llm="gpt-4o-mini"
)

writer = Agent(
    name="writer",
    role="Content Writer", 
    goal="Write engaging, clear content",
    backstory="Professional writer who creates compelling articles",
    llm="gpt-4o-mini"
)

editor = Agent(
    name="editor",
    role="Editor",
    goal="Polish and improve content quality",
    backstory="Experienced editor with keen eye for detail",
    llm="gpt-4o-mini"
)

workflow = AgentFlow(
    name="content-pipeline",
    steps=[researcher, writer, editor],
    process="hierarchical",
    manager_llm="gpt-4o-mini"
)

result = workflow.start("Write an article about AI in healthcare")

Data Analysis Pipeline

from praisonaiagents import AgentFlow, Agent

collector = Agent(
    name="collector",
    role="Data Collector",
    goal="Gather and prepare data",
    llm="gpt-4o-mini"
)

analyst = Agent(
    name="analyst",
    role="Data Analyst",
    goal="Analyze data and find insights",
    llm="gpt-4o-mini"
)

reporter = Agent(
    name="reporter",
    role="Report Writer",
    goal="Create clear reports from analysis",
    llm="gpt-4o-mini"
)

workflow = AgentFlow(
    name="data-pipeline",
    steps=[collector, analyst, reporter],
    process="hierarchical",
    manager_llm="gpt-4o-mini"
)

result = workflow.start("Analyze Q4 sales trends")

if result["status"] == "failed":
    print(f"Pipeline failed: {result['failure_reason']}")

Code Review Pipeline

from praisonaiagents import AgentFlow, Agent

reader = Agent(
    name="code_reader",
    role="Code Reader",
    goal="Understand code structure",
    llm="gpt-4o-mini"
)

reviewer = Agent(
    name="reviewer",
    role="Code Reviewer",
    goal="Find issues and improvements",
    llm="gpt-4o-mini"
)

suggester = Agent(
    name="suggester",
    role="Improvement Suggester",
    goal="Suggest specific code improvements",
    llm="gpt-4o-mini"
)

workflow = AgentFlow(
    name="code-review-pipeline",
    steps=[reader, reviewer, suggester],
    process="hierarchical",
    manager_llm="gpt-4o-mini",
    output="verbose"  # See validation results
)

result = workflow.start("Review this Python module for best practices")

Best Practices

Use a cheaper model for the manager

The manager only validates output, so a smaller manager_llm like gpt-4o-mini keeps cost low without hurting quality.

Force tool usage in tool-heavy steps

Set tool_choice="required" so the manager can confirm tools actually ran before approving a step.

Always check result status

Inspect result["status"] and result["failure_reason"] before using the output — hierarchical workflows fail gracefully rather than raising.

Keep steps single-purpose

Narrow, well-scoped steps make manager validation more reliable than broad, multi-goal steps.

AgentFlow

Deterministic multi-step pipelines

Conditional Execution

Branch workflows on runtime conditions

AgentTeam

Multi-agent task orchestration

Handoffs

Transfer control between agents

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Hierarchical Workflows

How It Works

Sequential (Default)

Hierarchical

Quick Start

Parameters

Manager Validation

Handling Failures

Result Structure

When to Use

Forcing Tool Usage

Comparison

Real-World Examples

Best Practices

AgentFlow

Conditional Execution

AgentTeam

Handoffs

​How It Works

Sequential (Default)

Hierarchical

​Quick Start

​Parameters

​Manager Validation

​Handling Failures

​Result Structure

​When to Use

​Forcing Tool Usage

​Comparison

​Real-World Examples

​Best Practices

​Related

AgentFlow

Conditional Execution

AgentTeam

Handoffs

How It Works

Quick Start

Parameters

Manager Validation

Handling Failures

Result Structure

When to Use

Forcing Tool Usage

Comparison

Real-World Examples

Best Practices

Related