Créer un agent LangGraph à exécution limitée pour diagnostiquer les incidents API

Le choix à faire : diagnostiquer automatiquement, remédier avec discernement

Un agent d’incident API peut faire gagner du temps en recueillant des éléments issus des journaux, des vérifications d’état et des métadonnées des déploiements récents. Il ne doit pas redémarrer des services, annuler des mises en production ni modifier la configuration sans le signaler. Une conception plus sûre sépare le diagnostic en lecture seule des mesures de remédiation qui ont des effets de bord, limite le travail de l’agent et rend visibles à l’opérateur les éléments manquants ou les échecs de collecte.

Il s’agit d’une conception pratique, et non d’une intégration testée ou d’un service prêt pour la production. Les corps des outils ci-dessous sont donnés à titre d’illustration : remplacez-les par vos propres clients d’observabilité authentifiés et dotés d’autorisations limitées.

Prérequis et workflow

Vous avez besoin de Python, d’un modèle de chat compatible avec LangGraph et configuré dans votre application, ainsi que de fonctions clientes pour les systèmes de diagnostic que vous utilisez déjà. Cet exemple suppose que ces fonctions clientes renvoient des données ou lèvent des exceptions. Il ne présuppose ni fournisseur de modèle, ni endpoint, ni intégration d’outil en particulier.

Une exécution d’incident utile suit une boucle encadrée :

1. Recueillir un petit ensemble prédéfini de signaux pour le service concerné et la période visée.
2. Indiquer pour chaque résultat s’il a réussi, échoué ou n’était pas disponible.
3. Demander au modèle de résumer les éléments recueillis et de préciser ce qui reste inconnu.
4. S’arrêter après un nombre limité d’étapes du graphe et demander une vérification humaine avant toute action qui modifie l’état.

Le champ d’état a une utilité opérationnelle : l’échec d’une requête dans les journaux ne doit pas être confondu avec une recherche de journaux réussie n’ayant trouvé aucun événement correspondant.

Définir des outils de diagnostic avec des signaux d’échec explicites

Gardez le contrat de l’outil précis. Exigez le nom d’un service et une période délimitée ; évitez de donner au modèle un accès arbitraire aux requêtes lorsqu’une requête fixe suffit. Renvoyez des résultats structurés afin que les nœuds en aval et le rapport d’incident puissent distinguer l’absence de données de l’échec d’un outil.

from typing import Literal, TypedDict
from langchain.tools import tool

class Signal(TypedDict):
    status: Literal["ok", "error", "unavailable"]
    source: str
    data: str
    error: str | None


def query_logs(service: str, minutes: int) -> Signal:
    if not 1 <= minutes <= 60:
        return {
            "status": "error", "source": "logs", "data": "",
            "error": "minutes must be between 1 and 60",
        }
    try:
        # Replace with a read-only, scoped observability client call.
        rows = logs_client.search(service=service, minutes=minutes)
        return {
            "status": "ok", "source": "logs",
            "data": str(rows), "error": None,
        }
    except TimeoutError as exc:
        return {
            "status": "unavailable", "source": "logs", "data": "",
            "error": f"timeout: {exc}",
        }

@tool
def inspect_api(service: str, minutes: int = 15) -> dict:
    """Collect scoped, read-only API incident signals."""
    return query_logs(service, minutes)

Ajoutez des outils distincts pour les vérifications d’état ou les métadonnées de déploiement, en conservant la même structure de résultat. N’interceptez pas toutes les exceptions pour renvoyer une chaîne vide : gardez suffisamment de contexte d’erreur pour diagnostiquer une intégration défaillante, tout en évitant d’exposer des secrets ou des données sensibles dans les journaux et le contexte du modèle.

Limiter l’exécution et signaler les exécutions incomplètes

Pour un agent créé avec create_agent de LangGraph, définissez une limite de récursion du graphe lors de l’appel. Cette limite encadre le nombre d’étapes du graphe ; elle ne garantit pas une réponse utile et ne remplace pas les délais d’expiration au niveau des outils. Gérez l’atteinte de la limite dans l’application qui entoure l’agent et renvoyez clairement l’état « incomplet » au lieu de présenter l’exécution comme un diagnostic terminé.

