subgraphs-and-composition-in-langgraph

Subgraphs and Composition in LangGraph

Purpose

This skill provides guidance on building modular LangGraph applications through subgraph composition. Subgraphs enable you to create reusable, independently testable workflow components that can be composed into complex multi-agent systems with clear boundaries and explicit state contracts.

Compatibility

This skill is compatible with LangGraph 1.x (tested with v1.0.6, January 2026).

When to Use This Skill

Use this skill when:

• Building large multi-agent systems that benefit from modular decomposition
• Creating reusable workflow components across multiple applications
• Managing complex state relationships between parent and child workflows
• Isolating specific functionality for independent testing and optimization
• Scaling teams working on different parts of a workflow system
• Implementing hierarchical agent architectures with specialized sub-agents

Core Concepts

1. Subgraph as Node

A compiled StateGraph can be added as a node to another graph. Compiled graphs are callable, making them valid node functions:

from langgraph.graph import StateGraph, START, END, MessagesState

def create_sentiment_subgraph():
    subgraph = StateGraph(MessagesState)
    subgraph.add_node("analyze", analyze_sentiment)
    subgraph.add_edge(START, "analyze")
    subgraph.add_edge("analyze", END)
    return subgraph.compile()

# Add compiled subgraph as a node
chatbot = StateGraph(MessagesState)
chatbot.add_node("sentiment", create_sentiment_subgraph())
chatbot.add_edge(START, "sentiment")
chatbot.add_edge("sentiment", "respond")
chatbot.add_edge("respond", END)

2. Shared State Schema Communication

Parent and child graphs can share the same state schema for seamless communication:

from langgraph.graph import MessagesState
from langchain_core.messages import SystemMessage

def analyze_sentiment(state: MessagesState) -> dict:
    last_message = state["messages"][-1].content.lower()
    sentiment = "positive" if "happy" in last_message else "neutral"
    return {"messages": [SystemMessage(content=f"[Sentiment: {sentiment}]")]}

# Both parent and child use MessagesState - no transformation needed
subgraph = StateGraph(MessagesState)
subgraph.add_node("analyze", analyze_sentiment)

parent = StateGraph(MessagesState)
parent.add_node("sentiment", subgraph.compile())  # Direct usage