GuidesOneMux

Appels d’outils LangGraph avec exécution bornée et reprise après échec

Créez un agent d’exploitation de production avec LangGraph qui utilise les appels d’outils, des budgets de tentatives, une approbation humaine et des voies de reprise explicites plutôt qu’une exécution sans limites.

AI

Résumé · TL;DR

Un agent d’exploitation de production ne doit pas pouvoir réessayer indéfiniment ni répéter aveuglément des effets de bord. LangGraph fournit le graphe et le modèle de persistance nécessaires pour suspendre l’exécution, tandis que le flux de travail doit définir les budgets de tentatives, les règles d’idempotence, les voies d’escalade et les états de reprise. HumanInTheLoopMiddleware peut soumettre les appels d’outils à risque à une validation humaine et les reprendre à partir d’un point de reprise après approbation, modification, rejet ou réponse directe.

Points clés

  • Distinguez les erreurs temporaires des erreurs permanentes avant de décider de réessayer.
  • Limitez l’exécution à l’aide d’un budget de tentatives par outil et d’une limite d’étapes au niveau du graphe.
  • Utilisez des clés d’idempotence pour les outils qui créent, suppriment ou modifient des ressources de production.
  • Soumettez les actions destructrices ou visibles de l’extérieur à une approbation humaine.
  • Persistez l’état du graphe afin qu’un flux interrompu puisse reprendre sans repartir de zéro.
Sur cette page (9)

Le choix de conception : réessayer automatiquement ou gérer la reprise de manière délibérée ?

Pour les opérations de flux de travail en production, le choix par défaut le plus sûr n’est pas « réessayer à chaque échec ». Il consiste à :

  1. Ne réessayer que les erreurs vraisemblablement temporaires.
  2. S’arrêter après un nombre limité et explicitement défini de tentatives.
  3. Transférer les tâches épuisées ou ambiguës vers un état de reprise.
  4. Exiger une approbation avant les effets de bord potentiellement coûteux ou irréversibles.

LangGraph convient bien à ce cas, car le flux de travail peut représenter ces résultats sous forme d’états du graphe plutôt que de les dissimuler dans une grande boucle d’agent. Le modèle peut proposer des appels d’outils, mais du code déterministe décide si un appel peut être exécuté, réessayé, transmis ou ignoré sans risque.

Les exemples ci-dessous illustrent des modèles de conception. Il ne s’agit pas d’une application testée, et les API exactes peuvent varier selon les versions de LangGraph et LangChain installées.

Prérequis

Vous aurez besoin de :

  • Python et de packages LangGraph et LangChain compatibles.
  • Un modèle de conversation prenant en charge les appels d’outils via l’intégration de votre choix.
  • Des outils dotés de schémas d’entrée explicites et de types d’erreur prévisibles.
  • Un checkpointer. InMemorySaver convient aux essais ; la documentation LangGraph recommande un checkpointer persistant tel que AsyncPostgresSaver ou MongoDBSaver en production.
  • Un thread_id stable pour chaque exécution de flux de travail.

Ne donnez pas au modèle un accès sans restriction aux identifiants de production. Intégrez l’autorisation, la validation, l’idempotence et la stratégie de nouvelles tentatives aux outils ou au middleware.

Définir un outil borné pouvant être relancé

La première limite doit encadrer l’opération elle-même. Cet exemple ne réessaie qu’une erreur temporaire catégorisée et renvoie un résultat structuré lorsque le budget est épuisé.

from dataclasses import dataclass
from typing import Literal

class TransientOperationError(Exception):
    pass

class PermanentOperationError(Exception):
    pass

@dataclass
class OperationResult:
    status: Literal["succeeded", "needs_recovery", "failed"]
    attempts: int
    message: str


