TAI BUI
Back to curriculum
LearnPython

Hierarchical Architecture and Its Failure Mode

Hierarchical is supervisor nested: manager agents over sub-managers over workers. CrewAI `Process.hierarchical` is the textbook version, where a `manager_llm` delegates tasks dynamically and validates outputs. The LangGraph equivalent is `create_supervisor(create_supervisor(...))`. It fits when the task really is an org chart. It is also the pattern most likely to collapse into managerial looping, because manager agents assign work poorly, misread sub-outputs, or fail to reach consensus. Sequential often beats it.

TIME: ~60 minutesPREREQUISITES: Phase 16 · 05 (Supervisor Pattern)

Learning Objectives

  • Explain why an LLM manager re-deriving the org chart each turn makes hierarchies fragile
  • Name the three failure modes of hierarchical systems: task assignment error, output misinterpretation, and consensus loops
  • Decide whether a task needs a hierarchical, sequential, or flat supervisor design
  • Trace how a bad decomposition propagates to the top synthesis by running the demo
  • Apply the Ship It guardrails: depth cap, reconciliation budget, provenance, and drift alerts

Problem

Once the supervisor pattern clicks, the next question is what happens when the workers are themselves supervisors. Teams have sub-teams and companies have departments of departments, so hierarchical architectures copy that shape.

The catch is that an LLM manager is not a human manager. A human manager carries stable priors about what their reports know. An LLM manager re-reasons the org chart every turn from whatever sits in its context. A small drift in that context can send work to the wrong place all the way down the tree.

Warm-up0/3
1. In the supervisor pattern from Phase 16 · 05, what does the supervisor do with worker results?Warm-up
A Supervisor box with arrows to three Worker boxes, each marked done. A dashed box below asks what the supervisor does with the three results.
Typed schematic; recap of the supervisor pattern.
2. A single supervisor decomposes a task badly and sends a worker the wrong subtask. What is the most likely result?Warm-up
Two stacked boxes: the task given to the supervisor is to review marketing copy, but the subtask it sends the worker is to format a slide deck. A dashed box asks what happens next.
Typed schematic; the mismatch is drawn, the outcome is not.
3. A department head collects reports from the team and hands the executive one combined summary. What is the main benefit?Warm-up
Four Report boxes feed into one Department Head box, which sends a single arrow to an Executive box. A line asks what the benefit is, with a question mark.
Typed schematic; four reports funnel into one summary.
Check: Problem0/1
1. Why does an LLM manager behave differently from a human manager in a hierarchy?Explain
A Human manager box and an LLM manager box, each with an arrow to a shared org chart box. The human's box says stable priors with a question mark; the LLM's box is just a question mark.
Typed schematic.

Concept

The shape

                 Manager
                 ┌─────┐
                 └──┬──┘
           ┌────────┴────────┐
           ▼                 ▼
       Sub-Mgr A         Sub-Mgr B
       ┌─────┐           ┌─────┐
       └──┬──┘           └──┬──┘
         ┌┴──┬──┐          ┌┴──┐
         ▼   ▼  ▼          ▼   ▼
       W1  W2  W3         W4  W5

Every internal node plans, delegates, and synthesizes. The leaves do the actual work.

Where it shines

  • Clear org mapping. If the real task is departmental ("legal review the doc, finance review the doc, engineering review the doc, then summarize for exec"), the hierarchy is explicit.
  • Local summarization. Each sub-manager synthesizes its team's output before the top manager sees it. Top manager sees three sub-manager summaries, not fifteen worker outputs.

Where it breaks

The 2026 post-mortems on these systems keep finding the same three failure modes:

  1. Task assignment error. The manager reads the goal, hallucinates a decomposition, and delegates to the wrong sub-manager. The sub-manager works on whatever it was given, so the error only surfaces at the top synthesis, one level removed from where a human could have caught it.
  2. Output misinterpretation. Sub-manager returns "unable to verify claim X." Top manager summarizes as "claim X not confirmed." Meaning drifts a little at each level.
  3. Consensus loops. Two sub-managers disagree; top manager asks them to reconcile; they re-delegate down; workers re-run; sub-managers return slightly different answers; loop. CrewAI's Process.hierarchical guards against this with step limits, but then the limit is a hyperparameter you have to tune.

The deciding question

