Créez votre premier agent d'IA avec LangGraph sans perdre la tête

Un guide complet à destination des développeurs qui souhaitent créer des systèmes d'IA structurés et intelligents, avec LangGraph !

1. Introduction : Simplifiez la création d'agents IA structurés

La création d'agents d'IA est souvent plus complexe qu'elle ne devrait l'être. La gestion de l'état, le contrôle du flux, la gestion des nouvelles tentatives et l'évitement des boucles infinies peuvent rapidement transformer même les projets simples en un véritable casse-tête. Découvrez comment simplifier le développement de vos agents d'IA.

LangGraph offre une alternative structurée : il vous permet de concevoir des agents d'IA à l'aide de graphes, en utilisant les mêmes principes qui alimentent tout, du routage réseau à l'IA des jeux. Au lieu d'assembler manuellement des invites et de la logique, vous définissez des nœuds (étapes) et des arêtes (connexions) qui forment des flux de travail intelligents. Vos agents peuvent désormais prendre des décisions, se remettre d'échecs, se souvenir du contexte et devenir plus complexes sans devenir ingérables. Gagnez en clarté et en contrôle sur vos agents d'IA.

Dans ce guide, nous allons créer un agent d'IA opérationnel à l'aide de LangGraph. Vous configurerez votre environnement, créerez vos premiers nœuds, les connecterez dans un graphe et déploerez un agent simple mais fonctionnel. En cours de route, nous garderons les explications pratiques, inclurons des exemples de code réels et mettrons en évidence les pièges à éviter. Apprenez à construire pas à pas un agent d'IA fonctionnel.

À la fin, vous aurez non seulement un agent d'IA en cours d'exécution, mais vous comprendrez également comment l'étendre en quelque chose de beaucoup plus puissant. Maîtrisez LangGraph et débloquez le potentiel de vos agents d'IA.

2. Qu'est-ce que LangGraph et pourquoi devriez-vous vous en soucier ? Créez des IA plus sophistiquées

À la base, LangGraph est un framework qui vous permet de créer des agents d'IA en tant que graphes avec état. Au lieu de penser en termes de chaînes simples comme « invite → réponse → invite suivante », vous concevez votre agent comme un graphe : une collection de nœuds (actions, décisions ou invites) et d'arêtes (les chemins entre eux). Découvrez une nouvelle façon de structurer vos agents d'IA.

Chaque nœud traite l'état actuel de l'agent (mémoire, entrée utilisateur, résultats intermédiaires) et décide de ce qui se passe ensuite. Cela pourrait être de passer à un autre nœud, de revenir en arrière, de faire plusieurs appels, ou même de mettre fin à la conversation entièrement. Donnez à vos agents IA une capacité de décision dynamique.

En termes simples :

Chaînes = conversations à voie unique.
Graphes = conversations intelligentes, ramifiées et axées sur la décision.

La puissance des graphes versus les limites des chaînes.

Pourquoi ne pas simplement utiliser des chaînes d'invites basiques ?

Les chaînes d'invites fonctionnent lorsque votre cas d'utilisation est très simple, comme poser quelques questions et donner une réponse. Mais dès que vous voulez :

Mémoire qui persiste à travers les étapes
Prise de décision dynamique
Gestion des erreurs et nouvelles tentatives
Conversations ou flux de travail ramifiés

…les chaînes d'invites s'effondrent. Vous finissez par bricoler des solutions manuellement, et chaque changement risque de casser tout le flux. Évitez l'approche "bricolage" et optez pour la robustesse.

LangGraph, d'autre part, a été construit pour la complexité dès le départ. Il traite le cerveau de l'agent comme un organigramme prévisible, testable et extensible. Créez des agents plus complexes et maintenables grâce à la structure de LangGraph.

Cas d'utilisation concrets de LangGraph

Voici où LangGraph brille :

Agents de support client en plusieurs étapes décidant quand escalader, quand demander des éclaircissements, quand offrir des solutions. Améliorez l'efficacité de votre service client avec des agents intelligents.
Chefs de projet IA planifient des tâches en fonction des objectifs et des échéances, s'adaptant en fonction des commentaires. Automatisez la gestion de projet avec des agents capables de s'adapter.
PNJ de jeux : personnages qui prennent des décisions dynamiques plutôt que de suivre un script fixe. Créez des expériences de jeu plus immersives avec des PNJ réactifs.
Pipelines d'analyse de données collectent des entrées, exécutent des modèles, résument les résultats et prennent différentes actions en fonction des sorties. Optimisez vos flux de travail d'analyse de données avec des agents intelligents.

