langgraph-hierarchies 0.0.2

LangGraph abstractions for hierarchical multi-agent systems

langgraph-hierarchies

Status: early development (0.0.x). API and scope are not stable. v0.1 will ship the keystone slice below.

Stateful, deeply-nested compiled-subgraph agent hierarchies on LangGraph — with declarative per-subchain state isolation and supervisor-controlled iteration safety.

Flat delegation (Deep Agents, supervisor handoffs) is a good starting point. This library targets the production wall past that: recursive hierarchies where subagents are real compiled subgraphs, with explicit clear/merge/discard policy across state fields — not ephemeral task-tool isolation alone.

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, SubchainPolicy
Nesting	Multi-level supervisors	Fan-out / data recursion (partial); not stateful deep trees	Recursive compiled subgraphs + declarative state policy
Best for	Quick hierarchical routing	General long-horizon agents	Production-grade deep hierarchies with accountability

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.

Compatibility

langgraph-hierarchies	langgraph
0.0.x	1.2.6 (pinned; see releases)

Regression tests gate version bumps. A pair is listed here only once the full suite is green for it.

Bumping the langgraph pin

1. Update the langgraph constraint in pyproject.toml.
2. Refresh the lockfile: uv sync.
3. Run the full suite: uv run pytest.
4. To isolate a failing story, run e.g. uv run pytest -m us04.
5. When the suite is green, update the compatibility matrix above and cut a release.

CI runs ruff and pytest on every push/PR (Python 3.10–3.13). Tests use scripted models only — no LLM API keys required.

What's in 0.0.2

• BaseGraph / CompiledGraph + phased compilation
• SubchainPolicy (entry snapshot, clear/merge/discard, exit restore)
• ReactGraph + iteration safety (per-agent limits, supervisor task_iterations, forced-exit report)
• Root compile (compile_as_root) and unified invocation
• Compatibility harness (per-story pytest markers, CI)
• TodoGraph + todo toolkit; IRS hierarchy example in repo (examples/irs_reporting/)

Planner/Executor, progress tracking, HITL: follow-on after v0.1.

Install

pip install langgraph-hierarchies

Requires Python ≥3.10 (matches LangGraph).

Development

Uses uv (same toolchain as upstream LangGraph):

uv sync
uv run pytest
uv build   # sdist + wheel for PyPI

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.

Contact

• Bug reports & feature requests: GitHub Issues

License

MIT — see LICENSE.