State, Nodes, and Edges

What you will be able to do

• ✓Explain state, nodes and edges in your own words, using an everyday example
• ✓Define the state with a TypedDict, and know what TypedDict does and does not check
• ✓Write nodes that read the state and return only what they change
• ✓Understand exactly how LangGraph merges a node’s update into the state
• ✓Connect nodes with START, END and add_edge, and build a graph in six steps
• ✓Compile and invoke a graph, and watch the state change with stream()
• ✓Write a node that calls an LLM, next to normal Python nodes
• ✓Recognise the mistakes that fail silently: unknown keys, wrong types, changing the state in place

The idea, in plain English

In Lesson 3.1 you saw that a graph is boxes (nodes) and arrows (edges). One question was left open: how does information move from one box to the next? In LangGraph the answer is the state.

The state is one dictionary that travels through the whole run. Think of it as a shared notebook. Every node gets the notebook, reads what it needs, does its job, and writes down only what it changed. LangGraph copies those changes into the notebook and passes it to the next node.

So every LangGraph program is built from three ideas. State answers "what do I know?" - the data. A node answers "what do I do?" - a Python function. An edge answers "where do I go next?" - an arrow from one node to another.

This lesson explains each idea slowly, with small examples you can run. Most examples need no LLM - the nodes are plain Python functions, which is the clearest way to see how the state moves. One example adds a real llama3 node. Everything was run with LangGraph 1.2.14.

Worked example: A greeting graph, an order-processing graph, and a graph where one node calls llama3.

An everyday picture: the restaurant order slip

Think of a small restaurant. When you order, the waiter writes an order slip: table number, dishes, notes. The slip goes to the kitchen. The cook reads the dishes, cooks them, and writes "ready" on the slip. Then the slip goes to the cashier, who reads the dishes and writes the bill amount. Everyone works on the same slip, and each person writes only their own part.

That is exactly how LangGraph works. The slip is the state. Each person is a node. The route the slip travels - waiter, then kitchen, then cashier - is the edges. The cook does not need to talk to the waiter; everything the cook needs is on the slip.

State: what the workflow knows

The state is a Python dictionary shared by the whole run. For a question-answer graph it might start as {"question": "What is Docker?"}. After the answering node runs, it also holds an answer.

Keep two things apart in your head. The graph is the structure - which nodes exist and how they are connected. It is built once. The state is the data - it is different for every run. Graph = structure, state = data.

You describe the shape of the state with a TypedDict. If TypedDict is new to you: it is a normal Python class that lists the keys a dictionary should have, and the type of each value. It helps you, your editor and other readers know what is in the state.

Watch out: TypedDict is a description, not a guard. Python does not check it while the program runs. In our test a node returned {"message": 42} for a field declared as str, and LangGraph stored 42 without any error.

Nodes: functions that return changes

A node is a normal Python function with one rule: it receives the current state, and it returns a dictionary with only the fields it wants to change. It does not return the whole state.

In the example below, greet reads state["name"] and returns {"message": "Hello, Chandu!"}. It does not mention name, so name stays exactly as it was. If a node has nothing to change - for example it only prints a log line - it can return {} or nothing at all. We tested both: the state passed through unchanged.

Give each node one job and a name that says what it does: classify_request, search_documents, generate_answer. Small nodes with clear names make the workflow easy to read, and you will see those names again when you stream a run or read a trace.

How LangGraph merges a change into the state

After a node runs, LangGraph takes the dictionary it returned and copies each field into the state. Fields the node did not return are kept. A field the node returned replaces the old value completely.

That last point surprises people with lists. If the state has items = ["a"] and a node returns {"items": ["b"]}, the result is ["b"], not ["a", "b"]. To add to a list, the node must build the new list itself: state["items"] + ["b"]. (In Lesson 3.5 you will meet MessagesState, whose messages list adds automatically - that is a special rule called a reducer.)

Edges, START and END

add_edge("greet", "personalize") means: after greet finishes, run personalize. START and END are two special names imported from langgraph.graph. START is where the run enters, END is where it stops. Every graph needs at least one edge from START.

The order in which you call add_node does not matter - only the edges decide the order of the run. We added "two" before "one" but connected START -> one -> two, and the run printed one, then two.

A node that no edge leads to simply never runs - and LangGraph does not warn you. We added a node called orphan, connected nothing to it, and the graph compiled and ran without it. If a node seems to be "skipped", check its edges first.

Some structure mistakes are caught by compile(). A graph with no edge from START fails with ValueError: Graph must have an entrypoint: add at least one edge from START to another node. An edge to a node that was never added fails with ValueError: Found edge ending at unknown node ‘goodbye’.

Build any graph in six steps

Every LangGraph program you write in this module follows the same six steps. Learn them once and every later lesson only adds new kinds of nodes and edges.

Here is the smallest possible graph: one node. Read it top to bottom and match each part to a step in the table.

compile(): from a plan to a program

StateGraph(State) gives you a builder. A builder is like an architect’s drawing of a house: you can add rooms (nodes) and doors (edges), but you cannot live in it. builder.compile() checks the drawing and builds the real thing - a compiled graph that you can run.

If you forget compile() and call builder.invoke(...), Python says AttributeError: ‘StateGraph’ object has no attribute ‘invoke’. The compiled graph has invoke() to run to the end and return the final state, stream() to see each step, and get_graph().draw_mermaid() to print its structure.

Example: an order-processing graph

