Langgraph Fundamentals

<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:

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.

</design-methodology>

<when-to-use-langgraph>

</when-to-use-langgraph>

State Management

<state-update-strategies>

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

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

</stream-mode-selection>

Error Handling

Match the error type to the right handler:

<error-handling-table>

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