Health Checks fuer Agenten

Idee in 30 Sekunden

Health checks fuer KI-Agenten zeigen, ob das System genau jetzt wirklich fuer Traffic bereit ist.

Sie helfen, Degradation vor dem Incident zu erkennen: langsame Tools, Timeouts, Queue-Probleme oder Ausfaelle im LLM-Layer.

Ohne health checks sieht man oft nur den Ausfall selbst, aber nicht die fruehen Signale davor.

Hauptproblem

Ein System kann formal "up" sein, aber praktisch bereits instabil laufen.

API antwortet, Runs starten, aber einzelne Schritte degradieren schon: timeout rate steigt, success rate faellt, queue time waechst. Ohne health checks wird das meist erst nach kaskadierendem Ausfall sichtbar.

Als Naechstes schauen wir, wie man diese Signale liest und findet, welche Komponente zuerst in Degradation geht.

In Production sieht das oft so aus:

• nach aussen wirkt alles "funktionsfaehig", aber p95 latency ist schon ausserhalb SLO;
• ein Tool liefert haeufiger Timeout, aber Ursache ist noch unklar;
• synthetic run faellt frueher als Haupttraffic;
• das Team reagiert erst nach partiellem Ausfall.

Darum sollte der Health-Layer separat ueberwacht werden und nicht nur ueber allgemeine Run-Metriken.

Wie es funktioniert

Health checks werden meist auf zwei Ebenen aufgebaut:

• component checks (tool_available, llm_reachable, queue_ok, db_ok);
• end-to-end checks (synthetic_run_ok, critical_workflow_ok).

Diese Signale beantworten: "Ist das System genau jetzt gesund?" Logs und Tracing werden gebraucht, um zu erklaeren, warum ein konkreter Check fehlgeschlagen ist.

Up != healthy. Ein System kann erreichbar sein, aber bereits Faehigkeit verlieren, Aufgaben auszufuehren.

Health checks sind das frueheste Systemsignal fuer Probleme. Sie erscheinen, bevor Degradation in latency oder Fehlern deutlich wird.

Ein Fall von synthetic_run_success_rate geht oft dem Anstieg von timeout_rate und der Degradation von p95 latency voraus.

Typische Production-Metriken fuer Health Checks

health_score wird meist auf Dashboard-/Health-Service-Ebene als Aggregat mehrerer Checks berechnet, nicht als eine "magische" Einzelmetrik.

Damit health-Metriken nuetzlich bleiben, werden sie meist nach release, region, workflow und Komponenten-Typ segmentiert.

Wichtig: keine hoch-kardinalen Felder (run_id, request_id, user_id) in Labels aufnehmen, sonst wird Metrik-Storage schnell ueberlastet.

Wie man den Health-Layer liest

Was geprueft wird -> was degradiert -> welche Komponente den workflow bricht. Diese drei Ebenen sollte man immer zusammen betrachten.

Wichtig sind Trends ueber Zeit und Unterschiede zwischen Releases, nicht ein einmaliger Ausfall eines einzelnen Checks.

Jetzt zu Signal-Kombinationen:

• health_check_pass_rate down + timeout_rate up -> System geht in instabilen Modus;
• synthetic_run_success_rate down + degraded_component_count up -> Problem beeinflusst bereits kritischen workflow;
• queue_time_p95 up + run_count up -> Capacity fehlt, Skalierung noetig;
• health_score down + error_rate up -> hohes Incident-Risiko in naechster Zeit;
• tool_check_latency_p95 up + synthetic_run_success_rate down -> Bottleneck im externen Tool-Layer.

Wann einsetzen

Ein kompletter Satz health checks ist nicht immer noetig.

Fuer fruehe Prototypen kann ein einfacher API-Verfuegbarkeitscheck reichen.

Detaillierte health checks werden aber kritisch, wenn:

• das System bereits in Production ist;
• Stabilitaets-SLO/SLA gelten;
• der Agent von mehreren externen Tools oder Queues abhaengt;
• fruehe Alerts benoetigt werden, bevor ein Massenausfall startet.

Implementierungsbeispiel

Unten ist ein vereinfachter health-check-Zyklus im Prometheus-Stil. Das Beispiel zeigt den Basisansatz: Komponentenchecks, synthetic run und aggregierter health score.

import time
from dataclasses import dataclass
from prometheus_client import Counter, Gauge, Histogram

# perf_counter() wird fuer praezise monotone Latency-Messungen genutzt
HEALTH_CHECK_TOTAL = Counter(
    "agent_health_check_total",
    "Total health checks by check name and status",
    ["check", "status", "release"],
)

HEALTH_CHECK_LATENCY_MS = Histogram(
    "agent_health_check_latency_ms",
    "Health check latency in milliseconds",
    ["check", "release"],
    buckets=(10, 20, 50, 100, 250, 500, 1000, 2000),
)

SYNTHETIC_RUN_TOTAL = Counter(
    "agent_synthetic_run_total",
    "Total synthetic runs by status",
    ["status", "release"],
)

DEGRADED_COMPONENT_TOTAL = Counter(
    "agent_degraded_component_total",
    "Total degraded component detections",
    ["component", "reason", "release"],
)

HEALTH_SCORE = Gauge(
    "agent_health_score",
    "Aggregated health score in range 0..1",
    ["release"],
)


@dataclass
class CheckResult:
    ok: bool
    reason: str = "ok"


def run_health_checks(checks, run_synthetic, release="2026-03-22"):
    total = len(checks)
    failed = 0

    for check_name, check_fn in checks.items():
        started_at = time.perf_counter()
        status = "error"  # default for any failure path
        try:
            result = check_fn()  # -> CheckResult
            status = "ok" if result.ok else "fail"
            if not result.ok:
                failed += 1
                DEGRADED_COMPONENT_TOTAL.labels(
                    component=check_name,
                    reason=result.reason,
                    release=release,
                ).inc()
        except Exception as error:
            failed += 1
            DEGRADED_COMPONENT_TOTAL.labels(
                component=check_name,
                reason=type(error).__name__,
                release=release,
            ).inc()
        finally:
            HEALTH_CHECK_TOTAL.labels(check=check_name, status=status, release=release).inc()
            HEALTH_CHECK_LATENCY_MS.labels(check=check_name, release=release).observe(
                (time.perf_counter() - started_at) * 1000
            )

    try:
        synthetic_ok = run_synthetic()
        SYNTHETIC_RUN_TOTAL.labels(
            status="ok" if synthetic_ok else "fail",
            release=release,
        ).inc()
        if not synthetic_ok:
            failed += 1
    except Exception:
        SYNTHETIC_RUN_TOTAL.labels(status="error", release=release).inc()
        failed += 1

    # 1.0 = alle Checks erfolgreich, 0.0 = alles fehlgeschlagen
    # +1 fuer synthetic run
    denominator = total + 1
    health_score = max(0.0, 1.0 - (failed / max(1, denominator)))
    HEALTH_SCORE.labels(release=release).set(health_score)
    return health_score

So koennen health-Metriken in einem realen Dashboard aussehen:

Investigation

Wenn ein health-Alert ausloest:

1. Check oder workflow mit Degradation finden;
2. problematische Runs im Tracing ansehen;
3. timeout, stop_reason und tool failures in Logs pruefen;
4. root cause finden (Tool, LLM, Queue, Routing, Release-Regression).

Typische Fehler

Auch wenn health checks vorhanden sind, bringen sie oft wenig wegen typischer Fehler unten.

Es gibt nur Ping-/Verfuegbarkeitschecks

API-Verfuegbarkeit garantiert nicht, dass der agentische workflow real funktioniert. Ohne synthetic run verpasst man versteckte Degradation leicht.

Keine Checks fuer externe Abhaengigkeiten

Wenn Tools, Queues oder DB nicht in health checks enthalten sind, kann das System bis zum ersten Incident "gesund" wirken. In so einer Lage ist schnelle Lokalisierung von Tool-Ausfall schwierig.

Keine Aufteilung nach workflow und release

Ohne das ist schwer erkennbar, welcher Release oder welches Szenario den Systemzustand verschlechtert hat.

Keine Alerts auf health-score-Degradation

Ohne Alerts werden health checks zu passiver Telemetrie. Dadurch verpasst man fruehe Signale von Multi-Agent-Chaos.

Hoch-kardinale Labels

run_id, request_id oder session_id in Labels ueberlasten Metrik-Backends schnell. Diese Daten besser in Logs und Tracing halten.

Selbstcheck

Unten ist eine kurze Checkliste fuer Basis-health-checks vor Release.

FAQ

Q: Worin unterscheiden sich health checks von normalen Metriken?
A: Metriken zeigen Trends, health checks geben eine schnelle "ist das System jetzt bereit oder nicht"-Antwort fuer konkrete Szenarien.

Q: Welches Minimum an health checks braucht man zum Start?
A: Starte mit llm_reachable, tool_available, queue_ok und einem synthetic run fuer kritischen workflow.

Q: Warum ist synthetic run so wichtig?
A: Er prueft den kompletten Ausfuehrungspfad, nicht nur einzelne Komponenten. Das bildet den realen Production-Zustand am besten ab.

Q: Wenn health score faellt, API aber noch antwortet - ist das schon Incident?
A: Das ist fruehe Degradation. Investigation sollte sofort starten, bevor das Problem zum Massenausfall wird.

Verwandte Seiten

Weiter zum Thema:

• Observability fuer KI-Agenten — Basismodell aus Tracing, Logs und Metriken.
• Agent-Metriken — allgemeine Produktionssignale fuer das System.
• Alerting in KI-Agenten — wie man fruehe Benachrichtigungen aufbaut.
• Agent Tracing — wie man den Schritt lokalisiert, der health check bricht.
• Latency Monitoring fuer Agenten — wie man Geschwindigkeits-Degradation vor Incident erkennt.