Почему AI-агенту нужна наблюдаемость: циклы, misuse инструментов и тихие ошибки

Вы поставили Prometheus, написали алерты на 5xx и p95 latency, у вас structured JSON-логи и сквозной request-ID. Сервер под этим стопом наблюдает за собой как надо — и при этом вы впервые узнаёте о проблеме из счёта за API: агент 40 минут крутился вокруг одной задачи, звал не тот инструмент и сжёг бюджет, а все ваши дашборды показывали зелёный. Это не дыра в вашем мониторинге. Это дыра в предположении, что сбой выглядит как ошибка.

Классический APM (application performance monitoring, «мониторинг производительности приложения») ловит отказы: процесс упал, запрос не ответил, статус 500. AI-агент почти никогда не «падает» в этом смысле. Он возвращает 200 на каждом шаге и при этом не приближается к цели. Наблюдаемость за агентом — это не «ещё один лог-файл», а отдельная дисциплина, потому что у агента есть три сущности, которых нет у обычного HTTP-клиента: цикл, решение какой инструмент звать и поток денег. Эта статья — установочная для серии: здесь задаём рамку и боль, словарь атрибутов (OpenTelemetry GenAI) разберём в №2, готовую телеметрию Claude Code и Copilot — в №3, а то, как собрать свой лёгкий слой на PHP, — в №6.

Термин-ловушка — снять сразу. В сети у нас есть статья «Наблюдение за DOM и производительность» — там наблюдатели это IntersectionObserver/MutationObserver внутри браузера, клиентский код следит за разметкой страницы. Здесь observability (наблюдаемость) — серверная: вы следите за тем, что делает модель и инструменты у вас на бэкенде. Одно русское слово, противоположные мишени. Дальше под «наблюдаемостью» мы имеем в виду именно серверную.


Часть I. Агент — это цикл, и это ломает всю вашу терминологию

1. Что такое «agent loop»

Код-ассистент, который «сам всё сделает», устроен не как «отправил промпт → получил ответ». Он устроен как цикл с памятью о состоянии (англ. agent loop — «петля агента»):

пока задача не завершена:
    1. отправить модели текущий контекст (историю + результат последних шагов)
    2. модель отвечает: либо текст пользователю, либо "хочу вызвать инструмент X с аргументами Y"
    3. если вызов инструмента — исполнить X у себя (grep, запуск теста, правка файла, HTTP-запрос)
    4. положить результат инструмента в контекст
    5. goto 1

Каждый проход — это полноценный запрос к модели, в который кладётся вся накопленная история. Отсюда три следствия, каждое из которых само по себе меняет метрики.

Следствие 1: один «запрос» к агенту — это N запросов к модели. Когда вы смотрите requests per second к своему эндпоинту агента и думаете «у нас низкая нагрузка», вы меряете циклы, а не вызовы модели. Один цикл легко даёт 10–40 вызовов модели, и каждый следующий дороже предыдущего (об этом — экономика в №5). Метрика «сколько запросов к агенту» для планирования ёмкости и биллинга практически бесполезна — полезна «сколько итераций и токенов на завершённую задачу».

Следствие 2: у цикла есть состояние, и оно живёт в контексте, а не в памяти процесса. «Транзакция» агента — это conversation (беседа) с идентификатором. Именно он, а не request-ID, — ось, вокруг которой надо группировать всё: вызовы модели, инструменты, стоимость, решения. В OpenTelemetry GenAI это отдельный атрибут gen_ai.conversation.id, и это, кстати, единственный зафиксированный в реестре атрибут, который явно пропагируется (проталкивается) между операциями — остальные живут внутри операции (про реестр атрибутов — №2).

Следствие 3: цикл может не закончиться. У обычного HTTP-запроса конечность гарантирована сетевым стеком: кто-то закрыл соединение, истёк таймаут. У агентного цикла конечность — ваша ответственность. Если модель на каждом шаге решает «ещё один инструмент вызову и посмотрю», а вы не ограничили число итераций, вы получите корректный, валидный, каждый-шаг-успешный поток, который никогда не завершается. Это и есть runaway loop — первый из трёх сбоев, которые разберём в Части II.

