Health checks des agents

Idee en 30 secondes

Les health checks pour agents IA montrent si le systeme est reellement pret pour le trafic maintenant.

Ils aident a detecter la degradation avant incident : tools lentes, timeouts, problemes de queue ou pannes dans la couche LLM.

Sans health checks, on voit souvent seulement la panne, pas les signaux precoces qui la precedent.

Probleme principal

Le systeme peut etre formellement "up", mais en pratique deja instable.

L'API repond, les runs demarrent, mais certaines etapes degradent deja : timeout rate augmente, success rate baisse, queue time monte. Sans health checks, cela devient visible seulement apres echec en cascade.

Ensuite, voyons comment lire ces signaux et trouver quel composant entre en degradation en premier.

En production, cela ressemble souvent a :

• de l'exterieur tout semble "fonctionner", mais p95 latency sort deja du SLO ;
• un tool renvoie timeout plus souvent, mais la cause reste floue ;
• synthetic run commence a echouer avant le trafic principal ;
• l'equipe reagit seulement apres panne partielle.

C'est pourquoi la health-layer doit etre surveillee separement, et pas seulement via les metriques globales de run.

Comment ca fonctionne

Les health checks sont generalement construits sur deux niveaux :

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

Ces signaux repondent a "le systeme est-il sain maintenant". Logs et tracing servent a expliquer pourquoi un check concret a echoue.

Up != healthy. Le systeme peut etre accessible, mais deja perdre sa capacite a executer les taches.

Les health checks sont le signal le plus precoce de probleme systeme. Ils apparaissent avant que la degradation devienne visible dans latency ou erreurs.

Une baisse de synthetic_run_success_rate precede souvent la hausse de timeout_rate et la degradation de p95 latency.

Metriques production typiques pour health checks

health_score est generalement calcule au niveau dashboard/health-service comme agregat de plusieurs checks, pas comme metrique "magique" unique.

Pour que les metriques de health soient utiles, on segmente souvent par release, region, workflow et type de composant.

Important : ne pas ajouter de champs a forte cardinalite (run_id, request_id, user_id) dans les labels, sinon le stockage metriques se surcharge vite.

Comment lire la health-layer

Ce qui est verifie -> ce qui degrade -> quel composant casse le workflow. Ces trois niveaux doivent toujours etre lus ensemble.

Il faut regarder les tendances dans le temps et les differences entre releases, pas une chute isolee d'un seul check.

Puis regarder les combinaisons de signaux :

• health_check_pass_rate down + timeout_rate up -> le systeme entre en mode instable ;
• synthetic_run_success_rate down + degraded_component_count up -> le probleme impacte deja le workflow critique ;
• queue_time_p95 up + run_count up -> manque de capacity, scaling necessaire ;
• health_score down + error_rate up -> risque eleve d'incident a court terme ;
• tool_check_latency_p95 up + synthetic_run_success_rate down -> bottleneck dans la couche tools externe.

Quand l'utiliser

Un ensemble complet de health checks n'est pas toujours necessaire.

Pour un prototype initial, un check basique de disponibilite API peut suffire.

Mais des health checks detaillees deviennent critiques quand :

• le systeme est deja en production ;
• il y a des SLO/SLA de stabilite ;
• l'agent depend de plusieurs tools externes ou de queues ;
• il faut des alertes precoces avant qu'un echec massif commence.

Exemple d'implementation

Ci-dessous un cycle simplifie de health checks en style Prometheus. L'exemple montre l'approche de base : checks de composants, synthetic run et health score agrege.

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

# perf_counter() est utilise pour des mesures monotones et precises de latency
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 = tous les checks passent, 0.0 = tout echoue
    # +1 pour 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

Voici a quoi ces metriques de health ressemblent sur un dashboard reel :

Investigation

Quand une alerte health se declenche :

1. trouver le check ou workflow en degradation ;
2. regarder les runs problematiques dans le tracing ;
3. verifier timeout, stop_reason et tool failures dans les logs ;
4. trouver la root cause (tool, LLM, queue, routing, release regression).

Erreurs typiques

Meme quand les health checks sont ajoutees, elles apportent souvent peu de valeur a cause des erreurs ci-dessous.

Il y a seulement ping/check de disponibilite

Disponibilite API ne garantit pas que le workflow agentique fonctionne reellement. Sans synthetic run, on manque facilement la degradation cachee.

Pas de checks des dependances externes

Si tools, queues ou base ne sont pas incluses dans les health checks, le systeme peut sembler "sain" jusqu'au premier incident. Dans ce cas, localiser rapidement echec d'outil devient difficile.

Pas de segmentation par workflow et release

Sans cela, il est difficile de comprendre quelle release ou quel scenario a degrade l'etat systeme.

Pas d'alertes sur degradation du health score

Sans alertes, les health checks deviennent de la telemetrie passive. Cela fait manquer les signaux precoces de chaos multi-agent.

Labels a forte cardinalite

Ajouter run_id, request_id ou session_id dans les labels surcharge vite le backend metriques. Il vaut mieux garder ces donnees dans logs et tracing.

Auto-verification

Ci-dessous une checklist courte des health checks de base avant release.

FAQ

Q : En quoi les health checks different des metriques classiques ?
R : Les metriques montrent des tendances, alors que les health checks donnent une reponse rapide "systeme pret ou non maintenant" pour des scenarios concrets.

Q : Quel minimum de health checks faut-il au demarrage ?
R : Commencer avec llm_reachable, tool_available, queue_ok et un synthetic run pour workflow critique.

Q : Pourquoi synthetic run est si important ?
R : Il valide le chemin d'execution complet, pas un composant isole. C'est le meilleur reflet de l'etat reel en production.

Q : Si health score baisse mais API repond encore, est-ce deja un incident ?
R : C'est une degradation precoce. Il faut lancer l'investigation tout de suite avant un echec massif.

Pages liees

Suite du sujet :

• Observability pour agents IA — modele de base du tracing, des logs et des metriques.
• Metriques d'agents — signaux systeme generaux pour production.
• Alerting dans les agents IA — comment construire des alertes precoces.
• Tracing d'agent — comment localiser l'etape qui casse un health check.
• Latency Monitoring pour agents — comment detecter degradation de vitesse avant incident.