> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Hierarchical Workflows

> Manager-based validation for graceful workflow failure handling

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.

<Note>
  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](/docs/features/hierarchical-process).
</Note>

<Note>
  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`](/docs/docs/features/nested-workflows#retry-guardrails-and-output_file-inside-nested-steps).
</Note>

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Hierarchical Workflow"
        In[📄 User Brief] --> A1[🤖 Agent 1]
        A1 --> V1{"Manager<br/>Validation"}
        V1 -->|Approved| A2[🤖 Agent 2]
        V1 -->|Rejected| Fail[❌ Failed + Reason]
        A2 --> V2{"Manager<br/>Validation"}
        V2 -->|Approved| Out[✅ Result]
        V2 -->|Rejected| Fail
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef manager fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff
    classDef fail fill:#F59E0B,stroke:#7C90A0,color:#fff

    class In,A1,A2 agent
    class V1,V2 manager
    class Out success
    class Fail fail
```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant AgentFlow
    participant Manager
    participant Agent

    User->>AgentFlow: Submit task
    AgentFlow->>Agent: Run step 1
    Agent-->>AgentFlow: Output
    AgentFlow->>Manager: Validate output
    alt Approved
        Manager-->>AgentFlow: Proceed to step 2
    else Rejected
        Manager-->>AgentFlow: Stop with failure_reason
        AgentFlow-->>User: {status: failed, failure_reason: ...}
    end
    AgentFlow-->>User: {status: completed, output: ...}
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph Workflow["Hierarchical Workflow"]
        direction TB
        A[/"Input"/]:::input --> B["Step 1: Agent"]:::agent
        B --> C{"Manager<br/>Validation"}:::manager
        C -->|Approved| D["Step 2: Agent"]:::agent
        C -->|Rejected| E[/"Failed + Reason"/]:::output
        D --> F{"Manager<br/>Validation"}:::manager
        F -->|Approved| G[/"Completed"/]:::output
        F -->|Rejected| E
    end
    
    classDef input fill:#8B0000,color:#fff,stroke:#7C90A0
    classDef output fill:#8B0000,color:#fff,stroke:#7C90A0
    classDef agent fill:#8B0000,color:#fff,stroke:#7C90A0
    classDef manager fill:#189AB4,color:#fff,stroke:#7C90A0
```

<CardGroup cols={2}>
  <Card title="Sequential (Default)" icon="arrow-right">
    Steps run one after another without validation
  </Card>

  <Card title="Hierarchical" icon="sitemap">
    Manager validates each step before proceeding
  </Card>
</CardGroup>

## Quick Start

<Steps>
  <Step title="Simple Usage">
    <Tabs>
      <Tab title="Python">
        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        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']}")
        ```
      </Tab>

      <Tab title="YAML">
        ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        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
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="With Configuration">
    Define the same workflow in YAML with process: hierarchical and a manager\_llm — see the YAML tab.
  </Step>
</Steps>

## Parameters

<ParamField path="process" type="string" default="sequential">
  Workflow execution mode:

  * `sequential` - Steps run without validation (default)
  * `hierarchical` - Manager validates each step
</ParamField>

<ParamField path="manager_llm" type="string" default="null">
  LLM model for the manager agent. If not specified, uses the workflow's `default_llm`.
</ParamField>

## Manager Validation

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

<Steps>
  <Step title="Task Completion">
    Does the output address the task?
  </Step>

  <Step title="Quality Check">
    Is the output meaningful (not an error)?
  </Step>

  <Step title="Expected Output">
    Does it meet the step's expected output criteria?
  </Step>
</Steps>

## Handling Failures

<CodeGroup>
  ```python Check Status theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  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!")
  ```

  ```python With Callbacks theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  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}
  )
  ```
</CodeGroup>

## Result Structure

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
    "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

<AccordionGroup>
  <Accordion title="Quality-Critical Workflows" icon="shield-check">
    When each step must meet quality standards before proceeding.
  </Accordion>

  <Accordion title="Multi-Agent Pipelines" icon="users">
    When agents depend on validated output from previous agents.
  </Accordion>

  <Accordion title="Production Workflows" icon="rocket">
    When you need graceful failure handling with clear reasons.
  </Accordion>
</AccordionGroup>

## Forcing Tool Usage

<Warning>
  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.
</Warning>

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph Without["tool_choice: auto (default)"]
        A1["Agent with tools"]:::agent --> B1{"LLM decides"}:::manager
        B1 -->|"May skip"| C1["Response without tool"]:::output
        B1 -->|"May call"| D1["Tool call → Response"]:::output
    end
    
    subgraph With["tool_choice: required"]
        A2["Agent with tools"]:::agent --> B2["Must call tool"]:::manager
        B2 --> C2["Tool call → Response"]:::output
    end
    
    classDef agent fill:#8B0000,color:#fff,stroke:#7C90A0
    classDef output fill:#8B0000,color:#fff,stroke:#7C90A0
    classDef manager fill:#189AB4,color:#fff,stroke:#7C90A0
```

<Tabs>
  <Tab title="YAML">
    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    agents:
      researcher:
        role: Research Specialist
        goal: Find latest information
        tools:
          - search_web
        tool_choice: required  # Forces tool usage
        llm: gpt-4o-mini
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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"
    ```
  </Tab>
</Tabs>

<ParamField path="tool_choice" type="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
</ParamField>

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

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

<Tip>
  Use `hierarchical` mode when you need **guaranteed quality** at each step. Use `sequential` mode for **faster execution** when validation isn't critical.
</Tip>

## Real-World Examples

<AccordionGroup>
  <Accordion title="Research & Writing Pipeline" icon="pen">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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")
    ```
  </Accordion>

  <Accordion title="Data Analysis Pipeline" icon="chart-line">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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']}")
    ```
  </Accordion>

  <Accordion title="Code Review Pipeline" icon="code">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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")
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Force tool usage in tool-heavy steps">
    Set `tool_choice="required"` so the manager can confirm tools actually ran before approving a step.
  </Accordion>

  <Accordion title="Always check result status">
    Inspect `result["status"]` and `result["failure_reason"]` before using the output — hierarchical workflows fail gracefully rather than raising.
  </Accordion>

  <Accordion title="Keep steps single-purpose">
    Narrow, well-scoped steps make manager validation more reliable than broad, multi-goal steps.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="AgentFlow" icon="diagram-project" href="/docs/features/agentflow">
    Deterministic multi-step pipelines
  </Card>

  <Card title="Conditional Execution" icon="code-branch" href="/docs/features/conditions">
    Branch workflows on runtime conditions
  </Card>

  <Card title="AgentTeam" icon="users" href="/docs/features/agentteam">
    Multi-agent task orchestration
  </Card>

  <Card title="Handoffs" icon="arrow-right-arrow-left" href="/docs/features/handoffs">
    Transfer control between agents
  </Card>
</CardGroup>