Опора на базу. Что такое span, trace, как пробрасывать request-ID через traceparent и куда складывать structured JSON-логи — всё это у вас уже должно быть, и это разбирает «Логирование и трассировка». Эта серия не пересказывает базу: она берёт её как данность и надстраивает агентную семантику — «что класть в span’ы, чтобы видеть цикл, а не только HTTP-статусы».


Часть II. Три класса сбоев, которые не бросают исключений

Это сердце статьи. Каждый класс — реальный сбой, который вы не увидите в логах уровня ERROR и не поймаете алертом на error rate.

1. runaway loop — бесконечная рекурсия, которая «успешна»

Агент вызывает инструмент, получает результат, вызывает тот же инструмент с теми же (или почти теми же) аргументами, снова получает результат, снова вызывает… Модель на каждом шаге думает, что она «продвигается», потому что в контексте появляются новые токены. Никакой ошибки нет. Каждый вызов вернул 200. Каждый инструмент отработал success: true.

Чем это кончается:

  • счёт за API (или исчерпание купленного лимита токенов) улетает в космос за одну задачу;
  • p95 latency вашего агента «в норме», потому что каждый отдельный шаг быстрый — медленно только целое;
  • пользователь видит «работает…», и вы включили мониторинг не туда.

Что это ловит: счётчик итераций на цикл (не на запрос) и алерт «цикл > K итераций». Это метрика-страховка, её нет в классическом APM. Ниже в Части V она появится как loop_guard.

2. tool misuse — валидный вызов не того инструмента

Агент имеет список инструментов (functions/tools, которые вы ему дали). tool misuse — не когда вызов упал, а когда вызов прошёл успешно и был не тем, который нужен:

  • модель позвала read_file вместо edit_file (и получила 200 с содержимым файла, решив, что «что-то сделала»);
  • позвала инструмент с плохими аргументами, инструмент «успешно» вернул пустой результат, модель приняла пустоту как сигнал «ничего не найдено» и пошла дальше с неверной картиной;
  • вызвала инструмент, который не должен был быть доступен агенту (у вас был drop_table в списке инструментов «для отладки»);
  • вызвала один инструмент столько раз, сколько не надо (надстройка над runaway loop, но поведенчески это misuse конкретного инструмента).

Что это ловит: счётчик решений и исходов инструментов — tool.name, success, error_type, размер входа/выхода. У Claude Code это готовые метрики и события: tool_result несёт tool_name, success, duration_ms, error_type; отдельный tool_decision считает accept/reject правки (claude_code.code_edit_tool.decision). В классическом мониторинге у вас нет понятия «принято/отклонено решение» — оно есть только потому, что агент принимает решения.

3. Тихая деградация и каскад 4xx — «не та модель» против «провайдер не жив»

Здесь сбоев два, и их нельзя путать, иначе вы будете лечить не то.

  • Каскад 429 (rate limit). Провайдер жив, но режет вас по частоте. Каждый отдельный шаг — валидный ответ с 429. Один 429 — retry, норма. Десятки подряд в пределах одного цикла — деградация, и если вы не отличаете «429 на одном провайдере» от «429 на всех», вы не заметите, что у вас весь выход в модель стал медленным, пока пользователь не уйдёт.
  • 403 уровня доступа к модели. Это не ошибка транспорта и не rate limit. Модель может быть в списке /v1/models формально, но ваш аккаунт/команда не имеет к ней доступа — ответ 403 team_model_access_denied. Если классифицировать это как «провайдер лежит» и включить circuit breaker — вы зря снимете живого провайдера. Если не отличить от «модели нет вообще» — вы будете будить ночного дежурного из-за опечатки в имени модели.

Прожитый кейс (без внутренних имён). В одной из наших связок «провайдер ↔ модель» 403 с классификацией «доступ запрещён на уровне команды» прилетал даже на эталонную модель, которая гарантированно доступна. Система, которая просто считывала «403 = провайдер нездоров», честно и правильно валила failover на следующего провайдера, хотя первый был абсолютно жив — падала конкретная пара «ключ↔модель», а не транспорт. Урок: код статуса сам по себе не классифицирует сбой для агента; классифицирует связка «код + кто именно + какая модель + какой эндпоинт». Это машина состояний, а не if status != 200. Её скелет — в Части V, детальная сборка слоя — в №6.