from langchain.agents import create_agent

agent = create_agent(
    model=your_configured_chat_model,
    tools=[inspect_api],
    system_prompt=(
        "Diagnose API incidents using available evidence. "
        "Report each source as ok, error, or unavailable. "
        "Do not claim a cause without supporting evidence. "
        "Do not perform remediation."
    ),
)

try:
    result = agent.invoke(
        {"messages": [{"role": "user", "content":
            "Investigate elevated errors for payments-api over the last 15 minutes."}]},
        config={"recursion_limit": 12},
    )
except Exception as exc:
    # Map known graph-limit and provider/tool failures to your app's
    # incident-run status; do not expose credentials or raw secrets.
    result = {"status": "incomplete", "reason": type(exc).__name__}

La valeur limite n’est qu’un exemple, pas une recommandation universelle. Choisissez-la en fonction du nombre d’outils et de tours de modèle que vous autorisez, et ajoutez des délais d’expiration ainsi que des limites de taille des requêtes au niveau des outils et de l’application. Consignez l’identifiant d’exécution, le service et la période sélectionnés, les outils tentés, leur état et la raison de l’arrêt. Ces signaux permettent à l’opérateur de distinguer « aucune erreur détectée » de « délai d’expiration du backend des journaux ».

Ajouter une vérification humaine avant toute remédiation

Si vous ajoutez par la suite des outils qui modifient l’état de la production, soumettez-les au middleware human-in-the-loop de LangChain et configurez un checkpointer. Le middleware documenté peut suspendre les appels d’outils concernés afin de permettre une approbation, une modification, un rejet ou une réponse directe. L’état est enregistré pour que l’exécution puisse reprendre après la décision ; en production, il faut un checkpointer persistant plutôt que l’option en mémoire montrée pour le prototypage. Consultez la documentation LangChain sur human-in-the-loop.

Une règle pratique consiste à autoriser les diagnostics en lecture seule sans interruption et à exiger une approbation pour les outils de redémarrage, d’annulation de mise en production ou de modification de configuration. Rejetez une action proposée en la refusant : la documentation précise que « respond » sert à agir en tant qu’outil, et non à refuser un appel ayant des effets de bord. Validez les arguments modifiés dans votre propre implémentation d’outil : le middleware documenté ne vérifie pas que les modifications respectent le schéma affiché.

Cas d’échec à anticiper

• Résultats vides : indiquez « aucun événement correspondant renvoyé », et non « le service est sain ».
• Délai d’expiration de l’outil ou échec d’autorisation : conservez la source en échec et la catégorie d’erreur ; ne relancez pas les tentatives indéfiniment sans le signaler.
• Appels répétés à un outil : limitez l’exécution du graphe et contraignez les entrées des outils. Si vous ajoutez des tentatives, définissez une politique explicite avec un nombre réduit d’essais et indiquez le nombre de tentatives effectuées.
• Impossible de reprendre après une interruption : vérifiez qu’un checkpointer est configuré et que le même identifiant de thread est utilisé lors de la reprise. La documentation source exige un mécanisme de checkpointing pour la vérification humaine.
• Résumé final trompeur : exigez que le rapport associe ses affirmations aux signaux recueillis et répertorie les sources indisponibles ainsi que les questions non résolues.

Liste de contrôle pour l’exécution d’un incident

Avant le déploiement, vérifiez que les outils de diagnostic sont en lecture seule et ont un périmètre limité, que les périodes et le volume des requêtes sont encadrés, que les erreurs des outils restent observables, que l’exécution du graphe est limitée et que chaque action ayant des effets de bord est suspendue dans l’attente d’une décision humaine. Testez les scénarios de délai d’expiration, de résultat vide, d’action rejetée et de reprise après interruption. Un bon agent ne se contente pas de proposer une cause racine plausible : il montre quels éléments il a réellement obtenus et où s’arrête son diagnostic.

Sources

• LangChain : middleware human-in-the-loop — décisions d’interruption, vérification conditionnelle des outils, checkpointing et reprise d’une exécution suspendue.