Sequential (linear pipeline) or hierarchical comes down to one question: does the task have independent sub-teams, or is it one linear flow pretending to be a tree? If it is a linear flow, use sequential. If the sub-teams are independent, use hierarchical and budget explicit reconciliation rules.

CrewAI's implementation

Process.hierarchical wires a manager LLM over specialist crews. The manager:

  • receives the top-level task,
  • assigns subtasks to crews,
  • evaluates crew outputs,
  • decides whether to accept, re-delegate, or iterate.

Documentation: https://docs.crewai.com/en/introduction (look for "Hierarchical Process" under Core Concepts).

LangGraph's implementation

LangGraph uses nested create_supervisor calls. The inner supervisor has its own graph; the outer supervisor treats the inner graph as an opaque node. This is easier to debug than CrewAI because you can step through each graph separately, but it is harder to express dynamic reshaping of the tree.

Reference: https://reference.langchain.com/python/langgraph-supervisor.

Check: Concept0/14
1. What does a hierarchical multi-agent architecture look like?Define
A tree of boxes: one Manager box at the top branches to two Sub-Manager boxes, A and B, each of which branches further to worker boxes (three under A, two under B) at the bottom.
Generic names only; matches the Concept section's own diagram.
2. What is the job of a manager LLM at an internal node of the tree?Define
The same tree with Sub-Mgr A highlighted. An arrow arrives from Manager above and two arrows leave toward its own workers below. A label under it reads job, with a question mark.
Only the position of the internal node is marked; what it does is left open.
3. What is decomposition drift?Define
A User's question box feeds a Manager box, which sends three arrows to three Piece boxes. A dashed line below asks for the term for the split drifting apart from the question, with a question mark.
Typed schematic.
4. What is a reconciliation loop?Define
Top Manager connected by two-way arrows to Sub-Mgr A and Sub-Mgr B, labelled disagree. A dashed box below asks how many rounds this continues for.
Typed schematic.
5. Which framework feature is the textbook hierarchical implementation, with a manager_llm that delegates and validates?Define
Four rows, one per framework (LangGraph, CrewAI, AutoGen, OpenAI Swarm), each with a dashed box asking for its feature, marked with a question mark.
Framework names only; no feature is filled in.
6. Which of these is NOT one of the three failure modes named in Where it breaks?Define
A 2x2 grid of four dashed candidate boxes, each marked with a question mark, with a note that three come from the lesson's failure-mode list and one does not.
No names are placed in the boxes.
7. What guardrail does CrewAI's Process.hierarchical apply against consensus loops, and what is its cost?Explain
A Process.hierarchical box beside a dashed box asking for its guardrail, with a second dashed box below asking for that guardrail's cost.
Typed schematic.
8. According to Where it shines, when does a hierarchy work well?Explain
Three department boxes, Legal, Finance and Engineering, each over its own Sub-Manager box, all feeding a Top Manager box. A line asks when this fits well, with a question mark.
Typed schematic of an org-chart shaped task.
9. How do nested LangGraph supervisors compare with CrewAI hierarchical for debugging?Explain
A CrewAI box and a LangGraph box side by side, each with a dashed box underneath asking about debugging, marked with a question mark.
Typed schematic; neither debugging tradeoff is filled in.
10. Why does a task assignment error usually surface only at the top synthesis?Explain
A top manager's task and the forwarded subtask differ. One dashed box asks whether the mismatch is visible at the top; a second dashed box leaves Sub-Mgr A's own result unlabeled.
Typed schematic.
11. Which question separates a sequential design from a hierarchical one?Explain
Two rows of boxes: a linear chain, extract then clean then summarize, and three independent boxes, legal, finance, engineering. A dashed box asks for the deciding question between the shapes.
Typed schematic of the two shapes.
12. A sub-manager returns "unable to verify claim X" and the top manager reports "claim X not confirmed." Which failure mode is this?Analyze
A sub-manager's line, unable to verify claim X, with an arrow to a top manager's line, claim X not confirmed. A dashed box below asks which failure mode this is.
The two quoted lines are the lesson's own example.
13. Your team wants to build a pipeline where extraction feeds cleaning, cleaning feeds summarizing, and each step needs the previous output. A colleague proposes a three-level manager tree. What do you recommend?Design
A linear chain, extraction then cleaning then summarizing, above a dashed region labelled the colleague's proposal of a 3-level manager tree. A dashed box below asks for a recommendation.
The three-step dependency and the colleague's proposal are both from the question.
14. You need to step through each sub-team separately when debugging, and you rarely reshape the tree at runtime. Which implementation fits?Design
Two requirement boxes, stepping through each sub-team alone and rarely reshaping the tree at runtime. A dashed box below asks for the matching implementation.
Restates the requirements given in the question.