Часть III. Почему «HTTP 200 = успех» ломается на агенте

Возьмите вашу типичную алерт-логику. Она почти наверняка выглядит как одно из:

  • error_rate > 1% по 5xx;
  • http_requests_total{status=~"5.."};
  • health-check эндпоинта отвечает 200;
  • p95 latency ниже порога.

Теперь наложите на агентный цикл из Части I. Ни один из этих сигналов не краснеет при runaway loop, tool misuse или тихой деградации, потому что:

Ваш сигналЧто он меряетПочему слеп к агенту
5xx error rate«сервер не ответил»Агент получает 200 на каждом шаге цикла. Ошибки агента — это 200 с неверным решением внутри.
Health-check 200«процесс жив»Живой процесс может крутить бесконечный цикл и жечь деньги — он и «жив», и «не работает» одновременно.
p95 latency (per request)«один вызов быстрый»latency шага в норме; latency задачи (= сумма N шагов) растёт квадратично, и его никто не мерит «на задачу».
Counter вызовов к агенту«сколько циклов запустили»Не говорит, сколько итераций сожрал каждый цикл. 1 цикл × 50 итераций = 50 × 1 цикл по деньгам, но не по этой метрике.

Правильная ось для агента — успех, измеренный по факту полезного действия, а не по коду ответа. Три способа его определить:

  1. Завершённость цикла — цикл вышел по своему штатному признаку конца (finish_reason = stop, tool_call = none, достигнут лимит итераций), а не оборвался таймаутом процесса.
  2. Полезный исход — был создан PR, применена правка, дан ответ (у Claude Code это счётчики pull_request.count, commit.count, lines_of_code.count).
  3. Исход инструмента — каждый вызов инструмента помечен success + duration_ms + error_type, а не «HTTP-статус инструмента».

Это не отменяет ваших текущих алертов — это надстройка над ними. Ваш Prometheus из «Метрики и мониторинг» остаётся мерить «жив ли сервер»; поверх появляется вопрос «а справился ли агент, и чего ему это стоило».


Часть IV. Три агентных сигнала и словарь, который их описывает

Если унести из статьи одно — унесите эти три сигнала. У классического APM их нет, потому что у классического приложения нет циклов, решений и счётчика денег на операцию.

Сигнал 1: итерации на задачу

Сколько проходов сделал цикл. Это ваш loop guard: без него runaway loop невидим. Как считать — в Части V.

Сигнал 2: стоимость на задачу

Накопленные input_tokens + output_tokens (+ cache_read / cache_write, у кого есть caching), пересчитанные в деньги. Claude Code отдаёт это прямо: метрика claude_code.token.usage (с атрибутом type = input/output/cacheRead/cacheCreation) и claude_code.cost.usage (USD). В OpenTelemetry GenAI для этого группа атрибутов gen_ai.usage.*:

# otel-genai-demo.py — как выглядят "итерации" и "стоимость" в терминах OTel GenAI
# (имена атрибутов — из реестра на 07.11.2026, СТАТУС = Development, см. ниже «осторожно»)
from opentelemetry import trace

tracer = trace.get_tracer("agent-loop")

def run_agent_turn(history):
    # span на один вызов модели: операция = chat
    with tracer.start_as_current_span("chat qwen3-coder") as span:
        span.set_attribute("gen_ai.operation.name", "chat")
        span.set_attribute("gen_ai.provider.name", "openai")     # НЕ gen_ai.system (старое имя)
        span.set_attribute("gen_ai.request.model", "qwen3-coder")
        span.set_attribute("gen_ai.conversation.id", history.session_id)  # ось цикла
        resp = call_llm(history)
        span.set_attribute("gen_ai.usage.input_tokens",  resp.usage.input)
        span.set_attribute("gen_ai.usage.output_tokens", resp.usage.output)
        # длительность вызова модели — отдельная гистограмма, не generic-метрика:
        #   gen_ai.client.inference.duration (s), gen_ai.server.time_to_first_token (s)
        return resp

