Getting started
Overview
Decomposable agent hierarchies for LangGraph — recursive compiled subgraphs with declarative context isolation.
Status: early development (0.0.x). API and scope are not stable. v0.1 will ship the keystone slice described below.
An agentic system is decomposable when it can be split into finer agentic systems — each developed, run, and evaluated in isolation, with its own context — that still achieve the goal of the whole. Decomposability in AI workflows explains why that matters: lean context per unit, benchmarkable seams, durable checkpoints, and improvements that stop colliding across stages.
langgraph-hierarchies is the library for building that on LangGraph: recursive hierarchies of real compiled subgraphs, with declarative per-subagent context isolation (SubagentPolicy), supervisor-controlled iteration budgets, and artifact handoff across boundaries — not one swelling monolith, not ephemeral task-tool isolation alone.
Flat delegation (supervisor handoffs, Deep Agents) is a good starting point. This library targets the production wall past that: invokable subagents that nest as deep as the problem needs while preserving streamability, durability, and resumability at every level.
Get started
Install the package and run a minimal parent/child hierarchy in under five minutes.
How this relates to other libraries
| langgraph-supervisor | Deep Agents | langgraph-hierarchies | |
|---|---|---|---|
| Model | Supervisor → workers (handoff tools) | Harness + subagents (task / programmatic task()) | Class-as-factory graphs, phased compile, SubagentPolicy |
| Context isolation | Shared parent history | Ephemeral subagent context | Declarative clear/merge/discard per subagent boundary |
| Nesting | Multi-level supervisors | Fan-out / data recursion (partial); not stateful deep trees | Recursive compiled subgraphs + explicit state policy |
| Best for | Quick hierarchical routing | General long-horizon agents | Production decomposable hierarchies — benchmarkable units, lean checkpoints |
Deep Agents already covers fan-out, parallel orchestration, and RLM-style recursion over data (programmatic subagents, June 2026). This project does not try to replace that.
What’s in 0.0.2
The mechanics behind decomposable hierarchies:
BaseGraph/CompiledGraph+ phased compilation — each unit is a real invokable subgraphSubagentPolicy— entry snapshot, clear/merge/discard, exit restore; isolate context at every seamReactGraph+ iteration safety — per-agent limits, supervisortask_iterations, forced-exit report- Root compile (
compile_as_root) and unified invocation — stream and checkpoint through the full tree - Compatibility harness (per-story pytest markers, CI) — benchmark units in isolation
TodoGraph+ todo toolkit — batch processing with flat context; IRS hierarchy example in the repository
Planner/Executor, progress tracking, and HITL are follow-on after v0.1.
Examples
Worked examples live in langgraph-hierarchies-examples, a companion repository that tracks the published library releases:
- Example 01 — Monolith — one agent, one flat
messageslist; the “before” picture - Example 02 — Artifact Handoff — root orchestrator delegates to specialist children;
SubagentPolicyclears messages on entry and merges onlypipeline_artifacton exit
Disclaimer
This project is not affiliated with, endorsed by, or maintained by LangChain or the LangGraph team. “LangGraph” is a trademark of LangChain; this package name indicates compatibility with the LangGraph runtime, not official status.