Einen begrenzten LangGraph-Agenten zur Diagnose von API-Vorfällen entwickeln

Die Entscheidung: automatisch diagnostizieren, Abhilfe gezielt einleiten

Ein Agent für API-Vorfälle kann Zeit sparen, indem er Belege aus Protokollen, Zustandsprüfungen und Metadaten aktueller Deployments sammelt. Er sollte Dienste nicht unbemerkt neu starten, Releases zurücksetzen oder Konfigurationen ändern. Ein sichereres Design trennt die schreibgeschützte Diagnose von Abhilfemaßnahmen mit Seiteneffekten, begrenzt die Arbeit des Agenten und macht fehlende oder fehlerhafte Belege für die zuständige Person sichtbar.

Dies ist ein praktischer Entwurf, keine getestete Integration und kein produktionsreifer Dienst. Die nachfolgenden Werkzeugrümpfe dienen der Veranschaulichung: Ersetzen Sie sie durch Ihre eigenen authentifizierten Observability-Clients mit eingeschränkten Berechtigungen.

Voraussetzungen und Workflow

Sie benötigen Python, ein mit LangGraph kompatibles Chatmodell, das in Ihrer Anwendung konfiguriert ist, sowie Clientfunktionen für die Diagnose-Systeme, die Sie bereits verwenden. In diesem Beispiel wird angenommen, dass diese Clientfunktionen Daten zurückgeben oder Ausnahmen auslösen. Ein bestimmter Modellanbieter, Endpunkt oder eine konkrete Tool-Integration wird nicht vorausgesetzt.

Ein sinnvoller Vorfallslauf folgt einem begrenzten Ablauf:

1. Erfassen Sie eine kleine, vorab festgelegte Auswahl an Signalen für den betroffenen Dienst und Zeitraum.
2. Kennzeichnen Sie jedes Ergebnis als erfolgreich, fehlgeschlagen oder nicht verfügbar.
3. Lassen Sie das Modell die Belege zusammenfassen und benennen, was noch unbekannt ist.
4. Beenden Sie den Lauf nach einer begrenzten Anzahl von Graph-Schritten und holen Sie vor jeder zustandsändernden Aktion eine menschliche Prüfung ein.

Das Statusfeld ist aus operativen Gründen wichtig: Eine fehlgeschlagene Protokollabfrage darf nicht wie eine erfolgreiche Suche ohne passende Ereignisse aussehen.

Diagnosewerkzeuge mit expliziten Fehlersignalen definieren

Halten Sie den Werkzeugvertrag eng gefasst. Verlangen Sie einen Dienstnamen und einen begrenzten Zeitraum; geben Sie dem Modell keinen beliebigen Abfragezugriff, wenn eine feste Abfrage ausreicht. Geben Sie strukturierte Ergebnisse zurück, damit nachgelagerte Knoten und der Vorfallsbericht zwischen fehlenden Belegen und einem Werkzeugfehler unterscheiden können.

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)

Ergänzen Sie separate Werkzeuge für Zustandsprüfungen oder Deployment-Metadaten, die dasselbe Ergebnisformat verwenden. Fangen Sie nicht jede Ausnahme ab und geben Sie dann eine leere Zeichenfolge zurück: Bewahren Sie genügend Fehlerkontext auf, um eine fehlerhafte Integration diagnostizieren zu können, und vermeiden Sie zugleich Geheimnisse oder sensible Nutzdaten in Protokollen und im Modellkontext.

Ausführung begrenzen und unvollständige Läufe kenntlich machen

Legen Sie für einen mit LangGraphs create_agent erstellten Agenten beim Aufruf ein Rekursionslimit für den Graphen fest. Das Limit begrenzt die Graph-Schritte; es garantiert weder eine brauchbare Antwort noch ersetzt es Timeouts auf Werkzeugebene. Behandeln Sie das Erreichen des Limits in der umgebenden Anwendung und geben Sie einen eindeutigen Status wie „unvollständig“ zurück, statt den Lauf als abgeschlossene Diagnose darzustellen.

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__}

