Python course Β· Module 11: RAG and Multi-Agent Systems

LangGraph - Graph-Based Agent Workflows

12 min read Β·
In this lesson9

The chain from the previous lessons always goes one way: researcher, analyst, writer, done. But what if the writer has to send work back to the researcher, or an agent should ask a human for approval before buying tickets? A real trail across the savanna has turnbacks and forks.

LangGraph is a framework for building complex, stateful AI applications based on graphs. It lets you create cycles, branches and advanced control flows for agents. Think of it as a trail map: nodes are camps, edges are paths, and the state is the backpack you carry from camp to camp.

What is LangGraph?

LangGraph extends LangChain's capabilities with:

  • State Management - managing state between steps
  • Cycles - the ability to create loops (unlike a DAG)
  • Branching - conditional flow branches
  • Human-in-the-loop - breakpoints for human interaction

The diagram shows a typical agent graph with tools, in which the flow can return to the agent many times:

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                     LangGraph Flow                          β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚                                                             β”‚
β”‚     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                                            β”‚
β”‚     β”‚  START   β”‚                                            β”‚
β”‚     β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜                                            β”‚
β”‚          β”‚                                                   β”‚
β”‚          β–Ό                                                   β”‚
β”‚     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                       β”‚
β”‚     β”‚  Agent   │────▢│   Condition  β”‚                       β”‚
β”‚     β”‚  Node    β”‚     β”‚   (Router)   β”‚                       β”‚
β”‚     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜                       β”‚
β”‚          β–²                  β”‚                               β”‚
β”‚          β”‚        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”                     β”‚
β”‚          β”‚        β–Ό         β–Ό         β–Ό                     β”‚
β”‚          β”‚   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”              β”‚
β”‚          β”‚   β”‚ Tool A β”‚ β”‚ Tool B β”‚ β”‚  END   β”‚              β”‚
β”‚          β”‚   β””β”€β”€β”€β”¬β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”¬β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜              β”‚
β”‚          β”‚       β”‚          β”‚                               β”‚
β”‚          β””β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                               β”‚
β”‚              (cycle back)                                    β”‚
β”‚                                                             β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

The agent decides, the router picks the path to a tool or to the end, and after a tool is used the flow returns to the agent.

Installation and Basics

The most important element of LangGraph is the state. We define it as a TypedDict, a dictionary with described key types:

# pip install langgraph langchain-openai

from langgraph.graph import StateGraph, END
from langgraph.checkpoint.memory import MemorySaver
from typing import TypedDict, Annotated, Literal
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, AIMessage
import operator

# State definition - key element of LangGraph
class AgentState(TypedDict):
    messages: Annotated[list, operator.add]  # Message list
    current_step: str
    iteration_count: int

# LLM model
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

Annotated[list, operator.add] tells LangGraph how to merge updates: new messages are appended to the list instead of replacing it. Keys without an annotation are overwritten. For chat there is also a ready-made add_messages reducer in the langgraph.graph.message module.

Basic Agent Graph

Building a graph always follows the same order: state definition, StateGraph, nodes (add_node), edges (add_edge) and compilation (compile). We start with the state and the agent node:

from langgraph.graph import StateGraph, START, END

# State definition
class State(TypedDict):
    messages: Annotated[list, operator.add]
    next_action: str

# Node functions
def agent_node(state: State) -> State:
    """Agent node - makes decisions."""
    messages = state["messages"]

    response = llm.invoke(messages)

    return {
        "messages": [response],
        "next_action": "tool" if response.tool_calls else "end"
    }

A node is an ordinary function: it receives the state and returns a dictionary with the keys it wants to change. For the model to return tool_calls at all, you have to attach the tools with llm.bind_tools(tools), otherwise the list will always be empty.

The second node executes tools, and the router picks the next step:

