Construire votre premier graphe LangGraph en TypeScript

Un graphe avant un agent

Un agent peut donner l’impression que tout dépend du modèle. Commençons par un parcours qui n’appelle aucun LLM : nettoyer un nom, puis produire une salutation. Vous pourrez suivre l’état transmis entre les deux étapes sans vous demander pourquoi un modèle a changé de réponse.

Le résultat visé : l’entrée " Ada " reste disponible, une valeur normalisée devient "Ada", puis un second nœud écrit "Bonjour Ada !".

Lancer le programme

Avec Node.js 22 ou plus récent, téléchargez les exemples, décompressez le dossier et ouvrez-y votre terminal :

npm ci
npm run graph

L’exemple utilise @langchain/langgraph 1.4.19, @langchain/core 1.2.14 et Zod 4.4.3. graph-demo.mts contient le programme complet et ses assertions. Aucun compte de fournisseur ni coût d’API.

L’état est le carnet du parcours

Les nœuds font le travail. Les arêtes indiquent quelle étape exécuter ensuite. L’état rassemble les valeurs partagées entre ces étapes ; chaque nœud renvoie les champs qu’il veut mettre à jour.

import { StateGraph, StateSchema, START, END } from "@langchain/langgraph";
import { z } from "zod";

const GreetingState = new StateSchema({
  name: z.string(),
  normalized: z.string().default(""),
  greeting: z.string().default(""),
});

const graph = new StateGraph(GreetingState)
  .addNode("normaliser", (state) => ({ normalized: state.name.trim() }))
  .addNode("saluer", (state) => ({ greeting: `Bonjour ${state.normalized} !` }))
  .addEdge(START, "normaliser")
  .addEdge("normaliser", "saluer")
  .addEdge("saluer", END)
  .compile();

const result = await graph.invoke({ name: "  Ada  " });

Le premier nœud ne réécrit pas name : il ajoute une mise à jour de normalized. Le second lit cette valeur et met à jour greeting. Vous gardez ainsi l’entrée d’origine et le résultat intermédiaire.

compile prépare le graphe pour l’exécution et vérifie sa structure. Il ne transforme pas la salutation en décision d’un agent. Les nœuds de ce guide sont deux fonctions ordinaires.

Lire le résultat avant d’ajouter de la complexité

Entrée conservée : "  Ada  "
Valeur normalisée : Ada
Résultat : Bonjour Ada !
Deux nœuds, un état transmis, aucun appel LLM.

Le programme vérifie ces valeurs avec des assertions. Une autre sortie doit vous faire inspecter les champs mis à jour et l’ordre des arêtes.

À vous : remplacez Ada par votre prénom, adaptez les assertions puis ajoutez un troisième nœud qui produit une version en majuscules dans un nouveau champ. Dessinez d’abord son emplacement entre saluer et END.

Ce que cet exemple ne fait pas encore

Il n’utilise ni branche conditionnelle, ni mémoire persistante, ni reprise après interruption. Les champs simples conservent la dernière valeur ; si plusieurs étapes doivent accumuler des éléments, il faut choisir un reducer adapté. Ne faites pas écrire deux nœuds parallèles dans le même champ sans comprendre comment leurs mises à jour seront combinées.

Un appel LLM pourrait ensuite vivre dans un nœud. Un appel d’outil pourrait en occuper un autre. Commencez par comprendre son exécution avant de lui confier un effet réel.

Sources : Graph API officielle et penser un parcours LangGraph. La documentation actuelle présente StateSchema ; le dossier verrouillé sert de repère reproductible lorsque les APIs évoluent.