Hierarchical Process

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

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 verbose=True 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",
    verbose=True,
)
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.

The Manager’s Schema

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

Field	Type	Required	Description
`task_id`	`int`	✅	1-based index of the task to run next
`agent_name`	`str`	✅	Name of the agent assigned to the task
`action`	`str`	✅	`"execute"` to run the task or `"stop"` to end the workflow

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`	1-based index of the task to run next
`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.

verbose=True shows delegation turns

When debugging why the manager stops early, run with verbose=True 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

The Manager’s Schema

OpenAI Strict-Mode Compatibility

Manager LLM Choice

Common Patterns

Best Practices

Hierarchical Workflows

Agents

Tasks

Process

​Quick Start

​Which hierarchical?

​How It Works

​The Manager’s Schema

​OpenAI Strict-Mode Compatibility

​Manager LLM Choice

​Common Patterns

​Best Practices

​Related

Hierarchical Workflows

Agents

Tasks

Process

Quick Start

Which hierarchical?

How It Works

The Manager’s Schema

OpenAI Strict-Mode Compatibility

Manager LLM Choice

Common Patterns

Best Practices

Related