langgraph

LangGraph

WHEN: Building stateful agent orchestration with explicit graph nodes, durable execution, checkpointing, interrupts, subgraphs, or LangSmith-observed agent workflows.

When to Use

• Building multi-step agents with explicit state transitions
• Implementing durable, resumable workflows for long-running tasks
• Adding human approval or interruption points into agent execution
• Modeling branching, loops, retries, and subgraphs explicitly
• Using LangSmith to inspect trajectories, state changes, and failures

Decision Tree

Need agent orchestration?
+- Mostly linear workflow with simple tool calls?
|  +- Use plain agent framework first
|  - Add LangGraph only if state and branching become explicit requirements
+- Need durable state across steps or resumes?
|  - Use LangGraph StateGraph with checkpointing
+- Need human approval or editing of state mid-run?
|  - Use interrupts / human-in-the-loop nodes
+- Need reusable workflow segments?
|  - Use subgraphs with narrow state contracts
+- Need production debugging visibility?
|  - Add LangSmith tracing and run metadata
-- Need complex branching and retries?
   - Model them as graph edges, not implicit prompt instructions

Core Rules

1. Model workflow state explicitly with typed schemas rather than ad hoc dictionaries everywhere.
2. Keep node responsibilities narrow: one decision, one transformation, or one external action.
3. Put retries, branching, and approval steps in the graph, not only inside prompts.
4. Persist checkpoints for any workflow that may exceed one request/response turn or need recovery.
5. Trace graph execution so failures can be tied to node transitions and state mutations.

Architecture Pattern

User Input
  -> StateGraph entry
  -> planner node
  -> tool/research node(s)
  -> validation node
  -> human approval interrupt (optional)
  -> writer/executor node
  -> final response node

Minimal Pattern

from typing_extensions import TypedDict
from langgraph.graph import START, END, StateGraph


class AgentState(TypedDict):
    question: str
    answer: str


def draft_answer(state: AgentState) -> dict:
    return {"answer": f"Draft response for: {state['question']}"}


graph = StateGraph(AgentState)
graph.add_node("draft_answer", draft_answer)
graph.add_edge(START, "draft_answer")
graph.add_edge("draft_answer", END)

app = graph.compile()
result = app.invoke({"question": "What should we build?", "answer": ""})