def tool_node(state: State) -> State:
    """Tool node - executes actions."""
    last_message = state["messages"][-1]

    # Execute tool calls
    tool_results = []
    for tool_call in last_message.tool_calls:
        result = execute_tool(tool_call)
        tool_results.append(result)

    return {"messages": tool_results, "next_action": "agent"}

def router(state: State) -> Literal["tool", "end"]:
    """Router - decides the next step."""
    return state["next_action"]

execute_tool is the place for your own logic. In practice you will replace this node with the ready-made ToolNode from langgraph.prebuilt.

Now we connect everything into a graph:

# Build graph
workflow = StateGraph(State)

# Add nodes
workflow.add_node("agent", agent_node)
workflow.add_node("tool", tool_node)

# Add edges
workflow.add_edge(START, "agent")
workflow.add_conditional_edges(
    "agent",
    router,
    {
        "tool": "tool",
        "end": END
    }
)
workflow.add_edge("tool", "agent")  # Cycle back to agent

# Compile graph
app = workflow.compile()

# Run
result = app.invoke({
    "messages": [HumanMessage(content="What is the weather in the Serengeti?")],
    "next_action": ""
})

add_conditional_edges asks the router for a path name and translates it to a node with the dictionary. The edge from "tool" back to "agent" creates the cycle.

ReAct Agent with LangGraph

This pattern is so popular that there is a ready-made version. First the tools with the @tool decorator, known from the lesson on multi-agent systems:

from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent

# Tool definitions
@tool
def get_weather(location: str) -> str:
    """Gets weather for a Safari location."""
    weather_data = {
        "Serengeti": "28C, sunny",
        "Masai Mara": "25C, cloudy",
        "Kruger": "30C, hot"
    }
    return weather_data.get(location, f"No data for {location}")

@tool
def search_animals(query: str) -> str:
    """Searches for information about Safari animals."""
    return f"Information about {query}: A fascinating animal of the African savanna!"

@tool
def calculate_safari_cost(days: int, people: int) -> str:
    """Calculates Safari cost."""
    cost_per_day = 200
    total = days * people * cost_per_day
    return f"Safari cost: {total} USD ({days} days, {people} people)"

Every tool has a docstring, which the model reads as its description, and parameter types that tell it what to pass.

create_react_agent builds the whole agent-tools graph in a single line:

# Create ReAct agent
tools = [get_weather, search_animals, calculate_safari_cost]
react_agent = create_react_agent(llm, tools)

# Run
result = react_agent.invoke({
    "messages": [HumanMessage(content="Calculate the cost of a 5-day Safari for 4 people")]
})
print(result["messages"][-1].content)

The model will call calculate_safari_cost with days=5 and people=4 by itself. Note: in LangGraph 1.0 create_react_agent is marked as deprecated, and new code should use create_agent from the langchain.agents package.

Multi-Agent with LangGraph

A graph is a great fit for a team of agents. Each agent is a node, and the current_agent field in the state says who is next:

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

class MultiAgentState(TypedDict):
    messages: Annotated[list, operator.add]
    current_agent: str
    task_complete: bool

# Specialist agents
def researcher_agent(state: MultiAgentState) -> MultiAgentState:
    """Research agent - gathers information."""
    system_prompt = "You are a Safari researcher. Gather information about animals and locations."

    response = llm.invoke([
        {"role": "system", "content": system_prompt},
        *state["messages"]
    ])

    return {
        "messages": [AIMessage(content=f"[Researcher]: {response.content}")],
        "current_agent": "analyzer"
    }

The researcher appends its answer to messages and names the analyzer as the next one.

The analyzer and the writer work the same way, only the writer finishes with the task_complete flag:

def analyzer_agent(state: MultiAgentState) -> MultiAgentState:
    """Analytical agent - analyzes data."""
    system_prompt = "You are an analyst. Analyze gathered information and draw conclusions."

    response = llm.invoke([
        {"role": "system", "content": system_prompt},
        *state["messages"]
    ])

    return {
        "messages": [AIMessage(content=f"[Analyzer]: {response.content}")],
        "current_agent": "writer"
    }

