Human-in-the-loop en vrai

Demander vs décider

La première version de notre chat d'ajustement interrogeait l'utilisateur sans fin, une question après l'autre. Insupportable. La bonne posture est act-first : agir par défaut avec des hypothèses explicites, et ne demander que sur un vrai point bloquant.

S'arrêter proprement : interrupt

LangGraph fournit interrupt() : appelé dans un nœud, il suspend le run et remonte une question à ton application. Le graphe ne « bloque » pas un thread serveur — il s'arrête et rend la main.

import { interrupt } from "@langchain/langgraph";
// dans un noeud : suspendre le run et demander a l'humain
function clarify(state) {
  if (state.deadline) return state;          // rien a demander -> on continue
  const answer = interrupt({                 // <- le graphe s'arrete ICI
    question: "Quelle est l'echeance visee ?",
    context: state.brief,
  });
  return { ...state, deadline: answer };     // reprise avec la reponse
}

Reprendre le run

Côté application, le premier appel s'arrête à l'interrupt et te renvoie la question. Tu l'affiches, l'utilisateur répond, et tu relances le même run avec sa réponse via Command({ resume }).

import { Command } from "@langchain/langgraph";
// 1er appel : le graphe tourne jusqu'a l'interrupt, puis rend la main
const first = await graph.invoke({ brief }, config);
// -> first.__interrupt__ contient la question posee a l'utilisateur
// ... on affiche la question, l'utilisateur repond ...
// reprise : on relance le MEME run (meme thread_id) avec la reponse
await graph.invoke(new Command({ resume: "fin mars 2026" }), config);

Durable : survivre à la pause

Pour que l'agent reprenne exactement où il s'était arrêté — même après un redéploiement, ou une réponse deux heures plus tard — l'état doit être persisté. C'est le rôle du checkpointer : il sauvegarde l'état du graphe à chaque étape, ici dans Postgres.

import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres";
// l'etat du run est persiste -> il survit a un reboot, une repons 2h plus tard
const checkpointer = PostgresSaver.fromConnString(process.env.DATABASE_URL);
const graph = builder.compile({ checkpointer });
// chaque run a un thread_id : c'est lui qui permet de reprendre au bon endroit
const config = { configurable: { thread_id: runId } };

Portes d'approbation : agir sous condition

L'act-first a une exception nette : les actions irréversibles. Supprimer des données, envoyer un e-mail à un client, valider un paiement, pousser en prod — là, l'agent ne devine pas, il demande une validation. Anthropic le formule bien dans Building effective agents : on place des points d'arrêt avant les actions à fort enjeu, pas à chaque étape. C'est exactement le même interrupt() que pour une clarification, mais ce qu'on remonte n'est plus une question ouverte — c'est un plan à approuver.

Trois réponses possibles, pas deux

Une bonne porte d'approbation ne se limite pas à « oui / non ». On veut aussi laisser l'humain corriger l'action avant qu'elle parte. Le payload d'interrupt remonte l'action proposée, et la réponse via Command({ resume }) porte la décision — que le nœud réexécute ensuite.

import { interrupt, Command } from "@langchain/langgraph";
// Inside a node, before a destructive tool call
async function sendEmailNode(state: State) {
  const draft = state.pendingEmail;
  // Surface the proposed action, not an open question
  const decision = interrupt({
    kind: "approval",
    action: "send_email",
    to: draft.to,
    subject: draft.subject,
    body: draft.body,
  }) as { type: "accept" | "edit" | "reject"; args?: EmailArgs; reason?: string };
  if (decision.type === "reject") {
    // Loop back with the reason, no side effect fired
    return new Command({
      goto: "plan",
      update: { note: `Email rejected: ${decision.reason}` },
    });
  }
  const finalDraft = decision.type === "edit" ? decision.args! : draft;
  await mailer.send(finalDraft); // the only irreversible line, gated
  return { sent: true };
}

Timeout et escalade

Une porte d'approbation sans limite de temps devient un run zombie : suspendu pour toujours parce que personne n'a répondu. Comme l'état est persisté par le checkpointer (thread_id + Postgres), le run ne coûte rien pendant qu'il attend — mais il faut quand même une politique. En pratique, je stocke un deadline avec le checkpoint et je fais tourner un job qui, passé le délai, relance le thread avec une décision par défaut (souvent reject) ou l'escalade à un autre approbateur.

Checkpoint n'est pas exécution durable

Un checkpointer te donne la reprise : l'état est écrit à chaque étape, tu peux relancer un thread par son thread_id, même après un crash — c'est bien documenté côté Persistence et côté durable execution. Mais reprendre n'est pas exécuter automatiquement jusqu'au bout. Le checkpoint sauve la place ; c'est encore à toi de détecter l'échec et de relancer avec le bon identifiant.

Sources & ressources