• Custom state fields (documents, metadata, user preferences, iterations, etc.)
• Complex multi-agent or supervisor workflows
• Advanced state management with custom reducers
• RAG pipelines with retrieved context
• Long-running agents that need memory beyond messages
• Production-grade, maintainable applications

from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import MessagesState
from typing import Annotated

class AgentState(MessagesState):          # Inherit from MessagesState
    documents: list[dict] = []
    iterations: int = 0
    next_agent: str | None = None

graph = StateGraph(AgentState)

graph.add_node("agent", agent_node)
graph.add_node("tools", ToolNode(tools))
graph.add_node("retriever", retrieval_node)

graph.add_edge(START, "agent")
graph.add_conditional_edges("agent", route_tools)
graph.add_edge("tools", "agent")
graph.add_edge("retriever", "agent")

• Building quick prototypes or simple chatbots
• You only need basic conversation flow
• You want the absolute minimum code
• You don’t need any state beyond message history
• You are experimenting or teaching basics

Migrating from MessageGraph to StateGraph

# Before (MessageGraph)
from langgraph.graph import MessageGraph

graph = MessageGraph()
graph.add_node("agent", agent_node)
graph.set_entry_point("agent")

class AgentState(MessagesState):    # Extend MessagesState
    documents: list = []
    iterations: int = 0

graph = StateGraph(AgentState)

• Prefer StateGraph(MessagesState) over MessageGraph
• Always define your state using TypedDict or Pydantic
• Use Annotated + reducers for all state fields
• Keep custom state fields minimal and purposeful
• Use Command for clean routing + state updates
• Always add checkpointers (MemorySaver or persistent)
• Implement safety limits in all cycles
• Stream outputs (stream_mode="messages") for better UX

• Shared memory across multiple agents
• Retrieved documents and context
• Iteration tracking and safety controls
• Supervisor / orchestrator logic
• Persistent custom data (user profiles, preferences, etc.)
• Complex routing and stateful decision making

• Hard to maintain
• Loses type safety
• Difficult to debug
• Breaks when you need to scale

def agent_node(state):  # state = list[Message]
    # Bad: stuffing data into message content
    data = {"documents": [...], "user_id": 123}
    response = llm.invoke(state + [HumanMessage(content=str(data))])
    return [response]

# Bad
def bad_node(state):
    return {"messages": state["messages"] + [new_message]}  # Manual concat

# Also Bad
return [new_message]  # Forgets previous messages

from langgraph.graph.message import add_messages

def good_node(state):
    return {"messages": [new_message]}   # add_messages reducer handles appending

class BadState(TypedDict):
    data: dict                    # Too vague
    everything: list              # No reducer
    temp: str = ""                # Mutable default

class AgentState(MessagesState):        # Inherit from MessagesState
    documents: list[dict] = []          # Only when doing RAG
    iterations: int = 0                 # For safety
    # Avoid: user_profile, full_db_results, etc.

from pydantic import BaseModel, Field
from typing import Annotated
from langgraph.graph.message import add_messages

class AgentState(BaseModel):
    messages: Annotated[list, add_messages] = Field(default_factory=list)
    documents: list[dict] = Field(default_factory=list)
    iterations: int = Field(default=0)
    confidence: float = Field(default=0.0)

from typing import TypedDict, Annotated

class AgentState(TypedDict):
    messages: Annotated[list, add_messages]
    documents: Annotated[list[dict], lambda a, b: a + b]
    iterations: int

class AgentState(MessagesState):
    messages: Annotated[list, add_messages]
    
    # Metadata / Control fields
    documents: list[dict] = []
    iterations: int = 0
    current_task: str | None = None
    user_preferences: dict = {}

class AgentState(MessagesState):
    messages: Annotated[list, add_messages]      # Conversation history
    retrieved_docs: list[dict]                   # From retriever node only
    iterations: int                              # Updated in agent node
    final_answer: str | None = None              # Written only at the end