Nodes & Edges
If work is a blob of Python, you cannot pause in the middle, retry one step, or stream 'the tool just ran'. Nodes are the units the runtime can see.
Kitchen stations: prep, grill, plate. Food (state) moves on tickets. The pass (edges) says where a ticket goes next — not the chef yelling across the room.
Visual Workflows
Start here — scroll inside each diagram frame to explore, then use + / − to zoom up to 200% if needed.
Overview
Scroll inside the frame to explore · use + / − to zoom up to 200%
Scroll inside the frame to explore · use + / − to zoom up to 200%
What a node returns
Scroll inside the frame to explore · use + / − to zoom up to 200%
Return only the fields you changed. The runtime merges them into shared state.
Fixed edge vs no edge
Scroll inside the frame to explore · use + / − to zoom up to 200%
A fixed edge is a promise: after A, always B. If you forget the edge, the run stops after A.
Key Takeaways
- 1.A node is a function: it reads the current state, does one job, and returns a partial update. An edge is the next step: a fixed edge always goes A to B; a missing edge is a dead end.
- 2.START is the entry arrow. Finish is the exit. You never write a node named start — you point START at the first real node. One node, one job. Classify is not also refund. Mixing jobs makes routing impossible later.
- 3.add_node(name, fn) registers the station. add_edge(a, b) is a fixed transition. START and the graph end are sentinels, not your functions.
- 4.Nodes should be idempotent-ish: if a checkpoint retries the node, side effects may run again — keep them small.
Learn elsewhere
- →StateGraph — next module
- →Conditional Routing
Real Example
Scenario
Ticket comes in. classify writes ticket_type. assistant writes a reply. Two nodes, one edge between them. Tomorrow you insert a tools node without rewriting classify.
What you would do
Name nodes after verbs you can say out loud: classify, search, refund_gate, reply. If you cannot say the job in one word, split the node.
Commands
Commands to Remember
add_node(name, function) # one job per nameadd_edge(A, B) # always A then BSTART points at the first nodeReturn a dict of changed fields only
Cheat Sheet
Quick recap
quick ref- •Node = function
- •Edge = next step
- •START / Finish
- •Partial updates
Common Mistakes
- ✕Putting the whole agent inside one node — then you cannot route, pause, or retry a step
- ✕Forgetting the edge from the last node to Finish, so invoke hangs or returns half-state
- ✕Mutating a global variable instead of returning a state update