Débuter avec LangGraph : le guide pas à pas

LangGraph, c’est l’outil qui transforme un LLM isolé en véritable système agentique. Là où LangChain vous donne des chaînes linéaires, LangGraph vous donne un graphe — avec des boucles, des conditions, des agents qui collaborent.

Ce guide est fait pour les développeurs Python qui veulent comprendre et utiliser LangGraph concrètement, sans jargon superflu. À la fin, vous aurez construit un vrai agent fonctionnel.

1. C’est quoi LangGraph — et pourquoi c’est différent

LangGraph est un framework Python open-source créé par l’équipe LangChain. Son idée centrale : représenter votre workflow IA comme un

graphe orienté où chaque noeud est une fonction et chaque arête est une transition.

Pourquoi c’est important ? Parce qu’un agent IA réel ne fait pas juste A → B → C. Il fait A → B → si condition : C ou D → retour en B si nécessaire → fin. Un graphe modélise ça naturellement. Une chaîne linéaire non.

LangGraph vs LangChain — la différence en une ligne

LangChain : A | B | C — séquentiel, prédictible, simple.

LangGraph : A → {B ou C} → boucle si besoin → fin — conditionnel, cyclique, agentique.

2. Les 4 concepts clés à connaître

Avant d’écrire une ligne de code, voici les 4 briques fondamentales. Comprenez-les et tout le reste devient évident.

2.1 Le State — la mémoire partagée

Le State est un dictionnaire typé (TypedDict) qui représente l’état complet du système à un instant donné. Tous les noeuds lisent depuis le State et écrivent dans le State.

from typing import TypedDict, Annotated
import operator

class AgentState(TypedDict):
    messages: Annotated[list, operator.add]  # s'accumule à chaque tour
    question: str
    reponse: str
    etape: str

2.2 Les Nodes — les fonctions qui font le travail

Un noeud est une simple fonction Python qui reçoit l’état actuel et retourne une mise à jour partielle de cet état.

from langchain_anthropic import ChatAnthropic

llm = ChatAnthropic(model="claude-3-5-sonnet-20241022")

def node_repondre(state: AgentState) -> dict:
    """Appelle le LLM et retourne la réponse."""
    messages = state["messages"]
    response = llm.invoke(messages)
    return {
        "messages": [response],     # ajouté à la liste existante
        "reponse": response.content,
        "etape": "done"
    }

2.3 Les Edges — les transitions entre noeuds

Les edges (arêtes) définissent qui appelle qui. Il en existe deux types :

• Edge simple : A → B toujours, inconditionnellement.
• Edge conditionnel : A → B ou C selon une fonction de routage.

def router(state: AgentState) -> str:
    """Retourne le nom du prochain noeud."""
    if state["etape"] == "recherche":
        return "node_rechercher"
    elif state["etape"] == "done":
        return END
    else:
        return "node_repondre"

# Edge conditionnel
graph.add_conditional_edges("node_analyser", router)

2.4 Le StateGraph — l’assemblage

Le StateGraph est le chef d’orchestre : vous lui déclarez vos noeuds, vos transitions, et il gère l’exécution.

from langgraph.graph import StateGraph, END

# Assembler
graph_builder = StateGraph(AgentState)

# Ajouter les noeuds
graph_builder.add_node("analyser", node_analyser)
graph_builder.add_node("repondre", node_repondre)

# Définir les transitions
graph_builder.set_entry_point("analyser")
graph_builder.add_edge("analyser", "repondre")
graph_builder.add_edge("repondre", END)

# Compiler
graph = graph_builder.compile()

3. Installation

Créez un environnement virtuel, puis installez les deux packages :

python -m venv .venv
.venv\Scripts\activate   # Windows
source .venv/bin/activate  # Mac/Linux

pip install langgraph langchain-anthropic

Configurez ensuite votre clé API Anthropic :

# Windows
set ANTHROPIC_API_KEY=sk-ant-...

# Mac/Linux
export ANTHROPIC_API_KEY=sk-ant-...

4. Votre premier graphe — de zéro à l’exécution

Construisons un graphe minimal : deux noeuds, une question, une réponse. C’est le "Hello World" de LangGraph.

Le code complet

# premier_graph.py
from typing import TypedDict, Annotated
import operator
from langgraph.graph import StateGraph, END
from langchain_anthropic import ChatAnthropic
from langchain_core.messages import HumanMessage, AIMessage

# 1. Définir l'état
class State(TypedDict):
    messages: Annotated[list, operator.add]
    question: str
    reponse: str
    etape: str

# 2. Initialiser le LLM
llm = ChatAnthropic(model="claude-3-5-sonnet-20241022")

# 3. Définir les noeuds
def node_analyser(state: State) -> dict:
    print(f"[Node: analyser]")
    print(f"  Input reçu : {state['question']!r}")
    return {"etape": "repondre"}