def run_with_budget(operation, *, max_attempts: int) -> OperationResult:
    for attempt in range(1, max_attempts + 1):
        try:
            operation()
            return OperationResult("succeeded", attempt, "Operation completed")
        except PermanentOperationError as exc:
            return OperationResult("failed", attempt, str(exc))
        except TransientOperationError as exc:
            if attempt == max_attempts:
                return OperationResult(
                    "needs_recovery", attempt,
                    f"Retry budget exhausted: {exc}",
                )

    return OperationResult("needs_recovery", max_attempts, "No attempt was made")

Dans les opérations réelles, ajoutez une clé d’idempotence avant de réessayer. Un délai d’attente dépassé après une demande de déploiement ne prouve pas que le déploiement n’a pas eu lieu. Réessayer sans clé pourrait créer un doublon de tâche, de ticket, de paiement ou de demande de modification.

Un tableau de règles utile pourrait ressembler à ceci :

Catégorie d’échecAction automatiqueAction de reprise
Délai d’attente temporaire du réseauRéessayer dans la limite du budgetTransmettre avec l’ID de l’opération
Limitation de débitRéessayer selon les indications du fournisseurMettre le flux en file d’attente ou le différer
Arguments non validesNe pas réessayerRenvoyer une erreur de validation à l’agent
Échec d’autorisationNe pas réessayerDemander une autorisation ou s’arrêter
Résultat inconnu après un délai d’attenteNe pas répéter aveuglémentVérifier l’état à l’aide de la clé d’idempotence

Ajouter les appels d’outils et l’approbation humaine

create_agent de LangChain s’appuie sur l’exécution LangGraph. La documentation LangGraph fournie décrit HumanInTheLoopMiddleware, qui peut interrompre certains appels d’outils et les reprendre à partir d’un état persistant.

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model="provider:model-name",
    tools=[inspect_job, restart_job, delete_artifact],
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "inspect_job": False,
                "restart_job": {
                    "allowed_decisions": ["approve", "reject"]
                },
                "delete_artifact": {
                    "allowed_decisions": ["approve", "edit", "reject"]
                },
            },
            interrupt_mode="per_call",
        ),
    ],
    checkpointer=InMemorySaver(),
)

Ici, l’inspection s’effectue sans vérification, tandis que le redémarrage et la suppression sont suspendus dans l’attente d’une décision. approve exécute les arguments d’origine, edit modifie les arguments avant l’exécution et reject ignore l’appel et renvoie à l’agent un retour indiquant le rejet. La source décrit également respond pour agir comme un outil de type « ask user » ; il ne faut pas l’utiliser pour refuser un outil produisant des effets de bord, car cette action est considérée comme un résultat d’outil réussi.

En production, remplacez le checkpointer en mémoire par une implémentation persistante et invoquez l’agent avec un ID de thread stable :

config = {
    "configurable": {"thread_id": "ops-workflow-1842"}
}

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Inspect the failed job and restart it if safe.",
            }
        ]
    },
    config=config,
    version="v2",
)

Avec la version v2, un résultat interrompu expose une collection interrupts. Présentez chaque action demandée à une personne habilitée à la valider, puis reprenez le même thread avec le format de décision Command documenté.

Respecter l’ordre adéquat entre nouvelles tentatives et approbation

La documentation source souligne une règle importante concernant le middleware : lors d’une vérification par appel, placez la gestion de l’intervention humaine avant le middleware de nouvelle tentative ou de gestion des erreurs. Sinon, une nouvelle tentative peut entraîner une nouvelle demande de validation, ou une réponse non valide peut être réessayée comme s’il s’agissait d’un échec de l’outil.

Voici la séquence prévue :

  1. Le modèle propose un appel d’outil.
  2. Les règles déterminent si une vérification est nécessaire.
  3. Une personne chargée de la validation approuve, modifie ou rejette l’appel.
  4. L’outil s’exécute avec sa propre politique de nouvelles tentatives bornée.
  5. En cas de réussite, le résultat est renvoyé à l’agent ; si le budget est épuisé, le flux passe en reprise.

N’effectuez pas d’effets de bord dans un middleware réexécuté lors de la reprise d’une interruption. La documentation avertit en particulier que le middleware situé avant la couche de vérification humaine doit pouvoir être réexécuté sans risque jusqu’à la suspension.