Стоимость как сигнал отличается от стоимости как отчёта. Отчёт («сколько мы потратили за месяц») нужен бухгалтеру. Сигнал («эта конкретная задача сожрала 12k токенов и не завершается») нужен вам, чтобы поймать runaway loop до счёта. Это одно и то же число в разных разрезах: отчёт считает по аккаунту/дню, сигнал — по conversation.id.

Сигнал 3: решения (какой инструмент, принят/отклонён, успех/ошибка)

Здесь живёт tool misuse. OTel GenAI выделяет для этого отдельную операцию execute_tool (span execute_tool {gen_ai.tool.name}) и invoke_agent (когда поток управления ведёт LLM), а инструментные исходы и решения — то, что Claude Code кладёт в tool_result/tool_decision. Без этого сигнала вы видите «агент что-то делал», но не видите «агент не туда делал».

Осторожно: стандарт есть, но он Development — и имена уже менялись

Это не сноска, а предмет разговора. GenAI-семантические конвенции OpenTelemetry имеют статус Development (стабильны пока только общие error.type, server.*, network.*, exception.*). Более того, они переехали из основного репозитория semantic-conventions в отдельный open-telemetry/semantic-conventions-genai, и по дороге переименовали часть имён. Что изменилось и почему это важно при написании кода — полностью в №2; здесь зафиксируем правило серии:

Не хардкодьте дословное имя атрибута как контракт. Пишите слой так, чтобы смена имени (gen_ai.system → gen_ai.provider.name, gen_ai.client.token.usage → gen_ai.client.inference.usage.*) была одной строкой конфигурации, а не миграцией дашбордов. Привязывайтесь к схеме («у меня есть поле «входные токены на вызов модели»»), а к имени атрибута — только на уровне адаптера, который вы меняете, когда спека сдвигается.


Часть V. Начать можно без SaaS: кольцевой журнал + breaker + loop guard

Самая частая реакция на «нужна observability» — «значит, надо поставить Langfuse/Grafana Cloud/Jaeger». Иногда да. Но для веб-мастера с PHP-сайтом на VPS, который встроил пару LLM-инструментов и не хочет отправлять содержимое промптов во внешний облачный SaaS, есть путь покороче и честнее по приватности (та же линия «владей данные сам», что в «Локальные модели для приватности»). Покажем три скелета — концепции, не имена конкретного продукта.

1. Кольцевой буфер последних N событий (event ring)

Когда провайдер начал валить 429, а потом вернул 403, вам не нужен весь лог за неделю — вам нужна последняя лента событий вызова, чтобы за минуту увидеть паттерн (это ровно то, что делает кольцевой журнал авторского слоя (из №6); здесь — абстрактная реализация).

PHP
<?php
// ai-event-ring.php — кольцевой журнал последних N событий AI-вызова.
// Хранится в одной option/таблице; без внешних зависимостей.
// Домены/ключи — плейсхолдеры example.test.

function ai_ring_push( array $event ): void {
    $max  = 200;
    $ring = get_option( 'ai_event_ring', [] );

    $event['ts'] = time();
    // Нормируем в плоский массив: что за операция, чем, код, длительность, session.
    $event['op']        = $event['op'] ?? 'unknown';       // chat | execute_tool | invoke_agent
    $event['provider']  = $event['provider'] ?? 'unknown'; // id провайдера (не секрет!)
    $event['model']     = $event['model'] ?? '';
    $event['http']      = $event['http'] ?? 0;             // код транспорта, 0 = не дошёл
    $event['class']     = ai_classify( $event );           // ВАЖНО: не сырой http (см. ниже)
    $event['dur_ms']    = $event['dur_ms'] ?? 0;
    $event['conv']      = $event['conv'] ?? '';            // conversation.id — ось цикла

    $ring[] = $event;
    if ( count( $ring ) > $max ) {
        $ring = array_slice( $ring, -$max );               // оставляем хвост: это и есть «кольцо»
    }
    // autoload=false — не тащим 200 событий в каждый автозагрузочный SELECT.
    update_option( 'ai_event_ring', $ring, false );
}