def node_repondre(state: State) -> dict:
    print(f"[Node: répondre]")
    print("  Appel LLM en cours...")
    response = llm.invoke([HumanMessage(content=state["question"])])
    print(f"  Réponse : {response.content}")
    return {
        "messages": [AIMessage(content=response.content)],
        "reponse": response.content,
        "etape": "done"
    }

# 4. Assembler le graphe
builder = StateGraph(State)
builder.add_node("analyser", node_analyser)
builder.add_node("repondre", node_repondre)
builder.set_entry_point("analyser")
builder.add_edge("analyser", "repondre")
builder.add_edge("repondre", END)
graph = builder.compile()

# 5. Exécuter
print("=== Exécution du graphe ===\n")
etat_initial = {
    "messages": [],
    "question": "Quelle est la capitale de la France ?",
    "reponse": "",
    "etape": "debut"
}
resultat = graph.invoke(etat_initial)
print(f"\n=== Graphe terminé ===")
print(f"État final : {resultat}")

5. Aller plus loin — un agent avec des outils

Un graphe à deux noeuds, c’est bien pour comprendre. Mais la puissance de LangGraph apparaît quand vous ajoutez des outils et une boucle agentique.

Le modèle : ReAct

Le pattern le plus courant en LangGraph est ReAct (Reasoning + Acting) :

• Le LLM reçoit la question et l’historique
• Il décide soit d’appeler un outil, soit de répondre directement
• Si outil : l’outil s’exécute, le résultat est ajouté au State, le LLM est rappelé
• Si réponse : le graphe termine

Code : agent avec outil de recherche

# agent_recherche.py
from typing import TypedDict, Annotated
import operator
from langgraph.graph import StateGraph, END
from langgraph.prebuilt import ToolNode
from langchain_anthropic import ChatAnthropic
from langchain_core.messages import HumanMessage
from langchain_core.tools import tool

# 1. Définir un outil
@tool
def rechercher_web(query: str) -> str:
    """Recherche des informations sur le web."""
    # Ici : intégrer Tavily, SerpAPI, etc.
    # Pour l'exemple : retour simulé
    return f"Résultats pour '{query}' : [article 1, article 2, article 3]"

# 2. État
class AgentState(TypedDict):
    messages: Annotated[list, operator.add]

# 3. LLM avec outils liés
llm = ChatAnthropic(model="claude-3-5-sonnet-20241022")
tools = [rechercher_web]
llm_with_tools = llm.bind_tools(tools)

# 4. Noeud agent
def node_agent(state: AgentState) -> dict:
    response = llm_with_tools.invoke(state["messages"])
    return {"messages": [response]}

# 5. Router : l'agent a-t-il appelé un outil ?
def should_continue(state: AgentState) -> str:
    last_message = state["messages"][-1]
    if last_message.tool_calls:
        return "tools"   # → exécuter l'outil
    return END            # → réponse finale

# 6. Assembler
builder = StateGraph(AgentState)
builder.add_node("agent", node_agent)
builder.add_node("tools", ToolNode(tools))  # noeud outil préfabriqué

builder.set_entry_point("agent")
builder.add_conditional_edges("agent", should_continue)
builder.add_edge("tools", "agent")  # retour à l'agent après l'outil

graph = builder.compile()

# 7. Exécuter
result = graph.invoke({
    "messages": [HumanMessage(content="Résume les dernières nouvelles sur LangGraph")]
})
print(result["messages"][-1].content)

6. Persistance — donner de la mémoire à votre agent

Par défaut, chaque invocation de votre graphe repart de zéro. Pour que votre agent se souvienne des échanges précédents, ajoutez un checkpointer.

from langgraph.checkpoint.memory import MemorySaver

# Ajouter la persistance au compile
memory = MemorySaver()
graph = builder.compile(checkpointer=memory)

# Identifier la session avec thread_id
config = {"configurable": {"thread_id": "session-utilisateur-42"}}

# Tour 1
graph.invoke({"messages": [HumanMessage("Bonjour, je m'appelle Vasanth")]}, config)

# Tour 2 — l'agent se souvient du tour 1
result = graph.invoke({"messages": [HumanMessage("Quel est mon prénom ?")]}, config)
print(result["messages"][-1].content)
# → "Vous vous appelez Vasanth."

Récapitulatif — ce que vous savez faire maintenant

Par où aller ensuite

Vous avez les bases. Voici les étapes naturelles selon ce que vous voulez construire :

• Agent multi-outils : ajoutez Tavily (recherche web), des outils de fichiers, une base de données
• Agents en parallèle : LangGraph supporte les sous-graphes et l’exécution parallèle de noeuds
• Supervisor pattern : un agent orchestrateur qui délègue à des agents spécialisés
• Interface utilisateur : combinez avec FastAPI ou Streamlit pour une UI

« LangGraph ne fait pas la magie à votre place — il vous donne le bon modèle mental pour décomposer des problèmes complexes en étapes claires. »