langgraph-fundamentals

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.

Designing a LangGraph application

Follow these 5 steps when building a new graph:

1. Map out discrete steps — sketch a flowchart of your workflow. Each step becomes a node.
2. 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.
3. Design your state — state is shared memory for all nodes. Store raw data, format prompts on-demand inside nodes.
4. Build your nodes — implement each step as a function that takes state and returns partial updates.
5. 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.