def writer_agent(state: MultiAgentState) -> MultiAgentState:
    """Writer agent - creates the final report."""
    system_prompt = "You are a writer. Create an engaging report based on the analysis."

    response = llm.invoke([
        {"role": "system", "content": system_prompt},
        *state["messages"]
    ])

    return {
        "messages": [AIMessage(content=f"[Writer]: {response.content}")],
        "current_agent": "end",
        "task_complete": True
    }

Every agent sees the whole message history, because messages grows with each node.

What remains is the router and the graph:

def router(state: MultiAgentState) -> Literal["analyzer", "writer", "end"]:
    """Router between agents."""
    return state["current_agent"]

# Build multi-agent graph
multi_agent_graph = StateGraph(MultiAgentState)

multi_agent_graph.add_node("researcher", researcher_agent)
multi_agent_graph.add_node("analyzer", analyzer_agent)
multi_agent_graph.add_node("writer", writer_agent)

multi_agent_graph.add_edge(START, "researcher")
multi_agent_graph.add_conditional_edges(
    "researcher",
    router,
    {"analyzer": "analyzer"}
)
multi_agent_graph.add_conditional_edges(
    "analyzer",
    router,
    {"writer": "writer"}
)
multi_agent_graph.add_conditional_edges(
    "writer",
    router,
    {"end": END}
)

multi_agent_app = multi_agent_graph.compile()

# Run pipeline
result = multi_agent_app.invoke({
    "messages": [HumanMessage(content="Prepare a report about lions in the Serengeti")],
    "current_agent": "researcher",
    "task_complete": False
})

The order is linear, but the router makes it easy to add a way back to the researcher.

Checkpointing and Persistence

By default the graph forgets everything after invoke. A checkpointer saves the state after every step, which lets you continue a conversation:

from langgraph.checkpoint.memory import MemorySaver
from langgraph.checkpoint.sqlite import SqliteSaver  # pip install langgraph-checkpoint-sqlite
import sqlite3

# Memory checkpoint (in-memory)
memory_checkpointer = MemorySaver()

# SQLite checkpoint (persistent)
sqlite_checkpointer = SqliteSaver(sqlite3.connect("safari_agent.db", check_same_thread=False))

# Compile with checkpointer
app_with_memory = workflow.compile(checkpointer=memory_checkpointer)

MemorySaver keeps the state in memory and loses it on restart. SqliteSaver from the langgraph-checkpoint-sqlite package stores it in an SQLite database file.

Conversations are told apart by the thread_id in the config:

# Run with thread_id for continuation
config = {"configurable": {"thread_id": "safari-session-1"}}

# First message
result1 = app_with_memory.invoke(
    {"messages": [HumanMessage(content="Tell me about lions")]},
    config
)

# Continue conversation (same thread_id)
result2 = app_with_memory.invoke(
    {"messages": [HumanMessage(content="What about their hunting?")]},
    config
)

# History is preserved!
print(result2["messages"])

The second call with the same thread_id sees the first message, so the model knows that "their" means the lions.

Human-in-the-loop

Some decisions an agent should not make alone. First the state, the nodes and the router:

from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver

class HumanLoopState(TypedDict):
    messages: Annotated[list, operator.add]
    needs_approval: bool
    approved: bool

def agent_node(state: HumanLoopState) -> HumanLoopState:
    """Agent proposes an action."""
    response = llm.invoke(state["messages"])

    # Check if action requires approval
    needs_approval = "delete" in response.content.lower() or "buy" in response.content.lower()

    return {
        "messages": [response],
        "needs_approval": needs_approval
    }

def human_approval_node(state: HumanLoopState) -> HumanLoopState:
    """Human approval checkpoint."""
    # This node stops execution
    # User must approve before continuing
    return {"approved": state.get("approved", False)}

