Health checks агентів

Ідея за 30 секунд

Health checks для AI-агентів показують, чи система реально готова до трафіку саме зараз.

Вони допомагають виявити деградацію до інциденту: повільні tools, timeout-и, проблеми з чергами або збої в LLM-шарі.

Без health checks часто видно тільки факт збою, але не ранні сигнали перед ним.

Основна проблема

Система може формально бути "up", але фактично працювати нестабільно.

API відповідає, run-и запускаються, але частина кроків уже деградує: росте timeout rate, падає success rate, зростає queue time. Без health checks це зазвичай помітно тільки після каскадного збою.

Далі розберемо, як читати ці сигнали і знаходити компонент, який першим входить у деградацію.

У production це часто виглядає так:

• зовні все "працює", але p95 latency уже виходить за SLO;
• один tool частіше повертає timeout, але проблема ще неочевидна;
• synthetic run починає падати раніше за основний трафік;
• команда реагує вже після часткового збою.

Саме тому health-layer варто моніторити окремо, а не лише через загальні run-метрики.

Як це працює

Health checks зазвичай будуються на двох рівнях:

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

Ці сигнали відповідають на питання «чи система здорова прямо зараз». Логи й трейсинг потрібні, щоб пояснити, чому конкретна перевірка впала.

Up ≠ healthy. Система може бути доступною, але вже втрачати здатність виконувати задачі.

Health checks — це найраніший сигнал проблеми у системі. Вони з'являються раніше, ніж деградація стає помітною в latency або помилках.

Падіння synthetic_run_success_rate зазвичай передує росту timeout_rate і деградації p95 latency.

Типові production-метрики health checks

health_score зазвичай рахується на рівні дашборду або health-сервісу як агрегат із кількох checks, а не як "магічна" одна метрика.

Щоб health-метрики були корисними, їх зазвичай сегментують за release, region, workflow і типом компонента.

Важливо: не додавай у labels висококардинальні поля (run_id, request_id, user_id), інакше сховище метрик швидко перевантажиться.

Як читати health-layer

Що перевіряється → що деградує → який компонент ламає workflow. Це три рівні, які завжди потрібно дивитися разом.

Важливо дивитися на тренди у часі і різницю між релізами, а не на одиничне падіння однієї перевірки.

Далі дивимось на комбінації сигналів:

• health_check_pass_rate ↓ + timeout_rate ↑ → система входить у нестабільний режим;
• synthetic_run_success_rate ↓ + degraded_component_count ↑ → проблема вже впливає на критичний workflow;
• queue_time_p95 ↑ + run_count ↑ → бракує capacity, потрібне масштабування;
• health_score ↓ + error_rate ↑ → високий ризик інциденту в найближчий час;
• tool_check_latency_p95 ↑ + synthetic_run_success_rate ↓ → bottleneck у зовнішньому tool-layer.

Коли використовувати

Повний набір health checks не завжди потрібен.

Для раннього прототипу інколи достатньо базової перевірки доступності API.

Але детальні health checks стають критичними, коли:

• система вже в production;
• є SLO/SLA по стабільності;
• агент залежить від кількох зовнішніх tools або черг;
• потрібні ранні алерти до того, як почнеться масовий збій.

Приклад реалізації

Нижче — спрощений приклад health-check циклу в стилі Prometheus. Приклад показує базовий підхід: перевірки компонентів, synthetic run і агрегований health score.

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

# perf_counter() використовується для точних монотонних вимірювань 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 = усі перевірки пройдені, 0.0 = усе впало
    # +1 для 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

Ось як health-метрики виглядають у реальному дашборді:

Investigation

Коли спрацьовує health-алерт:

1. знайти check або workflow з деградацією;
2. подивитись проблемні runs у трейсингу;
3. перевірити в логах timeout, stop_reason і tool failures;
4. знайти root cause (tool, LLM, queue, routing, release regression).

Типові помилки

Навіть коли health checks уже додані, вони часто не дають користі через типові помилки нижче.

Є тільки ping/check доступності сервісу

Доступність API не гарантує, що агентний workflow реально працює. Без synthetic run легко пропустити приховану деградацію.

Немає перевірок зовнішніх залежностей

Якщо tools, черги або БД не входять у health checks, система може виглядати "здоровою" до першого інциденту. У такій ситуації складно швидко локалізувати збій інструмента.

Немає розбиття за workflow і release

Без цього важко зрозуміти, який саме реліз або сценарій погіршив стан системи.

Немає алертів на деградацію health score

Без алертів health checks стають пасивною телеметрією. Через це легко пропустити ранні сигнали хаосу мультиагентної системи.

Висококардинальні labels

Додавання run_id, request_id або session_id у labels швидко перевантажує бекенд метрик. Краще тримати ці дані в логах і трейсингу.

Самоперевірка

Нижче — короткий checklist базових health checks перед релізом.

FAQ

Q: Чим health checks відрізняються від звичайних метрик?
A: Метрики показують тренд, а health checks дають швидку відповідь "система зараз готова чи ні" для конкретних сценаріїв.

Q: Який мінімум health checks потрібен на старті?
A: Почни з перевірок llm_reachable, tool_available, queue_ok і одного synthetic run для критичного workflow.

Q: Чому synthetic run такий важливий?
A: Бо він перевіряє цілісний шлях виконання, а не окремий компонент. Саме це найкраще показує реальний production-стан.

Q: Коли health score падає, а API ще відповідає — це вже інцидент?
A: Це рання деградація. Потрібно запускати investigation одразу, поки проблема не стала масовим збоєм.

Пов'язані сторінки

Далі за темою:

• Observability для AI-агентів — базова модель трейсингу, логів і метрик.
• Метрики агентів — загальні системні сигнали для production.
• Алерти у AI-агентах — як будувати ранні сповіщення.
• Трейсинг агента — як локалізувати крок, що ламає health check.
• Моніторинг затримок агентів — як виявляти деградацію швидкості до інциденту.