Créer un agent LangGraph d’appel d’outils borné avec revue humaine
Un modèle pratique pour évaluer un agent LangGraph d’appel d’outils avec des limites d’étapes explicites, une approbation humaine pour les actions à risque et des cas de test reproductibles.
Résumé · TL;DR
Utilisez une limite d’étapes du graphe pour borner l’exécution, HumanInTheLoopMiddleware pour mettre en pause les appels d’outils à risque et un petit ensemble fixe de tests pour vérifier les comportements d’approbation, de rejet et de dépassement de limite. Considérez les exemples comme un point de départ : le comportement du modèle et des outils doit être testé dans votre propre environnement.
Points clés
- Une limite de récursion du graphe fournit à un agent une frontière d’exécution claire ; elle ne garantit pas que l’agent terminera sa tâche.
- La revue humaine peut mettre en pause l’exécution d’un outil et la reprendre ultérieurement lorsque le graphe dispose d’un checkpointer et d’un identifiant de thread.
- Pour conserver des évaluations reproductibles, fixez les entrées de test, les résultats attendus, les fixtures d’outils et la limite d’exécution.
- Testez explicitement les actions rejetées et l’épuisement de la limite ; aucun de ces cas ne correspond à une récupération réussie.
Sur cette page (6)
Un agent d’appel d’outils a besoin de plus qu’un bon prompt : il lui faut une limite d’arrêt, un plan pour les actions à risque et des tests qui rendent son comportement reproductible. Dans LangGraph, vous pouvez combiner une limite de récursion du graphe avec une revue human-in-the-loop (HITL) pour certains outils. Vous pouvez ensuite évaluer le workflow avec des cas fixes plutôt que de vous appuyer sur quelques exécutions réussies.
L’exemple ci-dessous est fourni à titre illustratif et ne constitue pas une configuration testée. Il suppose un environnement Python avec des packages LangChain et LangGraph compatibles, un modèle de chat prenant en charge les appels d’outils et un outil que vous avez implémenté. Vérifiez les versions et les paramètres du fournisseur de modèle dans votre propre environnement.
Choisir la limite avant d’ajouter des outils
Une limite de récursion borne les étapes d’exécution du graphe. Il s’agit d’une limite de sécurité, et non d’une promesse que l’agent terminera sa tâche ni d’une limite précise du nombre d’appels d’outils : la structure du graphe influe sur le décompte des étapes. Si l’exécution atteint la limite, attendez-vous à une erreur de récursion du graphe et traitez-la comme une exécution incomplète. Ne la considérez pas comme une réponse réussie.
Commencez avec une limite réduite pendant l’évaluation, puis augmentez-la uniquement lorsqu’un cas de test montre que le workflow a besoin de davantage d’étapes. Gardez également les opérations des outils dans un périmètre étroit. Une limite au niveau du graphe ne peut pas annuler un effet secondaire qu’un outil a déjà produit.
Configurer un appel d’outil pouvant être mis en pause pour revue
Cet exemple utilise create_agent avec le middleware HITL. L’outil write_file est interrompu pour approbation ou rejet ; read_data ne l’est pas. Les implémentations des outils et le nom du modèle sont des valeurs fictives. Vérifiez que le modèle et le point de terminaison choisis prennent en charge les paramètres et le comportement d’appel d’outils utilisés par votre agent.
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
# Replace these placeholders with your own tool implementations.
tools = [write_file, read_data]
agent = create_agent(
model="your-tool-capable-chat-model",
tools=tools,
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"write_file": {"allowed_decisions": ["approve", "reject"]},
"read_data": False,
}
)
],
checkpointer=InMemorySaver(),
)
config = {
"configurable": {"thread_id": "evaluation-case-001"},
"recursion_limit": 8,
}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Save the approved summary."}]},
config=config,
version="v2",
)
InMemorySaver convient à un prototype ou à un test exécuté dans un seul processus ; il n’est pas persistant entre les redémarrages de processus. Pour un workflow déployé, utilisez un checkpointer persistant. Le guide HITL de LangChain explique qu’un checkpointer et un identifiant de thread sont nécessaires pour mettre une exécution en pause et la reprendre. Source : Human-in-the-loop.
Lorsque l’exécution renvoie une interruption, présentez l’action demandée et ses arguments à un réviseur. Reprenez le même thread avec une décision. L’ordre des décisions doit correspondre à l’ordre des actions dans l’interruption. Rejetez une action que vous refusez ; respond sert à renvoyer une réponse humaine comme résultat d’outil, et non à refuser un effet secondaire.
from langgraph.types import Command
# Use the same config, including the same thread ID, to resume.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Outside the approved scope."}]}),
config=config,
version="v2",
)
Rendre l’évaluation reproductible
Conservez un ensemble de tests concis dans le contrôle de version. Chaque cas doit préciser la demande de l’utilisateur, le comportement attendu de l’outil, la nécessité ou non d’une revue et le statut final attendu. Utilisez des fixtures inoffensives ou des outils simulés pour les tests ; ne laissez pas les cas d’évaluation écrire dans de vrais fichiers ni modifier des données de production.
| Cas | Configuration | Résultat attendu |
|---|---|---|
| Lecture sûre | Demander des informations via read_data | Aucune interruption HITL ; le résultat de l’outil est renvoyé |
| Écriture soumise à revue | Demander une écriture autorisée | Une interruption apparaît avant l’exécution de l’écriture ; l’approbation permet l’exécution |
| Écriture rejetée | Demander une écriture, puis la rejeter | L’outil d’écriture n’est pas exécuté ; le retour du rejet est transmis à l’agent |
| Limite d’étapes | Utiliser une fixture qui empêche le workflow de se terminer | L’exécution s’arrête à la limite configurée et est enregistrée comme incomplète |
Pour chaque exécution, enregistrez l’identifiant du cas, la limite configurée, les appels d’outils, les décisions liées aux interruptions, le statut d’achèvement et toute erreur. Comparez ces champs aux résultats attendus. Évitez de juger uniquement la réponse finale en langage naturel : un agent peut produire une réponse plausible après avoir effectué la mauvaise action.
Gestion des échecs : mettre en pause, rejeter ou arrêter
HITL est une pause contrôlée, et non un mécanisme général de nouvelle tentative. Selon la politique configurée, un réviseur peut approuver, modifier, rejeter ou répondre. Le rejet ignore l’appel d’outil demandé et renvoie un retour de rejet à l’agent. La suite — terminer, demander une autre action ou échouer — dépend du comportement ultérieur de l’agent ; testez donc ce parcours.
Si le graphe atteint sa limite de récursion, enregistrez l’exécution comme un échec dû à la limite et examinez son état ainsi que son historique d’outils. Ne rejouez pas automatiquement une exécution qui a peut-être déjà produit des effets secondaires. Rendez les outils idempotents lorsque cela est possible, ou exigez une vérification distincte avant de répéter une opération. La documentation fournie décrit la mise en pause et la reprise avec points de contrôle ; elle n’établit pas de récupération automatique après des échecs arbitraires d’outils ou de modèles.
Liste de vérification pour le dépannage
- Aucune interruption n’apparaît : vérifiez que le nom de l’outil correspond au mapping
interrupt_onet que sa politique active la revue. - La reprise ne retrouve pas l’exécution en pause : confirmez que le même checkpointer et le même identifiant de thread sont utilisés.
- L’exécution s’arrête trop tôt : examinez la limite de récursion configurée et le chemin du graphe ; augmentez la limite uniquement lorsqu’un cas de test le justifie.
- Une action rejetée semble avoir été effectuée : vérifiez que l’outil n’a pas été appelé avant la revue et que le réviseur a utilisé
reject, et nonrespond. - Les tests varient d’une exécution à l’autre : fixez les fixtures d’outils et les entrées de test, et contrôlez ou simulez les réponses du modèle lorsque votre configuration le permet. Une entrée fixe ne suffit pas à rendre la sortie du modèle déterministe.
La règle pratique
Utilisez la limite de récursion pour borner le travail du graphe, HITL pour contrôler les appels d’outils ayant des conséquences et un petit ensemble explicite de tests pour vérifier à la fois le parcours nominal et les parcours d’échec. Traitez les exécutions interrompues, rejetées et arrêtées par épuisement de la limite comme des résultats distincts. Cette distinction rend un agent plus facile à évaluer — et plus sûr à faire évoluer.
FAQ
La limite de récursion de LangGraph plafonne-t-elle le nombre d’appels d’outils ?
Pas exactement. Elle limite les étapes d’exécution du graphe, et le nombre d’appels d’outils possibles dépend de la structure du graphe. Traitez l’épuisement de la limite comme une exécution incomplète et testez cette limite.
Que faut-il pour reprendre un appel d’outil soumis à une revue humaine ?
Configurez un checkpointer, fournissez un identifiant de thread et reprenez l’exécution avec le même thread et le même contexte de persistance. Le réviseur fournit une décision pour chaque action interrompue.
HITL réessaie-t-il automatiquement un appel d’outil ayant échoué ?
Non. Le workflow HITL documenté met l’exécution en pause pour obtenir une décision humaine, puis exécute ou ignore l’action examinée. Il n’établit pas de nouvelles tentatives automatiques pour des échecs arbitraires d’outils ou de modèles.
Comment tester un appel d’outil rejeté ?
Utilisez un outil inoffensif ou simulé, déclenchez l’interruption, rejetez l’action, puis vérifiez que l’outil n’a pas été exécuté et que l’exécution enregistre le retour du rejet.
Articles liés
Guides
Créer un agent LangGraph respectueux de la vie privée, avec approbation des outils et reprise
Un modèle pratique pour utiliser la revue humaine, les points de contrôle, les exécutions limitées et des outils protégés contre l’exposition des identifiants dans un agent qui traite des données sensibles.
Guides
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.
Guides
Créer un agent LangGraph à exécution limitée pour diagnostiquer les incidents API
Créez un agent LangGraph de diagnostic des incidents qui utilise des outils de diagnostic en lecture seule, limite l’exécution, signale les échecs et suspend le processus avant toute action risquée.
Guides
Construire un agent de support client LangGraph avec appel d’outils, approbation humaine et limites d’exécution
Un modèle pratique LangGraph pour le triage du support client : orienter les demandes, appeler des outils de recherche, mettre les remboursements en pause pour approbation humaine et limiter l’exécution du graphe.