Hierarchical Process

A manager agent decides which task runs next and which agent takes it, one delegation turn at a time.

Since PraisonAI PR #3790, the hierarchical process correctly excludes the manager task from delegation candidates and blocks self-delegation. Earlier releases could allow the manager to delegate a subtask back to itself and could surface the manager’s generic response as the final result. No API change — existing process="hierarchical" code benefits automatically.

Quick Start

Delegate two tasks to two agents

The manager on manager_llm picks the next task and agent each turn.

from praisonaiagents import Agent, Task, PraisonAIAgents

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

tasks = [
    Task(name="research", description="Research AI trends", agent=researcher),
    Task(name="write", description="Write article about AI trends", agent=writer),
]

team = PraisonAIAgents(
    agents=[researcher, writer],
    tasks=tasks,
    process="hierarchical",
    manager_llm="gpt-4o-mini",
)
team.start()

See each delegation turn

Add output="verbose" to watch the manager emit {task_id, agent_name, action} on every turn.

from praisonaiagents import Agent, Task, PraisonAIAgents

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

tasks = [
    Task(name="research", description="Research AI trends", agent=researcher),
    Task(name="write", description="Write article about AI trends", agent=writer),
]

team = PraisonAIAgents(
    agents=[researcher, writer],
    tasks=tasks,
    process="hierarchical",
    manager_llm="gpt-4o-mini",
    output="verbose",
)
team.start()

Which hierarchical?

Two flows share the hierarchical keyword — pick the one that matches your setup.

How It Works

The manager loops: it picks a task and agent, the worker runs it, and the loop repeats until the manager returns action="stop". Each turn the manager reads the goal and remaining tasks, returns a single {task_id, agent_name, action} object, and the framework runs the named agent on that task. When no work remains, the manager returns action="stop" and the team aggregates the results.

Return value

With process="hierarchical", .start(), .astart(), and .run() return the raw output of the last user-supplied task (in insertion order), never the Manager’s synthetic manager_task.

from praisonaiagents import Agent, Task, PraisonAIAgents

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

team = PraisonAIAgents(
    agents=[researcher, writer],
    tasks=[
        Task(name="research", description="Research AI trends", agent=researcher),
        Task(name="write", description="Write article", agent=writer),
    ],
    process="hierarchical",
    manager_llm="gpt-4o-mini",
)

# Default: the final delegated task's raw output (the article), NOT the Manager's string.
article = team.start()

# All task outputs keyed by task id, including the manager_task delegation trace.
all_outputs = team.start(return_dict=True)

The framework snapshots the real task ids before injecting the Manager, so:

The default single-value return is the last user task’s raw output.
A stale manager_task from a prior run of the same team is skipped — calling .start() twice no longer returns the previous run’s Manager output on the second call.
Pass return_dict=True to inspect every task’s TaskOutput, keyed by task id.
The Manager’s own generated content lives only in the delegation trace — run with output="verbose" to see it.

Prior to PraisonAI PR #3678, hierarchical runs returned the Manager agent’s own generic output instead of the final worker task’s result. If you were previously stripping the Manager preamble in application code, you can now remove that workaround.

The Manager’s Schema

The manager returns a fixed three-field object every delegation turn.

Field	Type	Required	Description
`task_id`	`int`	✅	Exact `task_id` from the tasks list (0-based). Never `manager_task`.
`agent_name`	`str`	✅	Name of the agent assigned to the task
`action`	`str`	✅	`"execute"` to run the task or `"stop"` to end the workflow

Invalid Selections & the Synthetic `manager_task`

The framework injects a synthetic manager_task for the manager’s own turn — it is never a delegable task, and rejection is enforced by id so you can safely name a real Task "manager_task".

Rule	What happens
Manager returns the synthetic `manager_task`’s id	Rejected; manager is re-prompted with only the delegable ids.
Manager returns an id not in the tasks list	Rejected; same re-prompt path.
Manager keeps returning invalid ids	After `MAX_INVALID_SELECTIONS = 3` attempts the workflow aborts and logs an error.
A user Task is named `"manager_task"`	Delegable as normal — the synthetic task is matched by id, not name.

Before PraisonAI PR #3706, ManagerInstructions.task_id was described as “1-based” while runtime ids are 0-based, and validation only checked membership in self.tasks — which let the manager delegate to itself and the real user task never ran. If you built a workaround (renaming tasks, wrapping the manager, patching response_format), you can remove it now.

OpenAI Strict-Mode Compatibility

Hierarchical process uses OpenAI’s strict structured-output API natively — no JSON fallback, no per-turn retry. Under the hood, every manager delegation turn asks the LLM for a fixed 3-field object:

Field	Type	Meaning
`task_id`	`int`	Exact `task_id` from the tasks list (0-based). Never `manager_task`.
`agent_name`	`str`	Name of the agent assigned to the task
`action`	`str`	`"execute"` to run the task, `"stop"` to end the workflow