Build It

main.py runs a 3-level hierarchy:

  • top manager: delegates a task to branches by label (engineering, legal, finance),
  • engineering sub-manager: splits into "frontend" and "backend" workers,
  • legal and finance sub-managers: one worker each.

The workers return canned answers, so no LLM is involved. The demo contrasts a happy path, where the top manager picks engineering and legal, with a perturbed path where the branch list says finance instead of legal. That label swap is hard-coded in the call to top.run. It stands in for a bad decomposition. The finance sub-manager does finance work, the top synthesis reports finance findings, and the legal question goes unanswered.

Run:

python3 code/main.py

The output prints each path as a tree of sub-managers, leaf questions, and leaf answers, ending in the top synthesis, so you can compare what was asked against what was delivered.

Check: Build It0/7
1. In the Build It perturbed path, what triggers the cascading error?Apply
A code panel showing the perturbed call, top.run with branch_labels engineering and finance, above the real tree: top, eng-manager, legal-manager and finance-manager, each with their workers. A line asks what goes wrong.
The call is real code from main.py; the tree below shows every sub-manager that exists.
2. In main.py, top.run is called with branch_labels ["engineering", "legal"]. How many leaf workers answer?Apply
A code panel with top.run called with branch_labels engineering and legal, above the real tree with eng-manager and legal-manager highlighted and finance-manager drawn faint.
The call is real code; count the highlighted leaf boxes to answer.
3. In main.py, top.run is called with branch_labels ["engineering", "payments"]. What does the result hold for "payments"?Apply
A code panel with top.run called with branch_labels engineering and payments, a note that the known branches are engineering, legal and finance, and that payments is not one of them. A dashed box asks what the result holds for payments.
The call and the known branch names are real; the outcome is left open.
4. In main.py, which question does the lawyer worker receive when the label is "legal"?Apply
A code panel showing legal-manager's split dictionary with the key lawyer and its value hidden as a question mark. A dashed box asks what question the lawyer worker actually receives.
The dictionary key is real code; its value is hidden.
5. In the perturbed run of main.py, what does the second branch of the top synthesis contain?Apply
A code panel with the perturbed call, above a filled box for branch 1, eng-manager summary, and a blank dashed box for branch 2, labelled finance-manager underneath.
The call is real code; branch 2's text is hidden.
6. In the perturbed run, eng-manager and finance-manager both return clean results. Where was the mistake made, and where does it first show?Analyze
Two boxes, eng-manager and finance-manager, both returning clean results, both feeding a top synthesis box. A dashed box below asks where the mistake was made and where it first shows.
Restates the scenario given in the question.
7. Why is swapping "legal" for "finance" harder to catch than asking for a nonexistent "payments" branch?Analyze
Two code panels side by side: one swaps legal for finance, the other asks for an unknown branch called payments. A dashed box below asks which one is harder to notice went wrong.
Both calls are the real forms used elsewhere in main.py.

Use It

outputs/skill-hierarchy-fitness.md evaluates whether a given task should use hierarchical, sequential, or flat supervisor. It takes a task description, an org structure, and a reconciliation budget, and returns a pattern recommendation along with the failure modes to guard against.

Ship It

If you ship hierarchical:

  • Cap tree depth at 2. Three levels already hide most errors from observability.
  • Set an explicit reconciliation budget. Fix the max rounds before the top manager must commit. Usually 2.
  • Put provenance on every synthesis. Each node's summary should cite which leaf outputs produced it.
  • Alert on decomposition drift. Log the manager's decomposition per step and diff it against the user query. If the decomposition stops covering the query, fire an alert.