A more realistic example, shown in the second diagram above. The input has only items. Three nodes each add one field: validate_order keeps only items that are in the price list, calculate_total adds up the prices, and create_receipt writes the receipt.

Notice that the nodes never call each other. calculate_total does not ask validate_order for anything - it reads valid_items from the state. This is the big benefit of shared state: each node only needs to know the state, not the other nodes.

Example: a node that calls an LLM

A node can do anything a Python function can do - including calling a language model. Below, answer_question calls llama3 and stores the reply in the state. The next node, count_words, is plain Python: it reads the answer the LLM node wrote and counts its words.

This mix is normal in real agents: some nodes call a model, others check, calculate, or save data. LangGraph treats them the same way - each one reads the state and returns changes.

We used stream(stream_mode="updates") instead of invoke(). It prints what each node returned, one node at a time - the next topic explains it.

Watching the state move: stream()

invoke() only shows you the final state. When something goes wrong, you want to see every step. That is what stream() is for. It has two useful modes.

stream_mode="updates" prints what each node returned, with the node’s name: {‘greet’: {...}}, then {‘personalize’: {...}}. stream_mode="values" prints the whole state after each step - first the input, then the state after greet, then after personalize.

This is the most useful debugging tool in LangGraph. If a node gets a value you did not expect, stream the run with "updates" and look for the node that wrote it.

Mistakes that fail silently

Some mistakes give you an error, and those are easy to fix. Returning a string instead of a dictionary fails with InvalidUpdateError: Expected dict, got hi. Reading a key that is not in the state - state["question"] when the input had no question - fails with KeyError: ‘question’. If a key may be missing, use state.get("question", "a default").

Other mistakes give no error at all, and those are the dangerous ones. A key that is not in the state is dropped without a word: a node returning {"greeting": "hi"} on a state with only message left message empty. And changing the state in place does not work: a node that wrote state["message"] = "mutated" and returned nothing lost that change - the next node still saw the old value. Always return your changes.

Watch out: Return changes; never edit the state you were given. In our run the in-place change was simply lost - no error, no warning.

Practice: build your own graph

Try this before you read the solution. Build a graph with three nodes that cleans and measures a piece of text. The state has text (the input), clean_text, word_count and report. Node clean removes extra spaces and makes the text lower case. Node count counts the words. Node report writes "<count> words: <clean text>".

The solution uses add_sequence, a shortcut for nodes in a straight line: it adds all three nodes (named after their functions) and the edges between them. You still add the edge from START and the edge to END yourself.

Why shared state is worth it

Without a shared state, every function must pass all its data on by hand: step_a(user, question, history, tool_result, retry_count, metadata). When you add one new piece of data, you must change every function on the way. With state, a node reads what it needs and returns what it changed. Adding a field only touches the nodes that use it.

The real benefit comes with branches and loops. In Lesson 3.1’s support graph, the routing function read attempts and status from the state to choose between check, respond and escalate. In an agent, the state will hold the list of messages, and the model and tools nodes will take turns adding to it.

Common questions

Can a node call an LLM, an API, or a database? Yes. A node is just a Python function, so it can do anything Python can do. The LLM example above shows it.

Can a node be async? Yes - write async def and run the graph with await graph.ainvoke(...). We tested it: ainvoke worked, but invoke() on a graph with an async node failed with TypeError: No synchronous function provided.

Do I have to pass every state field in the input? No. The order example passed only items, and the nodes added the rest. But a node that reads a missing key with state["key"] fails with KeyError.

What does invoke() return? The whole final state - all fields - not only what the last node returned. Extra input keys that are not in the TypedDict are dropped from it.

Step-by-step code

Tip: When a node sees a value you did not expect, run the graph with stream_mode="updates". It shows exactly which node wrote what, in order.

LangGraph basics at a glance

StateGraph(State)

class State(TypedDict): message: str

builder.add_node("greet", greet)

builder.add_edge("greet", "personalize")

from langgraph.graph import START, END

graph = builder.compile()

graph.invoke({"name": "Chandu"})

graph.stream(x, stream_mode="updates")

builder.add_sequence([clean, count, report])

await graph.ainvoke({...})

Try it yourself

The code does not change. Swap the content string and the program does something else entirely.

What usually goes wrong

✗ builder.invoke({"message": ""})

✓ graph = builder.compile()
graph.invoke({"message": ""})

✗ builder.add_edge("hello", END)

✓ builder.add_edge(START, "hello")
builder.add_edge("hello", END)

✗ return {"greeting": "Hello"}   # State has message, not greeting

✓ return {"message": "Hello"}

✗ def greet(state):
    state["message"] = "Hello"

✓ def greet(state):
    return {"message": "Hello"}

✗ return {"items": ["b"]}

✓ return {"items": state["items"] + ["b"]}

✗ builder.add_node("process", process_everything)

✓ builder.add_sequence([classify, search, validate, generate])

Quick check before you move on

1. 1.

   A node returns {"greeting": "hi"} but the state only has message. What happens?

   Show answer
2. 2.

   A node sets state["message"] = "x" and returns nothing. What does the next node see?

   Show answer
3. 3.

   The state has items = ["a"]. A node returns {"items": ["b"]}. What is items now?

   Show answer
4. 4.

   You added a node but it never runs, and there is no error. What is the most likely cause?

   Show answer
5. 5.

   When is a missing START edge reported?

   Show answer
6. 6.

   What is the difference between stream_mode="updates" and "values"?

   Show answer

Interview questions