The model (ManagerInstructions in praisonaiagents/process/manager_schema.py) sets extra="forbid", so its generated JSON schema includes additionalProperties: false — the exact shape OpenAI’s strict structured-output validator requires.

Before PraisonAI 2026-08-04, hierarchical runs on OpenAI models silently fell back to JSON-mode on every delegation turn, making runs 5–13× slower. If you added a local workaround (patching response_format, or forcing manager_llm="anthropic/..." to sidestep the issue), you can remove it — process="hierarchical" is now strict-native by default on any OpenAI model.

Manager LLM Choice

manager_llm is optional and defaults to the team’s LLM. A cheaper model is a good default for the manager, because it only picks the next task and agent — it does not do the work.

from praisonaiagents import Agent, Task, PraisonAIAgents

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

team = PraisonAIAgents(
    agents=[researcher, writer],
    tasks=[
        Task(name="research", description="Research AI trends", agent=researcher),
        Task(name="write", description="Write article about AI trends", agent=writer),
    ],
    process="hierarchical",
    manager_llm="gpt-4o-mini",
)
team.start()

Common Patterns

Three realistic setups where a manager delegates by name.

Research → Write → Review
Collect → Analyse → Report
Triage → Respond

from praisonaiagents import Agent, Task, PraisonAIAgents

researcher = Agent(name="researcher", role="Research topics")
writer = Agent(name="writer", role="Write content")
reviewer = Agent(name="reviewer", role="Review and improve content")

team = PraisonAIAgents(
    agents=[researcher, writer, reviewer],
    tasks=[
        Task(name="research", description="Research AI trends", agent=researcher),
        Task(name="write", description="Write an article on the research", agent=writer),
        Task(name="review", description="Review and polish the article", agent=reviewer),
    ],
    process="hierarchical",
    manager_llm="gpt-4o-mini",
)
team.start()

from praisonaiagents import Agent, Task, PraisonAIAgents

collector = Agent(name="collector", role="Collect raw data")
analyst = Agent(name="analyst", role="Analyse the data")
reporter = Agent(name="reporter", role="Write the report")

team = PraisonAIAgents(
    agents=[collector, analyst, reporter],
    tasks=[
        Task(name="collect", description="Collect sales figures", agent=collector),
        Task(name="analyse", description="Analyse trends in the figures", agent=analyst),
        Task(name="report", description="Write a summary report", agent=reporter),
    ],
    process="hierarchical",
    manager_llm="gpt-4o-mini",
)
team.start()

from praisonaiagents import Agent, Task, PraisonAIAgents

triager = Agent(name="triager", role="Classify incoming requests")
responder = Agent(name="responder", role="Draft a response")

team = PraisonAIAgents(
    agents=[triager, responder],
    tasks=[
        Task(name="triage", description="Classify the support ticket", agent=triager),
        Task(name="respond", description="Draft a reply to the ticket", agent=responder),
    ],
    process="hierarchical",
    manager_llm="gpt-4o-mini",
)
team.start()

Best Practices

Use a cheaper manager_llm

The manager only picks the next (task_id, agent_name, action) — it does not do the actual work. gpt-4o-mini (or an equivalently cheap model on another provider) is a good default.

Give tasks descriptive names

The manager delegates by agent_name and picks tasks by task_id. A clear task description helps the manager reason about ordering.

Do not set response_format on manager_llm

The framework already asks for the strict ManagerInstructions schema and OpenAI accepts it natively. Overriding response_format re-introduces the JSON fallback.

output="verbose" shows delegation turns

When debugging why the manager stops early, run with output="verbose" and read the {task_id, agent_name, action} payloads emitted on each turn.

Hierarchical Workflows

The AgentFlow variant, where a manager validates each step.

Agents

The underlying Agent class.

Tasks

The Task class the manager delegates.

Process

The process-mode concept page.

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 Process

Quick Start

Which hierarchical?

How It Works

Return value

The Manager’s Schema

Invalid Selections & the Synthetic `manager_task`

OpenAI Strict-Mode Compatibility

Manager LLM Choice

Common Patterns

Best Practices

Hierarchical Workflows

Agents

Tasks

Process

​Quick Start

​Which hierarchical?

​How It Works

​Return value

​The Manager’s Schema

​Invalid Selections & the Synthetic manager_task

​OpenAI Strict-Mode Compatibility

​Manager LLM Choice

​Common Patterns

​Best Practices

​Related

Hierarchical Workflows

Agents

Tasks

Process

Quick Start

Which hierarchical?

How It Works

Return value

The Manager’s Schema

Invalid Selections & the Synthetic `manager_task`

OpenAI Strict-Mode Compatibility

Manager LLM Choice

Common Patterns

Best Practices

Related