👉 Repository d'exemples officiel : LangGraph Examples GitHub

LangGraph n'est pas seulement une nouvelle façon de câbler l'IA ; c'est une base plus intelligente sur laquelle s'appuyer à mesure que vos systèmes deviennent plus complexes. Préparez-vous pour l'avenir avec une fondation solide pour vos agents d'IA.

3. Configuration de votre environnement de développement: Prenez un bon départ

Avant d'écrire une logique d'agent sophistiquée, préparons un environnement propre. Pas de magie, pas de surprises, juste les bases. Configurez votre espace de travail pour un développement fluide.

Prérequis

Vous aurez besoin de quelques éléments installés :

Python 3.10 ou supérieur (Oui, 3.10+. LangGraph utilise des fonctionnalités de typage plus récentes que les versions antérieures ne prennent pas en charge.) Assurez-vous d'avoir la bonne version de Python.
pip pour installer les packages Python Gérez facilement vos dépendances Python.
Un éditeur de code VS Code est un choix solide Choisissez l'environnement de développement qui vous convient.

Facultatif mais utile :

virtualenv pour isoler les dépendances de votre projet Isolez vos projets pour éviter les conflits.
Familiarité de base avec async/await en Python (nous garderons les exemples conviviaux pour les débutants) Apprenez les bases de la programmation asynchrone.

Installation de LangGraph

Installons les outils principaux dont vous aurez besoin. Dans votre terminal, exécutez :

pip install langgraph langchain openai

Cela extrait :

langgraph : la bibliothèque de graphes principale Le cœur de votre projet d'agent IA.
langchain : des utilitaires utiles comme la mémoire, les agents et les outils Facilitez le développement avec des outils pratiques.
openai : si vous voulez vous connecter à des LLM comme GPT-4, Claude, etc. Connectez-vous aux modèles de langage les plus puissants.

(Vous n'êtes pas obligé d'utiliser OpenAI spécifiquement — LangGraph est agnostique du modèle.)

Configuration du projet

Mettons en place un répertoire de projet propre :

mkdir langgraph_agent
cd langgraph_agent
python -m venv venv
source venv/bin/activate  # Sous Windows: venv\Scripts\activate
pip install langgraph langchain openai
touch agent.py

Votre dossier devrait maintenant ressembler à ceci :

langgraph_agent/
├── venv/
└── agent.py

Ouvrez agent.py — c'est là que toute la magie opère. Préparez votre fichier principal pour le code de votre agent IA.

Note rapide sur les clés API

Si vous prévoyez d'utiliser des LLM comme OpenAI ou Anthropic, vous aurez besoin de clés API.

Une bonne pratique est de les stocker dans une variable d'environnement :

export OPENAI_API_KEY="votre-clé-openai"

Ou, utilisez un fichier .env avec python-dotenv si vous voulez rester organisé. (Facultatif, mais recommandé pour tout ce qui est sérieux.) Sécurisez et organisez vos clés API.

Première vérification de bon fonctionnement

Vérifions que tout est câblé.

Dans agent.py, mettez :

import langgraph

print(f"Version de LangGraph: {langgraph.__version__}")

Exécutez :

python agent.py

Vous devriez voir le numéro de version imprimé sans erreurs.

Si vous obtenez une ImportError, vérifiez que votre environnement virtuel est activé. Assurez-vous que votre installation est correcte.

Maintenant que vous êtes entièrement prêt. Ensuite, nous plongerons dans le cerveau réel de LangGraph : les nœuds, les arêtes et l'état.

