How langchain-ai/langgraph-supervisor-py works
Project Type & Purpose
• This is an open-source Python library that builds on top of LangGraph to create hierarchical multi-agent systems.
• It provides core modules for defining a supervisor agent, specialized sub-agents, and a tool-based handoff mechanism.
High-Level Components
From your code and README, identify these main blocks:
A. User Application (Top Layer)
– Code that imports langgraph_supervisor and langgraph APIs.
– Constructs specialized agents (React or Functional API) and a supervisor workflow.
– Calls .compile() and invokes the resulting application.
B. langgraph_supervisor Library (Core Layer)
– supervisor.py: create_supervisor() function, orchestrates a StateGraph with sub-graphs for each agent.
– handoff.py: Default and custom handoff tool definitions (create_handoff_tool) for message‐based delegation.
– agent_name.py: Utilities to manage/resolve agent names in the graph.
C. LangGraph & LangChain Integration (Framework Layer)
– Underlying graph engine (StateGraph, Command, InjectedState).
– Prebuilt React‐style agents from LangGraph (create_react_agent).
– Functional API decorators (@task, @entrypoint).
D. External Services & Data Stores
– LLM Provider: e.g. OpenAI API (via ChatOpenAI).
– Tool Endpoints: Web search function or any custom Python tool.
– Memory/Checkpoint Store (optional): In-memory or persistent store for histories.
Relationships & Data Flow
1. User Application ➔ calls create_react_agent/@entrypoint ➔ defines Agent Sub-graphs.
2. User Application ➔ calls create_supervisor(agents, …) ➔ builds a Supervisor Graph.
3. Supervisor Graph
– Maintains global state["messages"] and state["active_agent"].
– Exposes handoff tools that the LLM can “call” to switch context to sub-agents.
4. Agent Sub-graphs
– Receive messages, call the LLM provider or custom tools.
– Return responses to the supervisor graph via Command.
5. Compile & Invoke
– .compile() wires everything into a runnable app object.
– .invoke({"messages": [...]}) kicks off the supervisor entrypoint.
6. Optional Memory
– During compile, user can inject a checkpointer or store which the graph uses to persist state.
Architectural Patterns & Principles
• Hierarchical Multi-Agent: A tree of graphs (supervisor ➔ sub-agents ➔ optional sub-supervisors).
• Tool-Based Delegation: Supervisor uses first-class tool calls to hand off tasks.
• Functional vs Graph API: Your library supports both declarative graph definitions and decorator-based tasks.
• Separation of Concerns:
– Supervisor logic vs Agent logic vs Tool implementations.
– State management abstracted in LangGraph’s StateGraph.
Final Checklist
– Clear component names matching module/file names.