function ai_ring_recent( int $n = 30 ): array {
    $ring = get_option( 'ai_event_ring', [] );
    return array_slice( $ring, -$n );
}

Кольцо — это дешёвая замена «платформы логов» для задачи «загляни и посмотри, что происходило последние несколько минут». У него есть потолок глубины (200 событий), и это нормально: наблюдаемость агента нужна не для месячной аналитики, а чтобы ответить на «почему этот цикл не закончился прямо сейчас».

2. class вместо http: классификатор сбоя

Главная ошибка, которую делает слой «на кодах статусов»: он лечит код, а надо лечить класс сбоя (из Части II.3). Код 403 у вас означает и «провайдер жив, модели нет», и «ключ-пара-доступ запрещён», и «несанкционированный запрос» — а действовать надо по-разному.

PHP
<?php
// ai-classify.php — один источник правды: «что именно случилось».
// Возвращает класс, по которому решаем — retry / breaker / alert / ignore.

function ai_classify( array $event ): string {
    $http = (int) $event['http'];

    if ( 0 === $http ) {
        return 'transport';          // curl/файрвол/таймаут — до API не дошли.
    }
    if ( 200 <= $http && $http < 300 ) {
        return 'ok';                 // транспорт ОК; semantic-успех — уже по содержимому (не здесь).
    }
    if ( 429 === $http ) {
        return 'rate';               // провайдер ЖИВ, режет частоту. retry с backoff, НЕ breaker.
    }
    if ( 404 === $http ) {
        return 'no_deploy';          // «модели нет на этом эндпоинте» — не болезнь провайдера.
    }
    if ( 403 === $http ) {
        // Критично: 403 НЕ равен «провайдер мёртв». Часто это доступ к конкретной модели.
        // Тело несёт код вида team_model_access_denied / model_not_found:
        $detail = $event['detail'] ?? '';
        if ( false !== strpos( $detail, 'access_denied' ) ) {
            return 'access_denied';  // пара «ключ↔модель» запрещена; транспорт здоров.
        }
        return 'forbidden';
    }
    if ( 500 <= $http && $http < 600 ) {
        return 'overload';           // провайдер/модель перегружены или легли. Кандидат под breaker.
    }
    return 'other';
}

Заметьте: ok по транспорту ≠ успех агента. ai_classify отвечает на «дошёл ли запрос», а «полезно ли модель поступила» — уже по содержимому (finish_reason, tool_result.success), и это другая функция (Сигнал 3). Разделение принципиальное — именно оно спасает вас от «зря завалили живого провайдера».

3. Loop guard + breaker: счётчики, которых нет в APM

Два счётчика, без которых агентные сбои Части II невидимы.

PHP
<?php
// ai-loop-guard.php — и счётчик итераций (ловит runaway loop), и breaker
// (отделяет "болезнь" провайдера от опечатки/403-по-доступу).

// --- Loop guard: счётчик итераций НА conversation, не на запрос ---
function ai_iter_bump( string $conv ): ?int {
    $key   = 'ai_iter_' . md5( $conv );
    $count = (int) get_transient( $key ) + 1;
    set_transient( $key, $count, 3600 ); // окно жизни = типичной длительности одной задачи
    if ( $count > 40 ) {
        // Кандидат на runaway loop. Не убиваем молча: пишем событие в кольцо и алертим.
        ai_ring_push( [ 'op' => 'invoke_agent', 'class' => 'loop_alarm', 'conv' => $conv, 'iter' => $count ] );
    }
    return $count;
}

// --- Circuit breaker: только по классам "болезнь транспорта/перегрузка" ---
// access_denied / no_deploy НЕ гасят провайдера — это не его болезнь.
function ai_breaker_register( string $provider, string $class ): void {
    $fail_key = 'ai_br_fails_' . $provider;
    $open_key = 'ai_br_open_' . $provider;

    $is_illness = in_array( $class, [ 'transport', 'overload' ], true ); // НЕ 'rate', НЕ 'access_denied'
    $fails = $is_illness ? (int) get_transient( $fail_key ) + 1 : 0;

    if ( $fails >= 5 ) {
        set_transient( $open_key, 1, 300 );        // «нездоров» на 5 минут → следующий шаг уйдёт на failover
        delete_transient( $fail_key );
        ai_ring_push( [ 'op' => 'invoke_agent', 'provider' => $provider, 'class' => 'breaker_open' ] );
    } else {
        set_transient( $fail_key, $fails, 60 );    // окно, в котором считается «подряд»
    }
}