(Indice : c'est moins effrayant qu'il n'y paraît.)

4. Comprendre les bases : Nœuds, Arêtes et État: Maîtrisez le vocabulaire de LangGraph

Avant de commencer à écrire la logique d'agent réelle, il est important de comprendre comment LangGraph pense. Adoptez la mentalité LangGraph pour un développement efficace.

Si vous imaginez votre agent d'IA comme un personnage de jeu naviguant dans un donjon, alors :

Les nœuds sont les pièces Visualisez vos actions comme des étapes distinctes.
Les arêtes sont les couloirs reliant les pièces Définissez le flux de votre agent à travers les étapes.
L'état est le sac à dos que le personnage porte (mémoire, entrées, sorties, contexte) Suivez l'évolution de l'agent avec un état centralisé.

L'agent se déplace de nœud en nœud, suivant les arêtes, tout en mettant à jour son état en cours de route.

Simple, mais incroyablement puissant.

Qu'est-ce qu'un nœud ?

Un nœud est juste une fonction Python qui fait une chose :

Elle prend l'état actuel (un dictionnaire par défaut),
Le traite,
Renvoie l'état mis à jour.

C'est tout. Les nœuds peuvent appeler des API, générer du texte, vérifier des conditions, modifier la mémoire — peu importe ce dont votre agent a besoin à ce stade. Chaque nœud est une action spécialisée dans le flux de votre agent.

Exemple :

async def greet_node(state):
    user_name = state.get('user_name', 'there')
    state['message'] = f"Bonjour, {user_name} !"
    return state

Qu'est-ce qu'une arête ?

Une arête connecte un nœud à un autre.

Une fois qu'un nœud a terminé son travail, LangGraph vérifie quelle arête suivre ensuite en fonction de votre configuration. Les arêtes peuvent être simples (aller toujours au nœud B) ou dynamiques (si la condition X, aller au nœud B ; sinon le nœud C). Contrôlez le cheminement de votre agent en définissant des règles de transition claires.

Vous programmez essentiellement le flux de conversation en connectant des nœuds avec des arêtes intelligentes.

Exemple de mappage d'arêtes :

edges = {
    "start": "greet",
    "greet": "ask_question",
    "ask_question": "end",
}

Qu'est-ce que l'état ?

L'état est un dictionnaire qui voyage avec votre agent à travers le graphe.

Chaque nœud peut :

Lire à partir de l'état
Mettre à jour l'état
Le transmettre au nœud suivant.

Exemple d'état :

{
    "user_name": "Alice",
    "message": "Bonjour, Alice !",
    "questions_asked": 1,
}

L'état est la raison pour laquelle les agents LangGraph peuvent avoir de la mémoire, réessayer intelligemment et rester conscients du contexte à travers des flux complexes. L'état est la clé pour des agents d'IA contextuels et dynamiques.

Pourquoi est-ce important ?

Sans une conception claire des nœuds/arêtes/état, votre agent se transforme rapidement en un « monstre spaghetti » difficile à déboguer, plus difficile à étendre. LangGraph vous force à penser de manière structurée, rendant les agents modulaires, testables et plus intelligents au fil du temps. LangGraph impose une structure pour éviter le chaos dans vos projets d'IA.

Une fois que vous internalisez ce modèle, la construction d'un comportement d'IA complexe ressemble beaucoup plus à la construction d'une quête de jeu ou d'une API propre — pas comme le fait de coller des invites avec du ruban adhésif. Transformez vos agents IA en systèmes élégants et maintenables.

5. Construire votre premier nœud (avec du code): Écrivez votre première action IA

Maintenant que vous comprenez les nœuds, les arêtes et l'état, écrivons-en réellement un. Nous allons commencer simplement : un nœud de salutation qui prend le nom d'un utilisateur de l'état et génère un message de bienvenue. Créez un nœud de salutation simple pour votre agent.

Création d'un nœud simple

Dans agent.py, ajoutez :

async def greet_node(state: dict) -> dict:
    user_name = state.get("user_name", "ami")
    greeting = f"Bonjour, {user_name} ! Bienvenue à bord."
    state["greeting"] = greeting
    return state

Ce qui se passe ici :

Nous lisons "user_name" du dictionnaire d'état.
Si aucun nom n'est fourni, nous utilisons "ami" par défaut.
Nous créons un message de salutation.
Nous mettons à jour l'état avec une nouvelle clé "greeting".

Le nœud est asynchrone (async) parce que les nœuds du monde réel impliquent souvent d'attendre comme appeler une API ou accéder à une base de données. Préparez vos agents pour les opérations asynchrones du monde réel.

Bonnes pratiques pour écrire des nœuds

Toujours accepter et renvoyer le dictionnaire d'état. Maintenez le flux d'informations cohérent.
Gardez chaque nœud concentré sur une tâche (p. ex., générer une salutation, pas générer et vérifier en une seule fois). Faites en sorte que chaque action soit claire et isolée.
Écrivez des nœuds pour être sans état en interne — utilisez seulement ce qui est dans l'entrée d'état. Évitez les dépendances externes pour une plus grande prévisibilité.
Gérez les valeurs manquantes gracieusement (valeurs par défaut, try/except si nécessaire). Assurez-vous que votre agent peut gérer les données inattendues.

Test local rapide

Exécutons manuellement ce nœud à vérifier :

import asyncio

async def test():
    state = {"user_name": "Alex"}
    updated_state = await greet_node(state)
    print(updated_state)

asyncio.run(test())

✅ Vous devriez voir :

{ 'user_name': 'Alex', 'greeting': 'Bonjour, Alex ! Bienvenue à bord.'}

Si cela fonctionne, félicitations, vous venez de créer votre premier nœud LangGraph fonctionnel. Validez votre code avec des tests simples.

Récapitulatif :

Les nœuds sont des fonctions asynchrones.
Ils prennent un dictionnaire d'état, le modifient et le renvoient.
Gardez chaque nœud petit et facile à comprendre. La simplicité est la clé de la maintenance à long terme.

6. Connecter les nœuds : Construire un graphe: Assemblez votre agent IA

Un nœud seul ne fait pas grand-chose. La vraie puissance de LangGraph vient de la connexion de plusieurs nœuds dans un graphe flexible et intelligent. Créez un flux de travail complexe en connectant des actions individuelles.

Câblons un agent de base à deux nœuds :

Nœud 1 : Saluer l'utilisateur
Nœud 2 : Poser une question

Écrire le deuxième nœud

Dans agent.py, ajoutez :

async def ask_question_node(state: dict) -> dict:
    question = "Que puis-je faire pour vous aujourd'hui ?"
    state["question"] = question
    return state

Ce nœud ajoute juste une question polie à l'état. Ajoutez la prochaine étape logique à votre agent.

Définir le graphe

Connectons maintenant les deux nœuds.

Importez les pièces LangGraph nécessaires en premier :

from langgraph.graph import StateGraph, END

Ensuite, construisez le graphe :

# Étape 1 : Définir la structure d'état
class AgentState(dict):
    pass  # Pour les cas simples, vous pouvez hériter de dict

# Étape 2 : Créer le graphe
graph = StateGraph(AgentState)

# Étape 3 : Ajouter des nœuds
graph.add_node("greet", greet_node)
graph.add_node("ask", ask_question_node)

# Étape 4 : Connecter les nœuds
graph.set_entry_point("greet")
graph.add_edge("greet", "ask")
graph.add_edge("ask", END)

# Étape 5 : Compiler le graphe
app = graph.compile()

Ce que ce graphe fait :

Commence au nœud de salutation.
Passe automatiquement au nœud ask.
Termine la conversation après que la question a été posée.

C'est l'agent opérationnel le plus petit possible : greet → ask → done. Chaque agent complexe commence par un flux de base.

Vue d'ensemble visuelle

Si nous dessinions ce graphe simple, il ressemblerait à ceci :

[greet] --> [ask] --> [END]

Chaque agent d'IA du monde réel, peu importe sa complexité, n'est qu'une version mise à l'échelle de ce schéma. Visualisez votre agent comme un graphe pour simplifier la conception.

Maintenant que nous avons une structure de graphe, il est temps de l'exécuter et de tester le flux d'agent complet.

7. Exécuter et tester votre agent: Donnez vie à votre IA

Maintenant que nous avons défini les nœuds et les avons connectés avec des arêtes, il est temps d'exécuter le graphe et de voir l'agent en action. Observez votre agent en action et identifiez les améliorations.

L'exécution d'un agent LangGraph est simple : vous invoquez l'objet de graphe compilé et passez l'état initial.

Exécuter le graphe

Au bas de votre fichier agent.py, ajoutez :

import asyncio

async def main():
    initial_state = {"user_name": "Alex"}
    final_state = await app.invoke(initial_state)
    print(final_state)

if __name__ == "__main__":
    asyncio.run(main())

Voici la répartition :

initial_state est le premier sac à dos que votre agent transporte. Définissez l'état de départ de votre agent.
app.invoke() commence au nœud d'entrée et se déplace dans le graphe en suivant vos arêtes. Lancez le flux de travail de votre agent.
Chaque nœud met à jour l'état étape par étape.
À la fin, vous obtenez l'état final après que tous les nœuds ont fini de s'exécuter.

Sortie attendue

L'exécution du script devrait afficher quelque chose comme :

{ 'user_name': 'Alex', 'greeting': 'Bonjour, Alex ! Bienvenue à bord.', 'question': 'Que puis-je faire pour vous aujourd'hui ?'}

Si vous voyez cela, félicitations, votre premier agent d'IA alimenté par LangGraph est en direct ! Célébrez votre réalisation et préparez-vous à itérer.

Conseils de débogage

Si rien ne se passe, assurez-vous que vous avez compilé votre graphe (graph.compile()).
Si votre agent plante, vérifiez les fautes de frappe dans les noms de nœuds ou le async manquant dans vos fonctions.
Commencez toujours simplement — un nœud à la fois — et développez graduellement une fois que chaque élément est solide. Déboguez en divisant le problème en morceaux gérables.

La structure propre de LangGraph le rend beaucoup plus facile à déboguer par rapport aux chaînes d'invites traditionnelles ou aux boîtes à outils désordonnées. Profitez d'une structure qui facilite le débogage.

8. Exemple d'agent du monde réel : Bot de questions-réponses plus intelligent: Construisez un agent plus sophistiqué

Maintenant que vous avez un graphe de base en marche, passons à un niveau supérieur. Nous allons construire un agent légèrement plus intelligent qui salue l'utilisateur, pose une question et répond intelligemment en fonction de l'entrée. Créez un agent capable de comprendre et de répondre aux entrées utilisateur.

Cela se rapproche de la façon dont les agents du monde réel se comportent.

Ce que cet agent va faire

Nœud 1 : Saluer l'utilisateur.
Nœud 2 : Demander de quoi ils ont besoin d'aide.
Nœud 3 : Analyser la réponse de l'utilisateur et répondre de manière appropriée.

Nœuds mis à jour

Tout d'abord, modifiez votre agent.py pour ajouter un nouveau nœud :

async def answer_node(state: dict) -> dict:
    user_input = state.get("user_input", "").lower()
    if "météo" in user_input:
        state["response"] = "Le temps aujourd'hui est ensoleillé avec une légère brise."
    elif "heure" in user_input:
        state["response"] = "Il est 14h00 heure locale."
    else:
        state["response"] = "Je ne suis pas sûr de ça, mais je peux le découvrir pour vous !"
    return state

Structure de graphe mise à jour

Mettez à jour votre définition de graphe :

# Ajouter un nouveau nœud
graph.add_node("answer", answer_node)

# Mettre à jour les connexions
graph.add_edge("greet", "ask")
graph.add_edge("ask", "answer")
graph.add_edge("answer", END)

Maintenant, le flux de l'agent est :

[greet] --> [ask] --> [answer] --> [END]

Gérer l'entrée de l'utilisateur

Nous allons modifier la fonction main() pour simuler l'entrée de l'utilisateur aussi :

async def main():
    initial_state = {
        "user_name": "Alex",
        "user_input": "Pouvez-vous me dire la météo ?",
    }
    final_state = await app.invoke(initial_state)
    print(final_state)

Lorsque vous l'exécutez, vous devriez obtenir :

{ 'user_name': 'Alex', 'user_input': 'Pouvez-vous me dire la météo ?', 'greeting': 'Bonjour, Alex ! Bienvenue à bord.', 'question': 'Que puis-je faire pour vous aujourd'hui ?', 'response': 'Le temps aujourd'hui est ensoleillé avec une légère brise.'}

Pourquoi cet exemple est important

Ce minuscule agent montre déjà les principes clés utilisés dans les vrais systèmes d'IA :

Gestion d'état (passage des entrées utilisateur proprement entre les étapes) Assurez-vous que vos données sont transmises correctement entre les nœuds.
Pr

Créez votre premier agent d'IA avec LangGraph sans perdre la tête

Un guide complet à destination des développeurs qui souhaitent créer des systèmes d'IA structurés et intelligents, avec LangGraph !

1. Introduction : Simplifiez la création d'agents IA structurés

2. Qu'est-ce que LangGraph et pourquoi devriez-vous vous en soucier ? Créez des IA plus sophistiquées

En termes simples :

Chaînes = conversations à voie unique.
Graphes = conversations intelligentes, ramifiées et axées sur la décision.

La puissance des graphes versus les limites des chaînes.

Pourquoi ne pas simplement utiliser des chaînes d'invites basiques ?

Les chaînes d'invites fonctionnent lorsque votre cas d'utilisation est très simple, comme poser quelques questions et donner une réponse. Mais dès que vous voulez :

Mémoire qui persiste à travers les étapes
Prise de décision dynamique
Gestion des erreurs et nouvelles tentatives
Conversations ou flux de travail ramifiés

Cas d'utilisation concrets de LangGraph

Voici où LangGraph brille :

Agents de support client en plusieurs étapes décidant quand escalader, quand demander des éclaircissements, quand offrir des solutions. Améliorez l'efficacité de votre service client avec des agents intelligents.
Chefs de projet IA planifient des tâches en fonction des objectifs et des échéances, s'adaptant en fonction des commentaires. Automatisez la gestion de projet avec des agents capables de s'adapter.
PNJ de jeux : personnages qui prennent des décisions dynamiques plutôt que de suivre un script fixe. Créez des expériences de jeu plus immersives avec des PNJ réactifs.
Pipelines d'analyse de données collectent des entrées, exécutent des modèles, résument les résultats et prennent différentes actions en fonction des sorties. Optimisez vos flux de travail d'analyse de données avec des agents intelligents.

👉 Repository d'exemples officiel : LangGraph Examples GitHub

3. Configuration de votre environnement de développement: Prenez un bon départ

Prérequis

Vous aurez besoin de quelques éléments installés :

Python 3.10 ou supérieur (Oui, 3.10+. LangGraph utilise des fonctionnalités de typage plus récentes que les versions antérieures ne prennent pas en charge.) Assurez-vous d'avoir la bonne version de Python.
pip pour installer les packages Python Gérez facilement vos dépendances Python.
Un éditeur de code VS Code est un choix solide Choisissez l'environnement de développement qui vous convient.

Facultatif mais utile :

virtualenv pour isoler les dépendances de votre projet Isolez vos projets pour éviter les conflits.
Familiarité de base avec async/await en Python (nous garderons les exemples conviviaux pour les débutants) Apprenez les bases de la programmation asynchrone.

Installation de LangGraph

Installons les outils principaux dont vous aurez besoin. Dans votre terminal, exécutez :

pip install langgraph langchain openai

Cela extrait :

langgraph : la bibliothèque de graphes principale Le cœur de votre projet d'agent IA.
langchain : des utilitaires utiles comme la mémoire, les agents et les outils Facilitez le développement avec des outils pratiques.
openai : si vous voulez vous connecter à des LLM comme GPT-4, Claude, etc. Connectez-vous aux modèles de langage les plus puissants.

(Vous n'êtes pas obligé d'utiliser OpenAI spécifiquement — LangGraph est agnostique du modèle.)

Configuration du projet

Mettons en place un répertoire de projet propre :

mkdir langgraph_agent
cd langgraph_agent
python -m venv venv
source venv/bin/activate  # Sous Windows: venv\Scripts\activate
pip install langgraph langchain openai
touch agent.py

Votre dossier devrait maintenant ressembler à ceci :

langgraph_agent/
├── venv/
└── agent.py

Ouvrez agent.py — c'est là que toute la magie opère. Préparez votre fichier principal pour le code de votre agent IA.

Note rapide sur les clés API

Si vous prévoyez d'utiliser des LLM comme OpenAI ou Anthropic, vous aurez besoin de clés API.

Une bonne pratique est de les stocker dans une variable d'environnement :

export OPENAI_API_KEY="votre-clé-openai"

Ou, utilisez un fichier .env avec python-dotenv si vous voulez rester organisé. (Facultatif, mais recommandé pour tout ce qui est sérieux.) Sécurisez et organisez vos clés API.

Première vérification de bon fonctionnement

Vérifions que tout est câblé.

Dans agent.py, mettez :

import langgraph

print(f"Version de LangGraph: {langgraph.__version__}")

Exécutez :

python agent.py

Vous devriez voir le numéro de version imprimé sans erreurs.

Si vous obtenez une ImportError, vérifiez que votre environnement virtuel est activé. Assurez-vous que votre installation est correcte.

Maintenant que vous êtes entièrement prêt. Ensuite, nous plongerons dans le cerveau réel de LangGraph : les nœuds, les arêtes et l'état.

(Indice : c'est moins effrayant qu'il n'y paraît.)

4. Comprendre les bases : Nœuds, Arêtes et État: Maîtrisez le vocabulaire de LangGraph

Avant de commencer à écrire la logique d'agent réelle, il est important de comprendre comment LangGraph pense. Adoptez la mentalité LangGraph pour un développement efficace.

Si vous imaginez votre agent d'IA comme un personnage de jeu naviguant dans un donjon, alors :

Les nœuds sont les pièces Visualisez vos actions comme des étapes distinctes.
Les arêtes sont les couloirs reliant les pièces Définissez le flux de votre agent à travers les étapes.
L'état est le sac à dos que le personnage porte (mémoire, entrées, sorties, contexte) Suivez l'évolution de l'agent avec un état centralisé.

L'agent se déplace de nœud en nœud, suivant les arêtes, tout en mettant à jour son état en cours de route.

Simple, mais incroyablement puissant.

Qu'est-ce qu'un nœud ?

Un nœud est juste une fonction Python qui fait une chose :

Elle prend l'état actuel (un dictionnaire par défaut),
Le traite,
Renvoie l'état mis à jour.

Exemple :

async def greet_node(state):
    user_name = state.get('user_name', 'there')
    state['message'] = f"Bonjour, {user_name} !"
    return state

Qu'est-ce qu'une arête ?

Une arête connecte un nœud à un autre.

Vous programmez essentiellement le flux de conversation en connectant des nœuds avec des arêtes intelligentes.

Exemple de mappage d'arêtes :

edges = {
    "start": "greet",
    "greet": "ask_question",
    "ask_question": "end",
}

Qu'est-ce que l'état ?

L'état est un dictionnaire qui voyage avec votre agent à travers le graphe.

Chaque nœud peut :

Lire à partir de l'état
Mettre à jour l'état
Le transmettre au nœud suivant.

Exemple d'état :

{
    "user_name": "Alice",
    "message": "Bonjour, Alice !",
    "questions_asked": 1,
}

Pourquoi est-ce important ?

5. Construire votre premier nœud (avec du code): Écrivez votre première action IA

Création d'un nœud simple

Dans agent.py, ajoutez :

async def greet_node(state: dict) -> dict:
    user_name = state.get("user_name", "ami")
    greeting = f"Bonjour, {user_name} ! Bienvenue à bord."
    state["greeting"] = greeting
    return state

Ce qui se passe ici :

Nous lisons "user_name" du dictionnaire d'état.
Si aucun nom n'est fourni, nous utilisons "ami" par défaut.
Nous créons un message de salutation.
Nous mettons à jour l'état avec une nouvelle clé "greeting".

Bonnes pratiques pour écrire des nœuds

Toujours accepter et renvoyer le dictionnaire d'état. Maintenez le flux d'informations cohérent.
Gardez chaque nœud concentré sur une tâche (p. ex., générer une salutation, pas générer et vérifier en une seule fois). Faites en sorte que chaque action soit claire et isolée.
Écrivez des nœuds pour être sans état en interne — utilisez seulement ce qui est dans l'entrée d'état. Évitez les dépendances externes pour une plus grande prévisibilité.
Gérez les valeurs manquantes gracieusement (valeurs par défaut, try/except si nécessaire). Assurez-vous que votre agent peut gérer les données inattendues.

Test local rapide

Exécutons manuellement ce nœud à vérifier :

import asyncio

async def test():
    state = {"user_name": "Alex"}
    updated_state = await greet_node(state)
    print(updated_state)

asyncio.run(test())

✅ Vous devriez voir :

{ 'user_name': 'Alex', 'greeting': 'Bonjour, Alex ! Bienvenue à bord.'}

Si cela fonctionne, félicitations, vous venez de créer votre premier nœud LangGraph fonctionnel. Validez votre code avec des tests simples.

Récapitulatif :

Les nœuds sont des fonctions asynchrones.
Ils prennent un dictionnaire d'état, le modifient et le renvoient.
Gardez chaque nœud petit et facile à comprendre. La simplicité est la clé de la maintenance à long terme.

6. Connecter les nœuds : Construire un graphe: Assemblez votre agent IA

Câblons un agent de base à deux nœuds :

Nœud 1 : Saluer l'utilisateur
Nœud 2 : Poser une question

Écrire le deuxième nœud

Dans agent.py, ajoutez :

async def ask_question_node(state: dict) -> dict:
    question = "Que puis-je faire pour vous aujourd'hui ?"
    state["question"] = question
    return state

Ce nœud ajoute juste une question polie à l'état. Ajoutez la prochaine étape logique à votre agent.

Définir le graphe

Connectons maintenant les deux nœuds.

Importez les pièces LangGraph nécessaires en premier :

from langgraph.graph import StateGraph, END

Ensuite, construisez le graphe :

# Étape 1 : Définir la structure d'état
class AgentState(dict):
    pass  # Pour les cas simples, vous pouvez hériter de dict

# Étape 2 : Créer le graphe
graph = StateGraph(AgentState)

# Étape 3 : Ajouter des nœuds
graph.add_node("greet", greet_node)
graph.add_node("ask", ask_question_node)

# Étape 4 : Connecter les nœuds
graph.set_entry_point("greet")
graph.add_edge("greet", "ask")
graph.add_edge("ask", END)

# Étape 5 : Compiler le graphe
app = graph.compile()

Ce que ce graphe fait :

Commence au nœud de salutation.
Passe automatiquement au nœud ask.
Termine la conversation après que la question a été posée.

C'est l'agent opérationnel le plus petit possible : greet → ask → done. Chaque agent complexe commence par un flux de base.

Vue d'ensemble visuelle

Si nous dessinions ce graphe simple, il ressemblerait à ceci :

[greet] --> [ask] --> [END]

Chaque agent d'IA du monde réel, peu importe sa complexité, n'est qu'une version mise à l'échelle de ce schéma. Visualisez votre agent comme un graphe pour simplifier la conception.

Maintenant que nous avons une structure de graphe, il est temps de l'exécuter et de tester le flux d'agent complet.

7. Exécuter et tester votre agent: Donnez vie à votre IA

L'exécution d'un agent LangGraph est simple : vous invoquez l'objet de graphe compilé et passez l'état initial.

Exécuter le graphe

Au bas de votre fichier agent.py, ajoutez :

import asyncio

async def main():
    initial_state = {"user_name": "Alex"}
    final_state = await app.invoke(initial_state)
    print(final_state)

if __name__ == "__main__":
    asyncio.run(main())

Voici la répartition :

initial_state est le premier sac à dos que votre agent transporte. Définissez l'état de départ de votre agent.
app.invoke() commence au nœud d'entrée et se déplace dans le graphe en suivant vos arêtes. Lancez le flux de travail de votre agent.
Chaque nœud met à jour l'état étape par étape.
À la fin, vous obtenez l'état final après que tous les nœuds ont fini de s'exécuter.

Sortie attendue

L'exécution du script devrait afficher quelque chose comme :

{ 'user_name': 'Alex', 'greeting': 'Bonjour, Alex ! Bienvenue à bord.', 'question': 'Que puis-je faire pour vous aujourd'hui ?'}

Si vous voyez cela, félicitations, votre premier agent d'IA alimenté par LangGraph est en direct ! Célébrez votre réalisation et préparez-vous à itérer.

Conseils de débogage

Si rien ne se passe, assurez-vous que vous avez compilé votre graphe (graph.compile()).
Si votre agent plante, vérifiez les fautes de frappe dans les noms de nœuds ou le async manquant dans vos fonctions.
Commencez toujours simplement — un nœud à la fois — et développez graduellement une fois que chaque élément est solide. Déboguez en divisant le problème en morceaux gérables.

8. Exemple d'agent du monde réel : Bot de questions-réponses plus intelligent: Construisez un agent plus sophistiqué

Cela se rapproche de la façon dont les agents du monde réel se comportent.

Ce que cet agent va faire

Nœud 1 : Saluer l'utilisateur.
Nœud 2 : Demander de quoi ils ont besoin d'aide.
Nœud 3 : Analyser la réponse de l'utilisateur et répondre de manière appropriée.

Nœuds mis à jour

Tout d'abord, modifiez votre agent.py pour ajouter un nouveau nœud :

async def answer_node(state: dict) -> dict:
    user_input = state.get("user_input", "").lower()
    if "météo" in user_input:
        state["response"] = "Le temps aujourd'hui est ensoleillé avec une légère brise."
    elif "heure" in user_input:
        state["response"] = "Il est 14h00 heure locale."
    else:
        state["response"] = "Je ne suis pas sûr de ça, mais je peux le découvrir pour vous !"
    return state

Structure de graphe mise à jour

Mettez à jour votre définition de graphe :

# Ajouter un nouveau nœud
graph.add_node("answer", answer_node)

# Mettre à jour les connexions
graph.add_edge("greet", "ask")
graph.add_edge("ask", "answer")
graph.add_edge("answer", END)

Maintenant, le flux de l'agent est :

[greet] --> [ask] --> [answer] --> [END]

Gérer l'entrée de l'utilisateur

Nous allons modifier la fonction main() pour simuler l'entrée de l'utilisateur aussi :

async def main():
    initial_state = {
        "user_name": "Alex",
        "user_input": "Pouvez-vous me dire la météo ?",
    }
    final_state = await app.invoke(initial_state)
    print(final_state)

Lorsque vous l'exécutez, vous devriez obtenir :

{ 'user_name': 'Alex', 'user_input': 'Pouvez-vous me dire la météo ?', 'greeting': 'Bonjour, Alex ! Bienvenue à bord.', 'question': 'Que puis-je faire pour vous aujourd'hui ?', 'response': 'Le temps aujourd'hui est ensoleillé avec une légère brise.'}

Pourquoi cet exemple est important

Ce minuscule agent montre déjà les principes clés utilisés dans les vrais systèmes d'IA :

Gestion d'état (passage des entrées utilisateur proprement entre les étapes) Assurez-vous que vos données sont transmises correctement entre les nœuds.
Pr