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
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.fixRefer 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.fixExplicitly 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.fixPin 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.fixUpgrade 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.fixEnsure 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.