Check: Ship It0/9
1. What is the depth-2 ceiling?Define
A stack of four rows, each one level deeper and with more boxes, labelled level 1 to level 4. A dashed line with a question mark sits between level 2 and level 3.
Typed schematic of tree depth.
2. What is a canary question?Define
The tree from the Concept section with worker W2 highlighted and labelled special, question mark. Nothing else about W2 is drawn.
Typed schematic.
3. What is a provenance chain?Define
A Top synthesis box sits above three separate Leaf boxes with no connecting lines. A dashed box below asks for the term provenance chain.
Typed schematic; the boxes are deliberately left unconnected.
4. What tree-depth cap do the Ship It guardrails recommend?Define
Five stacked rows for tree depths 1 through 5, each with more boxes than the last, and a dashed vertical line of unspecified position labelled cap, question mark.
Typed schematic of tree depth.
5. What does Ship It say about the reconciliation budget?Define
Five round boxes in a row, with a dashed box below asking after how many rounds the top manager must commit.
Typed schematic.
6. Why should each node's summary cite the leaf outputs that produced it?Explain
A top synthesis box reading claim X, connected to three leaf boxes by dashed lines. A dashed label asks whether the claim can be traced back to a leaf.
Typed schematic.
7. Two sub-managers keep returning slightly different answers. The top manager keeps re-delegating, and cost climbs without a final answer. Which ingredient is missing?Analyze
Four round boxes in a row, cost climbing, with a note that there is no final answer yet, and a dashed box below asking which ingredient is missing.
Restates the scenario given in the question.
8. A shipped hierarchy answers a finance question when users asked about legal, and no error is logged. Which guardrail from Ship It would have caught it?Analyze
A box for what the user asked, legal review, beside a box for what the system answered, finance review, with a note that no error is logged. A dashed box below asks which Ship It guardrail would have caught this.
Restates the scenario given in the question.
9. Legal, finance and engineering must review a launch independently, then an exec summary is needed. Stakeholders fear a bad split will go unnoticed. Which design fits?Design
Three boxes, Legal, Finance and Engineering, with a note that they review independently and one exec summary is needed, and a fear that a bad split goes unnoticed. A dashed box asks for the design.
Restates the scenario given in the question.
Author's Note

I'd run main.py and read the two outputs side by side before reading anything else. The failure it shows is quiet. In the perturbed run the finance branch returns a clean, confident answer, and nothing in the top synthesis string says the legal question was never asked.

Keep the toy in proportion, though. The workers return canned strings and the "bad decomposition" is a list I typed into the call, so it shows how an error propagates but says nothing about how often a real manager LLM makes one. The finance branch also exists in the hierarchy. If you ask for a branch that doesn't, the top manager records a MISSING entry, which is at least visible. A wrong label that maps to a real sub-manager gets no such signal.

If I were building this for real, the first thing I'd add is the canary worker from the exercises. A worker that always sees the original query gives you something to compare the synthesis against, which is the check the code is missing.

Exercises

  1. Run code/main.py and compare happy vs perturbed. How many levels of manager hand-off does it take before the top output fully diverges from the user's question?
  2. Add a third level (top → sub → sub-sub → worker). Measure how often the perturbed path corrects itself vs fully diverges as depth grows.
  3. Implement a "canary" worker at each sub-manager that is always asked the original user question unchanged. Use the canary answer to detect decomposition drift. How should the manager react when the canary disagrees with the synthesized answer?
  4. Read CrewAI's Process.hierarchical docs. Identify one concrete guardrail CrewAI applies (step limit, manager_llm constraint) and describe what failure mode it targets.
  5. Compare nested LangGraph supervisors to CrewAI hierarchical. Which makes reconciliation loops cheaper to detect?

Key Terms

TermWhat people sayWhat it actually means
Hierarchical"Org chart pattern"Supervisors over supervisors; only leaves do work.
Manager LLM"The boss"The LLM that decomposes, assigns, and validates at an internal node.
Decomposition drift"The boss lost the plot"Top manager's split no longer covers the original question.
Reconciliation loop"Endless meetings"Sub-managers disagree; top re-delegates; workers re-run; loop until budget exhausted.
Depth-2 ceiling"Don't go deeper than 2 levels"Empirical guardrail: 3+ levels collapses observability.
Canary question"Ground truth at every level"A worker that is always asked the original query unchanged, to detect drift.
Provenance chain"Who said what"Trace from each synthesis back to the leaf outputs that produced it.

Further Reading

Code

Ships With