Анализ trace агента

Тебе нужно разобрать trace агентской сессии из {{trace_source}} по жалобе {{complaint}}. Не «гадать что было», а реконструировать ход агента шаг за шагом.

1. Что должен дать trace

Минимальный набор полей на каждое событие:

• ts — точное время (мс)
• turn_index — порядковый номер шага модели
• event — turn_start / tool_call / tool_result / turn_end / error
• tool_name, args (отсанированные), duration_ms, status
• tokens_in / tokens_out / cached
• model, stop_reason

Если чего-то нет — сначала ставь телеметрию (см. «Телеметрия для агентов»), потом разбирай. Без полей анализ — это фантазии.

2. Шаг 1: построй timeline

Просто список всех событий по времени, с дельтами:

t+0.0s   turn 1 start  (prompt 4.2k tok)
t+1.8s   tool_call: Grep(pattern="...", path=".")
t+2.1s   tool_result: 180 matches, 12k tok
t+2.1s   turn 1 end (stop: tool_use)
t+2.3s   turn 2 start (context now 16.4k tok)
t+4.0s   tool_call: Read(file="...", offset=0)
...

Цель — увидеть где время и где токены. Часто один взгляд на timeline уже даёт диагноз.

3. Шаг 2: что искать (контрольный список)

Loops

• Один и тот же tool_name с почти одинаковыми args ≥ 3 раз → агент крутится
• turn_index растёт, токены тоже, но stop_reason не меняется → нет прогресса
• Чередование двух tools без новой информации между ними → пинг-понг

Redundant calls

• Re-read одного и того же файла подряд (нет Edit между ними) → лишний токен
• Grep с тем же паттерном в разных директориях → можно было одним вызовом
• Bash для того что есть в встроенном tool (например ls вместо Glob)

Missed tool

• Агент пытается ответить «из головы» там где есть tool (вопрос про файл — не Read, вопрос про время — не Bash)
• stop: end_turn посреди задачи без вызова инструмента → агент сдался
• Длинный текст «возможно файл выглядит так» вместо реального чтения

Hallucinated args

• Путь файла, которого нет в проекте
• Команда с несуществующим флагом
• Передача в инструмент структуры, которой агент не видел в tool_result

Latency

• p95 на один tool > 3s → внешний сервис тормозит
• Длинные паузы между turn_end и turn_start → бэкенд модели троттлит
• tool_result весит 20k токенов → раздувает контекст следующих ходов

Error handling

• error без retry → агент молча сломался
• 5+ retry подряд без backoff → агент в петле
• Catch ошибки и продолжение «как будто всё ок» → даст неверный финал

4. Шаг 3: гипотеза → проверка

Под каждое подозрение — конкретный артефакт из trace:

Гипотеза: агент в петле на чтении одного файла
Доказательство: turns 4, 6, 8, 10 — Read(file="app/page.tsx", offset=0). Между ними нет Edit и нет изменений args.
Импакт: 4 × ~6k токенов = 24k лишних, +12s wall-clock
Фикс: добавить инструкцию «не читай тот же файл дважды без причины»; в debug — кеш Read-результатов

Без «доказательства строкой из trace» — это домыслы, не разбор.

5. Шаг 4: классификация причины

Категории (важно для агрегата по многим инцидентам):

• Prompt — промт не покрыл случай / не запретил поведение
• Tool design — инструмент возвращает слишком много / слишком мало / непредсказуемо
• Context — слишком большой контекст, модель потеряла фокус
• Model — стохастика, на другом seed бы прошло (редко настоящая причина)
• External — внешний сервис упал / timeout
• Data — входные данные не такие как ожидалось

90% причин — Prompt и Tool design. На Model списывай только когда воспроизводится 1 из 50.

6. Формат отчёта

# Trace report: <session_id>

## Жалоба
<одно предложение>

## TL;DR
<1-2 предложения: что произошло и почему>

## Timeline (укороченный)
| t | turn | event | tool | duration | tokens |
...

## Симптомы
- [симптом 1, с указанием turn]
- [симптом 2, ...]

## Корневая причина
- Категория: prompt / tool / context / ...
- Объяснение: ...
- Доказательство: turns X, Y, Z

## Импакт
- Латентность: +N s
- Токены: +K
- Cost: +$X
- UX: <что увидел пользователь>

## Фикс
- [конкретное изменение в промте / tool / инфре]
- [проверка: regression test]

## Repro
- Можно ли воспроизвести? Минимальный input.

Этот формат — стандартный артефакт. Подшивай к incident-doc.

7. Анти-паттерны

• ❌ Разбор «по памяти» без точного timeline — упустишь loop
• ❌ Сразу винить модель — почти всегда виноват промт или tool
• ❌ Trace без correlation ID — не соберёшь сессию из логов
• ❌ Анализ без token-расходов — пропустишь context bloat
• ❌ Фикс без regression-теста — повторится через две недели
• ❌ Длинный отчёт без TL;DR — никто не прочтёт
• ❌ «Это редкий случай, забьём» — обычно это вершина айсберга
• ❌ Удалить trace после фикса — потеряешь возможность сравнить регрессию

На выходе

• Отчёт по шаблону (один файл на инцидент)
• Список симптомов с привязкой к turns
• 1-3 конкретных фикса
• Regression-кейс в наборе evals