Implementation:Langchain ai Langgraph StateGraph Add Edge

Metadata	Value
Type	Implementation (API Doc)
Library	langgraph
Source File	`libs/langgraph/langgraph/graph/state.py`
Lines	L785-837 (`add_edge`), L839-887 (`add_conditional_edges`)
Workflow	Building_a_Stateful_Graph

Overview

StateGraph.add_edge adds a static (unconditional) directed edge between nodes. StateGraph.add_conditional_edges adds a conditional edge where a routing function determines the next node(s) at runtime. Together they define the execution topology of the graph.

Description

add_edge connects a start node (or list of start nodes) to an end node. When start_key is a single string, a simple directed edge is created. When start_key is a list, a waiting edge (fan-in/join) is created -- the end node only triggers after all listed start nodes have completed.

add_conditional_edges attaches a routing function to a source node. After the source node executes, the routing function is called with the current state. It returns one or more destination node names. The optional path_map translates the routing function's return values to actual node names.

Both methods validate that END is never used as a start node and START is never used as an end node. They also return Self for method chaining.

Usage

from typing import Literal
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END

class State(TypedDict):
    x: int

def a(state: State) -> dict:
    return {"x": state["x"] + 1}

def b(state: State) -> dict:
    return {"x": state["x"] * 2}

def route(state: State) -> Literal["b", "__end__"]:
    return "b" if state["x"] < 10 else END

builder = StateGraph(State)
builder.add_node(a)
builder.add_node(b)
builder.add_edge(START, "a")
builder.add_conditional_edges("a", route)
builder.add_edge("b", END)
graph = builder.compile()

Code Reference

Source Location

Item	Path	Lines
`add_edge`	`libs/langgraph/langgraph/graph/state.py`	L785-837
`add_conditional_edges`	`libs/langgraph/langgraph/graph/state.py`	L839-887
`set_entry_point`	`libs/langgraph/langgraph/graph/state.py`	L936-947
`set_finish_point`	`libs/langgraph/langgraph/graph/state.py`	L973-984
`START` constant	`libs/langgraph/langgraph/constants.py`	L30-31
`END` constant	`libs/langgraph/langgraph/constants.py`	L28-29

Signature

def add_edge(
    self,
    start_key: str | list[str],
    end_key: str,
) -> Self:

def add_conditional_edges(
    self,
    source: str,
    path: Callable[..., Hashable | Sequence[Hashable]]
        | Callable[..., Awaitable[Hashable | Sequence[Hashable]]]
        | Runnable[Any, Hashable | Sequence[Hashable]],
    path_map: dict[Hashable, str] | list[str] | None = None,
) -> Self:

Import

from langgraph.graph import StateGraph, START, END

I/O Contract

add_edge Parameters

Parameter	Type	Description
`start_key`	list[str]	The source node name(s). If a list, creates a fan-in (join) edge -- the end node waits for all start nodes.
`end_key`	`str`	The destination node name. Can be a node name or `END`.

Returns: Self -- The StateGraph instance.

Raises:

ValueError -- If start_key is END or end_key is START.
ValueError -- If any node in a list-form start_key has not been added yet.

add_conditional_edges Parameters

Parameter	Type	Default	Description
`source`	`str`	required	The node after which the routing function executes.
`path`	Runnable	required	The routing function. Receives the current state and returns destination node name(s) or `END`.
`path_map`	list[str] \| None	`None`	Optional mapping from `path` return values to node names. If omitted, `path` must return valid node names directly.

Returns: Self -- The StateGraph instance.

Raises:

ValueError -- If a branch with the same name already exists for the source node.

Usage Examples

Simple Linear Edge

builder = StateGraph(State)
builder.add_node("a", a)
builder.add_node("b", b)
builder.add_edge(START, "a")
builder.add_edge("a", "b")
builder.add_edge("b", END)

Fan-in (Join) Edge

def c(state: State) -> dict:
    return {"x": state["x"] + 100}

builder = StateGraph(State)
builder.add_node("a", a)
builder.add_node("b", b)
builder.add_node("c", c)
builder.add_edge(START, "a")
builder.add_edge(START, "b")
# "c" only runs after BOTH "a" and "b" complete
builder.add_edge(["a", "b"], "c")
builder.add_edge("c", END)

Conditional Edge with Routing Function

from typing import Literal

def decide_next(state: State) -> Literal["b", "__end__"]:
    if state["x"] >= 10:
        return END
    return "b"

builder = StateGraph(State)
builder.add_node("a", a)
builder.add_node("b", b)
builder.add_edge(START, "a")
builder.add_conditional_edges("a", decide_next)
builder.add_edge("b", "a")  # loop back

Conditional Edge with path_map

def classify(state: State) -> str:
    if state["x"] > 0:
        return "positive"
    return "negative"

builder = StateGraph(State)
builder.add_node("classifier", a)
builder.add_node("pos_handler", b)
builder.add_node("neg_handler", c)
builder.add_edge(START, "classifier")
builder.add_conditional_edges(
    "classifier",
    classify,
    path_map={"positive": "pos_handler", "negative": "neg_handler"},
)

Entry and Finish Point Convenience Methods

builder = StateGraph(State)
builder.add_node("main", a)
builder.set_entry_point("main")   # equivalent to add_edge(START, "main")
builder.set_finish_point("main")  # equivalent to add_edge("main", END)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment