langgraph-fundamentals

SKILL.md

StateGraph: Main class for building stateful graphs

Nodes: Functions that perform work and update state

Edges: Define execution order (static or conditional)

START/END: Special nodes marking entry and exit points

State with Reducers: Control how state updates are merged

Graphs must be compile()d before execution.

Designing a LangGraph application

Follow these 5 steps when building a new graph:

Map out discrete steps — sketch a flowchart of your workflow. Each step becomes a node.

Identify what each step does — categorize nodes: LLM step, data step, action step, or user input step. For each, determine static context (prompt), dynamic context (from state), retry strategy, and desired outcome.

Design your state — state is shared memory for all nodes. Store raw data, format prompts on-demand inside nodes.

Build your nodes — implement each step as a function that takes state and returns partial updates.

Wire it together — connect nodes with edges, add conditional routing, compile with a checkpointer if needed.

Use LangGraph When
Use Alternatives When

Need fine-grained control over agent orchestration
Quick prototyping → LangChain agents

Building complex workflows with branching/loops
Simple stateless workflows → LangChain direct

Require human-in-the-loop, persistence
Batteries-included features → Deep Agents

State Management

Need
Solution
Example

Overwrite value
No reducer (default)
Simple fields like counters

Append to list
Reducer (operator.add / concat)
Message history, logs

Custom logic
Custom reducer function
Complex merging

Nodes

Node functions return partial state updates. Signatures for configuration and runtime access differ by language; use the applicable implementation reference.

Edges

Need
Edge Type
When to Use

Always go to same node
add_edge()
Fixed, deterministic flow

Route based on state
add_conditional_edges()
Dynamic branching

Update state AND route
Command
Combine logic in single node

Fan-out to multiple nodes
Send
Parallel processing with dynamic inputs

Command

Command combines state updates and routing in a single return value. Fields:

update: State updates to apply (like returning a dict from a node)

goto: Node name(s) to navigate to next

resume: Value to resume after interrupt() — see human-in-the-loop skill

Python: Use Command[Literal["node_a", "node_b"]] as the return type annotation to declare valid goto destinations.

TypeScript: Pass { ends: ["node_a", "node_b"] } as the third argument to addNode to declare valid goto destinations.

Warning: Command only adds dynamic edges — static edges defined with add_edge / addEdge still execute. If node_a returns Command(goto="node_c") and you also have graph.add_edge("node_a", "node_b"), both node_b and node_c will run.

Send API

Fan-out with Send: return [Send("worker", {...})] from a conditional edge to spawn parallel workers. Requires a reducer on the results field.

Running Graphs: Invoke and Stream

Call graph.invoke(input, config) to run a graph to completion and return the final state.

Mode
What it Streams
Use Case

values
Full state after each step
Monitor complete state

updates
State deltas
Track incremental updates

messages
LLM tokens + metadata
Chat UIs

custom
User-defined data
Progress indicators

Error Handling

Match the error type to the right handler:

Error Type
Who Fixes
Strategy
Example

Transient (network, rate limits)
System
RetryPolicy(max_attempts=3)
add_node(..., retry_policy=...)

LLM-recoverable (tool failures)
LLM
ToolNode(tools, handle_tool_errors=True)
Error returned as ToolMessage

User-fixable (missing info)
Human
interrupt({"message": ...})
Collect missing data (see HITL skill)

Unexpected
Developer
Let bubble up
raise

Core boundaries

Return partial state updates from nodes instead of mutating state directly.

Route loops through a named node; START is entry-only.

Define reducers for accumulated list fields; otherwise, the last write wins.

Account for static edges when using Command with goto, because both routes execute.

Implementation references

If writing, modifying, or debugging LangGraph code, determine the project's language from its existing files, then read the applicable reference before implementing:

For Python, read references/python.md.

For TypeScript, read references/typescript.md.

Read both only when the task covers both languages. For conceptual questions that require no code, do not load either reference.