def execute_node(state: HumanLoopState) -> HumanLoopState:
    """Executes the approved action."""
    return {"messages": [AIMessage(content="Action executed!")]}

def approval_router(state: HumanLoopState) -> Literal["human", "execute", "end"]:
    """Router checking if approval is needed."""
    if state.get("needs_approval") and not state.get("approved"):
        return "human"
    elif state.get("approved"):
        return "execute"
    return "end"

The human node computes nothing, it is only a stopping point. It returns one key unchanged, because returning the whole state would append all messages a second time through the operator.add reducer.

We compile the graph with a checkpointer and interrupt_before:

# Graph with human-in-the-loop
human_loop_graph = StateGraph(HumanLoopState)

human_loop_graph.add_node("agent", agent_node)
human_loop_graph.add_node("human", human_approval_node)
human_loop_graph.add_node("execute", execute_node)

human_loop_graph.add_edge(START, "agent")
human_loop_graph.add_conditional_edges(
    "agent",
    approval_router,
    {"human": "human", "execute": "execute", "end": END}
)
human_loop_graph.add_edge("human", "agent")  # After approval, return to agent
human_loop_graph.add_edge("execute", END)

# Compile with interrupt_before for human node
app = human_loop_graph.compile(
    checkpointer=MemorySaver(),
    interrupt_before=["human"]  # Stop before human node
)

The router returns "end", which is why the path dictionary translates that name to END. Without it, LangGraph raises an error about an unknown end node.

Running stops before the human node, and we approve and resume:

# Run - will stop before human node
config = {"configurable": {"thread_id": "approval-1"}}
result = app.invoke(
    {"messages": [HumanMessage(content="Delete all files")]},
    config
)

# Check state
state = app.get_state(config)
print(f"Needs approval: {state.values.get('needs_approval')}")

# User approves
app.update_state(config, {"approved": True})

# Continue execution
final_result = app.invoke(None, config)

update_state records the approval, and invoke(None, config) resumes the graph while the router sends the flow to execute. In newer versions the interrupt() function called inside a node is more convenient.

Branching and Parallel Execution

Two independent branches can run at the same time. First the node functions:

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

class ParallelState(TypedDict):
    query: str
    weather_result: str
    animal_result: str
    combined_result: str

def weather_branch(state: ParallelState) -> ParallelState:
    """Fetches weather in parallel."""
    # Simulated API call
    return {"weather_result": "Weather: 28C, sunny"}

def animal_branch(state: ParallelState) -> ParallelState:
    """Fetches animal info in parallel."""
    return {"animal_result": "Animals: Lions, elephants, giraffes"}

def combine_results(state: ParallelState) -> ParallelState:
    """Combines results from parallel branches."""
    combined = f"{state['weather_result']}. {state['animal_result']}"
    return {"combined_result": combined}

Each branch writes a different state key, so there is no conflict.

Two edges from START split the flow:

# Graph with parallel execution
parallel_graph = StateGraph(ParallelState)

parallel_graph.add_node("weather", weather_branch)
parallel_graph.add_node("animals", animal_branch)
parallel_graph.add_node("combine", combine_results)

# Parallel edges
parallel_graph.add_edge(START, "weather")
parallel_graph.add_edge(START, "animals")
parallel_graph.add_edge("weather", "combine")
parallel_graph.add_edge("animals", "combine")
parallel_graph.add_edge("combine", END)

parallel_app = parallel_graph.compile()

result = parallel_app.invoke({"query": "Safari info"})
print(result["combined_result"])

weather and animals run in the same step, and combine starts only when both have finished.

Supervisor Pattern

In this pattern one agent manages the rest. The supervisor asks the model who should work:

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

class SupervisorState(TypedDict):
    messages: Annotated[list, operator.add]
    next_worker: str
    completed_workers: list[str]