Der Grenzwert ist ein Beispiel und keine allgemeingültige Empfehlung. Wählen Sie ihn anhand der Anzahl der Werkzeuge und Modellschritte, die Sie zulassen, und ergänzen Sie Timeouts sowie Größenbegrenzungen für Anfragen auf Werkzeug- und Anwendungsebene. Protokollieren Sie die Lauf-ID, den ausgewählten Dienst und Zeitraum, die aufgerufenen Werkzeuge, deren Status und den Beendigungsgrund. Anhand dieser Signale kann die zuständige Person erkennen, ob „keine Fehler gefunden“ oder „Zeitüberschreitung beim Protokoll-Backend“ vorliegt.

Vor Abhilfemaßnahmen eine menschliche Prüfung einbauen

Wenn Sie später Werkzeuge hinzufügen, die den Produktionszustand ändern, sichern Sie diese mit LangChains Human-in-the-Loop-Middleware und einem Checkpointer ab. Die dokumentierte Middleware kann passende Werkzeugaufrufe für eine Freigabe, Bearbeitung, Ablehnung oder direkte Antwort anhalten. Der Zustand wird gespeichert, sodass die Ausführung nach einer Entscheidung fortgesetzt werden kann; für den Produktiveinsatz ist ein persistenter Checkpointer erforderlich, nicht die hier für Prototypen gezeigte In-Memory-Option. Siehe die LangChain-Dokumentation zu Human-in-the-Loop.

Eine praktikable Richtlinie erlaubt schreibgeschützte Diagnosen ohne Unterbrechung und verlangt eine Freigabe für Werkzeuge zum Neustarten, Zurücksetzen oder Ändern der Konfiguration. Lehnen Sie eine vorgeschlagene Aktion ab, wenn Sie sie verweigern; laut Dokumentation ist „respond“ dafür gedacht, als Werkzeug zu handeln, und nicht dafür, einen Aufruf mit Seiteneffekten abzulehnen. Prüfen Sie bearbeitete Argumente in Ihrer eigenen Werkzeugimplementierung: Die dokumentierte Middleware validiert Änderungen nicht anhand des angezeigten Schemas.

Fehlerfälle, die Sie berücksichtigen sollten

• Leere Ergebnisse: Melden Sie „keine passenden Ereignisse zurückgegeben“ und nicht „der Dienst ist fehlerfrei“.
• Zeitüberschreitung oder Autorisierungsfehler beim Werkzeug: Bewahren Sie die fehlgeschlagene Quelle und Fehlerkategorie auf; wiederholen Sie den Vorgang nicht unbegrenzt im Hintergrund.
• Wiederholte Werkzeugaufrufe: Begrenzen Sie die Graph-Ausführung und schränken Sie Werkzeugeingaben ein. Wenn Sie Wiederholungen hinzufügen, legen Sie eine kleine, ausdrückliche Wiederholungsrichtlinie fest und machen Sie die Anzahl der Versuche sichtbar.
• Interrupt kann nicht fortgesetzt werden: Prüfen Sie, ob ein Checkpointer konfiguriert ist und beim Fortsetzen dieselbe Thread-ID verwendet wird. Die Quelldokumentation verlangt Checkpointing für die menschliche Prüfung.
• Irreführende Zusammenfassung: Verlangen Sie, dass Aussagen im Bericht auf erfasste Signale verweisen, und führen Sie nicht verfügbare Quellen sowie offene Fragen auf.

Checkliste für Vorfallsläufe

Prüfen Sie vor der Bereitstellung, ob Diagnosewerkzeuge schreibgeschützt und auf ihren Zweck beschränkt sind, Zeiträume und Abfragevolumen begrenzt werden, Werkzeugfehler sichtbar bleiben, die Graph-Ausführung ein Limit hat und jede Aktion mit Seiteneffekten für eine menschliche Entscheidung pausiert. Testen Sie Zeitüberschreitungen, leere Ergebnisse, abgelehnte Aktionen und das Fortsetzen unterbrochener Läufe. Ein guter Agent liefert nicht bloß eine plausible Ursache, sondern zeigt, welche Belege er tatsächlich erhalten hat und wo seine Diagnose endet.

Quellen

• LangChain: Human-in-the-Loop-Middleware — Unterbrechungsentscheidungen, bedingte Werkzeugprüfung, Checkpointing und Fortsetzung pausierter Ausführungen.