langgraph-fundamentals by @akillness

<overview> LangGraph models agent workflows as **directed graphs**:

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. </overview>

<design-methodology>

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.

</design-methodology> <when-to-use-langgraph>

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

</when-to-use-langgraph>

State Management

<state-update-strategies>

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

</state-update-strategies>

Nodes

<node-function-signatures>

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

</node-function-signatures>

Edges

<edge-type-selection>

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

</edge-type-selection>

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

<command-return-type-annotations>

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.

</command-return-type-annotations> <warning-command-static-edges>

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.

</warning-command-static-edges>

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

<invoke-basics>

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

</invoke-basics> <stream-mode-selection>

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

</stream-mode-selection>

Error Handling

Match the error type to the right handler:

<error-handling-table>

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`

</error-handling-table>

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.

For disk-backed checkpointers, interrupt_before approval gates, subgraph composition, error-in-state routing, and LangSmith tracing / streaming set-up, read references/production-patterns.md after the language reference above.