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.
Résumé · TL;DR
Utilisez le middleware de LangGraph avec intervention humaine pour suspendre les appels sensibles aux outils, les examiner ou les rejeter, puis reprendre l’exécution à partir d’un point de contrôle. Associez ce processus à des limites strictes pour les outils, à l’isolation des identifiants et à une limite d’exécution.
Points clés
- Conservez les identifiants dans les implémentations des outils ; ne transmettez au modèle que les arguments minimums nécessaires.
- Exigez une revue humaine pour les écritures ou requêtes sensibles, tout en autorisant les lectures sûres.
- Utilisez un mécanisme de sauvegarde de points de contrôle persistant et un identifiant de fil stable pour reprendre le travail interrompu.
- Limitez l’exécution du graphe et rendez les outils idempotents ou sûrs à relancer de manière autonome.
- Considérez les états sauvegardés aux points de contrôle et les charges utiles d’interruption comme des données sensibles.
Sur cette page (5)
Un agent respectueux de la vie privée ne doit pas s’en remettre au modèle pour déterminer si un appel d’outil est sûr. Gardez les identifiants en dehors de la conversation, limitez les capacités de chaque outil et suspendez les actions sensibles pour les soumettre à une revue humaine. Le middleware de LangGraph avec intervention humaine fournit le mécanisme de suspension et de reprise ; votre application doit toujours définir le traitement des données, les autorisations et les limites d’exécution.
Ce guide présente un modèle simple pour un agent capable de lire des dossiers clients et de demander une modification de base de données. Le code est donné à titre d’exemple et n’a pas été testé ici. Avant le déploiement, vérifiez les versions des packages et les signatures des outils dans votre environnement.
1. Séparer le contexte du modèle des identifiants
Ne placez pas de mots de passe, de clés API, de cookies de session ni d’identifiants de base de données sans restriction dans les invites ou les arguments des outils. À la place, proposez aux outils des opérations limitées et faites-leur récupérer les identifiants auprès du mécanisme de gestion des secrets de votre application au moment de l’exécution. Le modèle ne doit voir que les données nécessaires au choix d’une action.
Par exemple, préférez un outil tel que find_customer_record(customer_id) à un outil généraliste qui accepte des requêtes SQL arbitraires et des paramètres de connexion. Vérifiez les autorisations dans l’outil lui-même : la demande d’un utilisateur ne prouve pas qu’il est autorisé à accéder au dossier demandé.
La revue humaine constitue un contrôle supplémentaire, pas un système d’autorisation. Les personnes chargées de la revue doivent disposer de suffisamment d’informations pour prendre une décision, sans que des données personnelles ou des secrets inutiles soient affichés dans les interfaces de revue et les journaux.
2. Configurer la revue des actions sensibles
La documentation fournie de LangChain sur l’intervention humaine décrit un middleware qui vérifie les appels d’outils selon une politique. Les appels correspondants peuvent interrompre l’exécution ; un mécanisme de sauvegarde de points de contrôle enregistre l’état du graphe afin que l’exécution puisse reprendre ultérieurement. Les décisions documentées comprennent l’approbation, la modification des arguments, le rejet avec commentaires et la réponse à un outil qui pose une question à l’utilisateur.
Voici une configuration illustrative. Remplacez les outils de substitution par des implémentations qui appliquent les règles d’accès et la validation des entrées de votre application.
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
agent = create_agent(
model="YOUR_CONFIGURED_MODEL",
tools=[read_customer_record, update_customer_record],
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"read_customer_record": False,
"update_customer_record": {
"allowed_decisions": ["approve", "edit", "reject"]
},
},
description_prefix="Review requested customer-data change",
),
],
# For production, use a persistent checkpointer appropriate to your stack.
checkpointer=InMemorySaver(),
)
InMemorySaver convient au prototypage, mais pas à une reprise durable après le redémarrage d’un processus. La documentation exige un mécanisme de sauvegarde de points de contrôle pour les interruptions avec revue humaine et cite des options persistantes telles que AsyncPostgresSaver et MongoDBSaver. Choisissez un stockage doté de contrôles d’accès, de règles de conservation et d’un chiffrement adaptés aux données sauvegardées. Un point de contrôle peut contenir des messages et des arguments d’outils ; il peut donc renfermer des données sensibles sur les utilisateurs, même si les identifiants en sont exclus.
Si seuls certains appels doivent être soumis à une revue, la documentation prend également en charge un prédicat when pour les interruptions conditionnelles (nécessite langchain>=1.3.3). Vous pourriez, par exemple, suspendre une écriture en dehors d’un espace de travail approuvé ou une requête qui n’est pas en lecture seule. Ne considérez pas la vérification d’un préfixe de chaîne comme une politique complète de sécurité SQL ; appliquez également des opérations sûres au niveau de la base de données et des outils.
3. Suspendre, examiner et reprendre la même exécution
Utilisez un identifiant de fil stable afin que l’application puisse associer la revue en attente à la bonne conversation. Protégez cet identifiant et l’interface de revue : posséder un identifiant de fil ne doit pas donner le droit d’approuver une action.
from langgraph.types import Command
config = {"configurable": {"thread_id": "conversation-123"}}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Update this customer's address"}]},
config=config,
version="v2",
)
if result.interrupts:
# Present the requested action to an authenticated reviewer.
# Resume only after recording that reviewer's decision.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Verify the request first."}]}),
config=config,
version="v2",
)
Lorsque plusieurs appels d’outils sont suspendus, l’ordre des décisions doit correspondre à celui des actions dans la demande d’interruption. Utilisez reject pour refuser une action ayant des effets de bord. La documentation précise que respond fournit un résultat synthétique d’outil ; cette option sert à répondre à un outil de type « demander à l’utilisateur », et non à refuser une écriture.
4. Limiter l’exécution et prévoir la reprise
Une suspension pour revue n’empêche pas, à elle seule, le modèle de demander des outils à répétition. Définissez une limite de récursion du graphe pour les appels et traitez l’erreur qui en résulte comme un arrêt contrôlé. La limite exacte dépend de la charge de travail ; choisissez-la en fonction de la séquence maximale utile d’étapes du modèle et des outils, et testez le comportement à la limite.
config = {
"configurable": {"thread_id": "conversation-123"},
"recursion_limit": 12,
}
Ce paramètre donné à titre d’exemple limite les étapes du graphe ; il ne garantit pas la protection contre les outils lents, les sorties volumineuses ou la répétition d’effets de bord externes. Ajoutez des délais d’expiration aux appels réseau et de base de données, plafonnez les sorties des outils et validez les entrées. Pour les opérations pouvant être relancées, utilisez des mécanismes d’idempotence ou vérifiez l’état actuel avant d’appliquer une modification. Si une exécution échoue après la réussite d’un outil, mais avant que l’agent n’enregistre le résultat, une relance aveugle risque d’effectuer l’opération deux fois.
Lors de la reprise, ne reprenez le même fil sauvegardé au point de contrôle qu’après avoir vérifié que l’action en attente et son autorisation sont toujours valides. Si les autorisations de l’utilisateur ou le dossier sous-jacent ont changé pendant la revue, rejetez l’action ou validez-la à nouveau au lieu d’exécuter des arguments obsolètes.
5. Liste de contrôle relative à la confidentialité et aux défaillances
Avant la mise en production, vérifiez les points suivants :
- Les implémentations des outils récupèrent les identifiants de manière privée et ne les renvoient jamais dans les résultats des outils ni dans les erreurs.
- Chaque outil vérifie les autorisations de l’utilisateur et n’accepte que les arguments les plus restreints qui restent utiles.
- Les points de contrôle, les charges utiles d’interruption, les journaux et les interfaces de revue sont soumis à des contrôles d’accès et de conservation définis.
- La personne chargée de la revue peut identifier la cible et les conséquences sans voir de données personnelles sans rapport avec l’action.
- Les rejets n’exécutent pas l’outil et les nouvelles tentatives ne peuvent pas dupliquer les effets de bord.
- Les exécutions sont soumises à des limites d’étapes, à des délais d’expiration des outils et à des limites de sortie ; une procédure claire permet de signaler les travaux interrompus ou échoués.
Le choix de conception essentiel consiste à traiter l’approbation humaine comme un point de contrôle dans un processus sécurisé, et non comme un substitut au principe du moindre privilège, à la minimisation des données ou à la validation au niveau des outils.
FAQ
Le middleware de LangGraph avec intervention humaine stocke-t-il l’état de l’agent suspendu ?
Il utilise la persistance de LangGraph pour sauvegarder l’état pendant une interruption. Un mécanisme de sauvegarde de points de contrôle est obligatoire ; en production, choisissez un stockage persistant et appliquez des contrôles d’accès et de conservation adaptés.
Dois-je utiliser la décision respond pour rejeter un appel sensible à un outil ?
Non. Selon le comportement documenté, respond fournit un résultat d’outil synthétique positif et sert dans des cas tels que la réponse à un outil qui demande des informations à l’utilisateur. Utilisez reject pour refuser une action ayant des effets de bord.
Comment protéger les identifiants dans un agent LangGraph ?
Conservez les identifiants dans l’environnement d’exécution de l’outil ou dans la couche de gestion des secrets. Ne les placez pas dans les invites, les arguments d’outils visibles par le modèle, les résultats des outils, les messages d’interruption ni les journaux.
L’approbation humaine empêche-t-elle un agent de s’exécuter indéfiniment ?
Non. Le middleware d’approbation gère la revue des appels d’outils configurés. Ajoutez séparément une limite d’exécution, des délais d’expiration pour les outils, des limites de sortie et un comportement sûr en cas de nouvelle tentative.
Articles liés
Guides
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.
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.
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.