function ai_provider_unhealthy( string $provider ): bool {
    return (bool) get_transient( 'ai_br_open_' . $provider );
}

Три детали, за которые этот скелет уже стоит того, чтобы его иметь:

  • loop guard считает итерации по conversation — ровно то, чего нет у rps/latency, и ровно то, что делает runaway loop видимым;
  • breaker открывается по классу, а не по коду — потому что 429 (rate) — не повод валить провайдера (он жив, это retry), а 403 access_denied — тем более (падает пара «ключ↔модель», не транспорт);
  • каждое интересное событие пишется в кольцо, и вы чините по ленте из Части V.1, а не гадаете.

Это не полноценная наблюдаемость-платформа — и не претендует. Это минимальный слой, который закрывает три сигнала Части IV, живёт на одном WordPress без sidecar’а и не отправляет содержимое промптов наружу. Полная сборка (журнал + breaker + health-монитор моделей + экспорт в Prometheus, чтобы встроиться в ваш metiki-i-monitoring) — №6.


Инструменты под задачу

  • Разобрать ленту событий / найти паттерн в логах вызова — AI-анализатор логов на codestack.space: вставьте выгрузку кольцевого журнала (Часть V.1) или фрагмент логов провайдера — инструмент выделит, что происходит (каскад 429, повторяющийся инструмент, тихая деградация).
  • Прогнать свой цикл агента и попросить разобрать построчно — AI-ассистент для кода: покажите свою реализацию loop/breaker и спросите «где этот цикл может уйти в runaway и не заметить этого».

Чек-лист граблей

  1. Мерить rps агента вместо итераций. 1 цикл × 30 итераций выглядит как «1 запрос, всё спокойно». Заведите счётчик итераций на conversation.id — иначе runaway loop для вас невидим до счёта за API.
  2. Считать 200 успехом. Успех агента — это завершённость цикла и исход инструмента (success, finish_reason, создан ли PR), а не код ответа. Отдельный вызов мог вернуть 200 с неверным решением внутри.
  3. Лечить код статуса, а не класс сбоя. 403 — это и «модели нет», и «доступ к модели запрещён на уровне команды», и «не тот ключ». Breaker надо включать по классу (transport/overload — да, rate/access_denied/no_deploy — нет), иначе вы валите живого провайдера из-за опечатки в имени модели.
  4. Открывать breaker по 429. Rate-limit — это «провайдер жив, но режет частоту»; правильный ответ — backoff+retry, а не failover на второго (второй через минуту начнёт резать так же). См. механику лимитов в «Защита API: rate limiting».
  5. Хардкодить имя атрибута gen_ai.* как контракт. Спека — Development и уже переименовывала (gen_ai.system → gen_ai.provider.name, client.token.usage → client.inference.usage.*). Держите маппинг имён в одном адаптере.
  6. Ставить платформу до того, как поняли, что мерить. Кольцевой журнал + loop guard + breaker (Часть V) дают основную пользу без Langfuse/Cloud/Jaeger и без утечки промптов. Платформа нужна, когда этих трёх сигналов мало, а не как первый шаг.
  7. Ждать ошибки там, где её не будет. Агент, уходящий в рекурсию, бросает 0 исключений и 0 ERROR-строк в логе. Ваш единственный индикатор — «цикл не завершился за ожидаемое число шагов и стоимость растёт». Если вы не меряете итерации/стоимость/завершённость, вы этого не увидите никогда.
  8. Смешать клиентское «наблюдение» с серверным. IntersectionObserver из статьи про DOM не имеет отношения к наблюдаемости агента. Уточняйте в команде, о каком из двух «наблюдений» речь — как мы делали с «воркером» в Edge-серии.

👤 Зарегистрируйтесь, чтобы добавить материал в закладки.