Registry / llm-agents / langgraph-supervisor

langgraph-supervisor

JSON →
library0.0.31pypypi✓ verified 22d ago

LangGraph Supervisor is a Python library that simplifies building hierarchical multi-agent systems using LangGraph. It provides a central supervisor agent responsible for orchestrating specialized worker agents, managing communication flow, and delegating tasks. The library is currently in version 0.0.31 and receives frequent updates, indicating active development.

pip install langgraph-supervisor langchain-openai
INSTALL
IMPORT
SIG · LANGGRAPH-SUPERVIS
L
langgraph-supervisor
llm-agentspythonv0.0.31
Install
10.3s avg
Import
3020ms
Disk
111MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.0.31 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✓ —
✓ 12.8s
py 3.11
✓ —
✓ 10.7s
py 3.12
✓ —
✓ 8.9s
py 3.13
✓ —
✓ 9s
py 3.9
✕ build_error
✕ build_error
111MB installed
● package 111MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

create_supervisor
from langgraph_supervisor import create_supervisor
ChatOpenAI
from langchain_openai import ChatOpenAI
Required if using OpenAI models for the supervisor or agents.
create_react_agent
from langgraph.prebuilt import create_react_agent
Commonly used to create worker agents managed by the supervisor.

This quickstart demonstrates how to create two specialized agents (a math expert and a research expert) and then orchestrate them using `create_supervisor`. The supervisor uses an LLM to decide which agent to hand off tasks to based on the user's input.

import os from langchain_openai import ChatOpenAI from langgraph_supervisor import create_supervisor from langgraph.prebuilt import create_react_agent from langgraph.graph import END # Set your OpenAI API key from environment variable os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "") # Initialize the LLM for agents and supervisor model = ChatOpenAI(model="gpt-4o") # Define simple tools def add(a: float, b: float) -> float: """Add two numbers.""" return a + b def web_search(query: str) -> str: """Search the web for information.""" # Placeholder for actual web search functionality return f"Found results for '{query}': Example search data." # Create specialized agents math_agent = create_react_agent( model=model, tools=[add], name="math_expert", ) research_agent = create_react_agent( model=model, tools=[web_search], name="research_expert", ) # Create supervisor workflow # The prompt parameter defines the supervisor's role and how to delegate. workflow = create_supervisor( [research_agent, math_agent], model=model, prompt=( "You are a team supervisor managing a research expert and a math expert. " "For research tasks, use research_agent. " "For math tasks, use math_agent." ), ) # To add memory and enable longer conversations, you would typically use a StateGraph and add checkpointing. # For this quickstart, we'll compile and run a single turn. app = workflow.compile() # Example invocation result = app.invoke({ "messages": [ { "role": "user", "content": "What is 10 + 5 and what's the capital of France?" } ] }) print(result["messages"][-1].content)
Debug
Known issues
deprecatedThe LangGraph team now recommends implementing the 'supervisor pattern directly via tools' for most use cases, rather than using this dedicated `langgraph-supervisor` library. This library may be less actively maintained or receive fewer new features compared to the manual approach.
fix
Refer to the LangChain multi-agent guide and supervisor tutorial for implementing the pattern directly with LangGraph's core features. Consider if this library uniquely solves a problem not easily addressed by the manual pattern.
affects: All versions (strategic recommendation change)
breakingIn versions 0.0.26 and earlier, the `state_schema` parameter for `create_supervisor` defaulted to `AgentState`. From 0.0.26 onwards, it defaults to `None`. If your application relied on the implicit `AgentState`, you might experience issues.
fix
Explicitly define and pass a `state_schema` to `create_supervisor` if you need a specific schema, or ensure your graph state is compatible with the new default behavior.
affects: >=0.0.26
gotchaThe library is in `0.0.x` versions, indicating that the API is not yet stable. Breaking changes and significant shifts in functionality can occur without major version bumps.
fix
Pin your dependency to a specific patch version (`==0.0.X`) rather than using caret (`^`) or tilde (`~`) ranges in your `pyproject.toml` or `requirements.txt` to avoid unexpected breakage during minor updates.
affects: All 0.0.x versions
breakingVersion 0.0.31 includes a fix for `v1 ToolNode compat`, suggesting prior versions might have had compatibility issues with the `ToolNode` structure introduced in `langgraph` v1.x.
fix
Upgrade to `langgraph-supervisor==0.0.31` or higher to ensure compatibility with `langgraph`'s `ToolNode`.
affects: <0.0.31
gotchaLangGraph Supervisor requires Python version 3.10 or higher. Using older Python versions will result in installation or runtime errors.
fix
Ensure your development and deployment environments are running Python 3.10 or a newer compatible version.
affects: All versions
Upgrade
Version history
0.0.31latest on PyPI · released Nov 19, 2025
Audit
Dependencies
langgraphrequiredCore framework for building agent applications.
langchain-corerequiredUnderlying LangChain utilities.
langchain-openaioptionalCommonly used for the supervisor's language model in examples.
Agent activity
35 hits · last 30 days
node
32
Amazon
1
OpenAI (training)
1
Resources