def supervisor_node(state: SupervisorState) -> SupervisorState:
    """Supervisor decides which worker should act."""
    system_prompt = """You are a supervisor managing a team:
    - researcher: gathers information
    - analyst: analyzes data
    - writer: creates reports

    Based on the task and results so far, choose the next worker.
    Reply with ONLY the worker name or 'FINISH' if the task is complete."""

    completed = state.get("completed_workers", [])

    response = llm.invoke([
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": f"Completed: {completed}\nTask: {state['messages'][-1].content}"}
    ])

    next_worker = response.content.strip().lower()

    return {"next_worker": next_worker}

The supervisor returns only the name of the next worker.

A factory creates the worker nodes, and the router translates the decision:

def worker_node(worker_name: str):
    """Factory for worker nodes."""
    def node(state: SupervisorState) -> SupervisorState:
        prompts = {
            "researcher": "You are a researcher. Gather information.",
            "analyst": "You are an analyst. Analyze the data.",
            "writer": "You are a writer. Write the report."
        }

        response = llm.invoke([
            {"role": "system", "content": prompts[worker_name]},
            *state["messages"]
        ])

        completed = state.get("completed_workers", []) + [worker_name]

        return {
            "messages": [AIMessage(content=f"[{worker_name}]: {response.content}")],
            "completed_workers": completed
        }
    return node

def supervisor_router(state: SupervisorState) -> Literal["researcher", "analyst", "writer", "end"]:
    """Supervisor router."""
    next_worker = state.get("next_worker", "").lower()
    if next_worker == "finish" or next_worker == "end":
        return "end"
    return next_worker

If the model answers with something outside the list, the router returns an unknown name and the graph crashes, so in production enforce the answer format.

Every worker hands control back to the supervisor:

# Build supervisor graph
supervisor_graph = StateGraph(SupervisorState)

supervisor_graph.add_node("supervisor", supervisor_node)
supervisor_graph.add_node("researcher", worker_node("researcher"))
supervisor_graph.add_node("analyst", worker_node("analyst"))
supervisor_graph.add_node("writer", worker_node("writer"))

supervisor_graph.add_edge(START, "supervisor")

# All edges lead back to the supervisor
for worker in ["researcher", "analyst", "writer"]:
    supervisor_graph.add_edge(worker, "supervisor")

supervisor_graph.add_conditional_edges(
    "supervisor",
    supervisor_router,
    {
        "researcher": "researcher",
        "analyst": "analyst",
        "writer": "writer",
        "end": END
    }
)

supervisor_app = supervisor_graph.compile()

# Run
result = supervisor_app.invoke({
    "messages": [HumanMessage(content="Prepare a complete report on Safari in the Serengeti")],
    "completed_workers": []
})

I recommend starting with a linear graph and adding cycles and a supervisor when you really need decisions along the way.

LangGraph is a powerful tool for building complex AI workflows. In the next lesson you will learn about subagents and agent hierarchies!

Remember: LangGraph is a trail map on which you may turn back, split up and wait for the guide's decision.

Docs entries used in this lesson

Spotted a mistake in this lesson?

Check yourself

Answer the questions from this lesson. Pick an answer to see right away whether it is correct.

  1. 1. What is LangGraph?

  2. 2. What does LangGraph enable compared to standard chains?

These are 2 of 4 questions for this lesson. Solve the rest in the game.

Hands-on tasks in the game

  • Horizontal ordering

    Arrange the elements:

  • Vertical ordering

    Arrange the steps for building a graph in LangGraph:

  • Code editor

    Define a State class with TypedDict and Annotated for messages.

  • Click in order

    Arrange creating a node in LangGraph:

  • Code editor

    Implement a graph with researcher, analyzer, and writer agents.

  1. QuestionLangGraph
  2. Put in orderImport StateGraph
  3. QuestionLangGraph Capabilities
  4. Put in orderLangGraph Workflow
  5. Coding taskLangGraph State
  6. Click in orderStateGraph Build
  7. QuestionCheckpointing
  8. QuestionHuman-in-the-loop
  9. Coding taskMulti-Agent LangGraph

Useful articles