Ajouter un état de reprise plutôt qu’une nouvelle tentative

Une fois le budget de nouvelles tentatives épuisé, consignez un événement opérationnel comprenant l’ID du flux de travail, le nom de l’outil, le nombre de tentatives, la clé d’idempotence et la dernière erreur connue. Choisissez ensuite l’une de ces trois voies :

  • Vérifier : interroger le système externe pour déterminer si l’opération initiale a réussi.
  • Transmettre : suspendre le flux pour qu’un opérateur disposant du contexte nécessaire décide de la suite.
  • Compenser : exécuter une opération corrective distincte, explicitement approuvée.

Ne demandez pas au modèle d’inventer une action compensatoire à partir d’un message d’erreur incomplet. Fournissez-lui des données d’état structurées et limitez les outils disponibles.

Une limite d’exécution au niveau du graphe constitue une deuxième mesure de sécurité. Configurez la limite prise en charge par la version de LangGraph installée et traitez son atteinte comme un événement de reprise, plutôt que de poursuivre silencieusement. Cela évite qu’une boucle modèle-outil ne devienne un processus de production sans limites.

Liste de vérification pour le dépannage

  • Le flux de travail repart du début : vérifiez qu’un checkpointer persistant et un thread_id inchangé sont utilisés.
  • Une action rejetée est quand même exécutée : vérifiez que la décision de reprise est bien un rejet, et non respond.
  • La personne chargée de la validation reçoit trop de demandes : ajoutez des prédicats when fondés sur les arguments afin que seules les actions à risque déclenchent une interruption.
  • Une nouvelle tentative duplique le travail : ajoutez l’idempotence et un outil de vérification d’état avant de réessayer lorsque le résultat est incertain.
  • La même vérification réapparaît : examinez l’ordre du middleware et assurez-vous que la gestion des nouvelles tentatives n’encapsule pas la limite d’approbation de manière incorrecte.
  • Un appel modifié a un comportement inattendu : validez vous-même les arguments modifiés ; le schéma de réponse documenté décrit la structure, mais ne garantit pas nécessairement la sécurité métier.

Conclusion

Un agent d’exploitation LangGraph fiable est un flux de travail borné, pas un chatbot sans contraintes. Attribuez à chaque outil un budget de nouvelles tentatives, catégorisez les échecs, persistez l’état, soumettez les appels dangereux à validation et faites de la reprise une branche explicite. L’approbation humaine devient ainsi un point de contrôle maîtrisé dans le flux de travail, plutôt qu’une solution de secours en urgence.

Sources

FAQ

LangGraph réessaie-t-il automatiquement chaque appel d’outil ayant échoué ?

Ne le présumez pas. Définissez explicitement le comportement en cas de nouvelle tentative, catégorisez les erreurs et imposez un nombre maximal de tentatives. Un middleware de nouvelle tentative pour les outils est peut-être disponible dans votre pile logicielle, mais sa configuration et son comportement doivent être vérifiés dans la documentation correspondant à la version utilisée.

Pourquoi un point de reprise est-il nécessaire pour l’approbation humaine ?

Une interruption suspend l’exécution pendant l’attente d’une décision. Un checkpointer préserve l’état du graphe afin que le même thread de flux de travail puisse reprendre après une approbation, une modification, un rejet ou une réponse directe.

Dans quels cas un appel d’outil doit-il être soumis à une vérification humaine ?

Soumettez à vérification les appels qui modifient l’état de la production, suppriment des données, envoient des communications externes ou présentent un coût ou une portée incertains. L’inspection en lecture seule peut souvent s’exécuter automatiquement lorsque son autorisation et les limites de sortie sont clairement définies.

Que faut-il faire une fois le budget de nouvelles tentatives épuisé ?

Passez à une voie de reprise : vérifiez l’opération externe, transmettez le cas à un opérateur ou exécutez une action compensatoire approuvée séparément. Évitez de répéter aveuglément une opération dont le résultat est inconnu.

Articles liés