ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Написать runbook для агента

1. Цель задачи

Разработать и задокументировать runbook (план действий) для оперативного реагирования на типовые ошибки AI-агента: галлюцинации, зависание в бесконечном цикле, превышение лимита шагов, некорректный вызов инструментов. Основной фокус — сокращение времени обнаружения инцидента (MTTD — Mean Time to Detection) до менее 5 минут и обеспечение воспроизводимого процесса диагностики и исправления.

Ключевой результат Runbook в формате Markdown, который позволяет дежурному инженеру зафиксировать симптом, классифицировать ошибку, применить корректную процедуру и восстановить нормальную работу агента — всё в течение 5–15 минут.

2. Исходные данные

Если нет реальной системы — симулируем:

1. Собрать простого агента (Python + OpenAI API / Ollama + LangGraph) с 2–3 инструментами (например, search_web, calculator, get_weather).
2. Добавить преднамеренные неисправности:
   • В одном из инструментов вызвать while True: при определённом входе (бесконечный цикл).
   • Для галлюцинации: модифицировать промпт агента, чтобы он игнорировал контекст и генерировал выдуманные факты.
   • Установить искусственный лимит шагов (например, max_iterations=3), чтобы агент обрывался.
3. Собрать логи в формате JSON с метками времени, типом события (start, tool_call, response, error).

3. Технологический стек

4. Этапы выполнения

Этап 1: Классификация типовых ошибок агента (1–2 часа)

Действия

1. Проанализировать возможные сбои агента (на основе документации фреймворков и реальных кейсов). Составить таблицу:

   Тип ошибки	Признаки	Пример
   Галлюцинация	Ответ содержит факты, отсутствующие в предоставленных источниках (например, агент выдумывает цену акции)	User: "Какая цена TSLA?" → Agent: "456 USD" (реальная цена 350)
   Бесконечный цикл	Агент повторяет один и тот же вызов инструмента с одинаковыми параметрами без прогресса	Лог: call_tool("search_web", "погода Москва") повторяется 20 раз
   Зависание (hang)	Агент не отвечает более 60 секунд на запрос	Тайм-аут в API gateway
   Некорректный вызов инструмента	Агент передаёт неверные аргументы, вызывает несуществующий инструмент	call_tool("get_price", symbol="MSFT", exchange="BINANCE") — инструмент не поддерживает криптобиржи
   Превышение лимита шагов	Количество вызовов инструментов превышает порог (например, 50)	total_steps=52, ответ не получен

2. Определить пороги срабатывания алертов:

   • steps_per_request > 30 → алерт "Возможный бесконечный цикл"
   • response_time > 30s → алерт "Зависание"
   • accuracy_check_failed (при наличии пайплайна верификации) → алерт "Галлюцинация"

Ожидаемый результат этапа Таблица классификации с порогами, согласованная с командой.

Этап 2: Настройка наблюдаемости и алертов (2–3 часа)

Действия

1. Добавить структурированное логирование в код агента:

   import logging
   import json
   
   logger = logging.getLogger("agent")
   handler = logging.StreamHandler()
   handler.setFormatter(logging.Formatter(json.dumps({
       "timestamp": "%(asctime)s",
       "level": "%(levelname)s",
       "agent_id": "...",
       "event": "%(message)s"
   })))
   logger.addHandler(handler)
   # Пример логирования при вызове инструмента
   logger.info({"event": "tool_call", "tool": "search_web", "query": "weather Moscow", "step": step_num})
   

2. Экспортировать ключевые метрики в Prometheus (через prometheus_client):

   from prometheus_client import Counter, Histogram, Gauge, start_http_server
   
   STEPS_COUNTER = Counter('agent_steps_total', 'Total agent steps', ['agent_id', 'tool'])
   LLM_CALL_DURATION = Histogram('agent_llm_duration_seconds', 'LLM call latency')
   CURRENT_STEP_GAUGE = Gauge('agent_current_step', 'Current step number for active request', ['request_id'])
   ERROR_COUNTER = Counter('agent_errors_total', 'Total errors', ['type'])  # type: hallucination, loop, hang
   

3. Настроить алерты в Grafana / Alertmanager:

   • rate(agent_steps_total[5m]) > 50 → предупреждение
   • agent_llm_duration_seconds{quantile="0.95"} > 15 → критический
   • agent_errors_total[1m] > 2 → критический

4. Разработать дашборд Grafana с панелями:

   • Количество шагов за запрос (heatmap)
   • Топ инструментов по времени выполнения
   • Количество ошибок по типам за последний час
   • Время обнаружения инцидента (MTTD) за неделю

Ожидаемый результат этапа Работающий мониторинг, алерты приходят в Slack/Telegram, дашборд доступен.

Этап 3: Разработка процедур реагирования (runbook) (2–3 часа)

Действия

1. Создать файл runbook_agent_errors.md со следующей структурой (обязательные разделы):

   # Runbook: Ошибки AI-агента
   
   ## 1. Быстрая диагностика (первые 5 минут)
   
   | Симптом | Что делать | Куда смотреть |
   |---------|------------|---------------|
   | Агент не отвечает >30s | Проверить статус LLM API | Дашборд `LLM latency` |
   | Ответ содержит фактические ошибки | Сравнить с базой знаний / верификатором | Логи последнего вызова, tool outputs |
   | Агент повторяет одно и то же | Проверить количество шагов | Grafana `steps_per_request` |
   
   ## 2. Детальный разбор по типу ошибки
   
   ### 2.1. Галлюцинация
   [[Вики/Check|Верификация]]
   - Проверить, был ли передан соответствующий контекст (retrieved chunks).
   - Если да, проверить, учёл ли агент их в ответе (сравнить ответ с контекстом).
   Временные меры
   - Уменьшить `temperature` до 0.0.
   - Включить принудительную цитату (instruct модель: "always quote the source").
   Постоянное исправление
   - Добавить validation pipeline (LLM-as-judge или факт-чекинг).
   
   ### 2.2. Бесконечный цикл
   **Обнаружение:**
   - Если `steps > 30` в течении 10 секунд — экстренно прервать запрос (raise TimeoutError).
   Временные меры
   - Увеличить `max_iterations`? Нет — это не решит проблему. Правильнее: добавить guardrail на повторяющиеся вызовы одного инструмента с одинаковыми аргументами.
   Постоянное исправление
   - Ввести кэш вызовов инструментов (same (tool, args) → return cached result).
   - Добавить детектор цикла: if same tool call repeated > N times → break.
   
   ## 3. Эскалация
   - Если не удаётся восстановить за 15 минут → #team-ai, #oncall.
   - Контакты: ...
   

2. Добавить чек-лист “First Responder”:

   • Открыть дашборд Grafana
   • Найти аномальные метрики
   • Получить логи последних 10 запросов
   • Определить тип ошибки по таблице
   • Применить временную меру
   • Уведомить канал инцидентов

3. Написать скрипт-помощник (Python), который по alert_name выводит нужную секцию runbook:

   # get_runbook_section.py
   sections = {
       "agent_loop": "### 2.2. Бесконечный цикл",
       "agent_hallucination": "### 2.1. Галлюцинация",
   }
   if sys.argv[1] in sections:
       print(sections[sys.argv[1]])
   

Ожидаемый результат этапа Файл runbook_agent_errors.md со всеми разделами, скрипт получения секции.

Этап 4: Тестирование runbook (симуляция инцидентов) (1–2 часа)

Действия

1. Создать test scenarios:

   Сценарий	Действие	Ожидаемая реакция runbook
   1	Внедрить бесконечный цикл (один из инструментов зациклен)	Алерт «possible loop» → диагностика → применить guardrail
   2	Увеличить температуру LLM до 1.5, чтобы получить галлюцинации	Алерт «hallucination» (если есть верификатор) или ручная проверка → снизить температуру
   3	Имитировать зависание LLM API (добавить sleep 120)	Алерт «hang» → проверить статус провайдера → отключить агента на 5 минут

2. Провести «tabletop exercise» с коллегой (или solo), засекая время:

   • Получен алерт (0 мин)
   • Открыть runbook (1 мин)
   • Определить тип ошибки и применить временную меру (3 мин)
   • Убедиться, что метрики возвращаются к норме (5 мин)

3. Зафиксировать время обнаружения (MTTD) для каждого сценария. Если MTTD > 5 минут — доработать мониторинг или runbook.

Ожидаемый результат этапа Все сценарии пройдены, MTTD ≤ 5 мин, runbook скорректирован по итогам тестирования.

Этап 5: Документирование и интеграция в процессы (1 час)

Действия

1. Поместить runbook в репозиторий (docs/runbooks/agent_errors.md).
2. Добавить ссылку в описание дашборда Grafana и в сообщения алертов (например, в поле annotations алерта добавить runbook: http://...).
3. Подготовить краткое описание для дежурных инженеров (1-2 страницы) — «Quick Reference Card».
4. Обновить postmortem template — добавить вопрос «Runbook applied?».

Ожидаемый результат этапа Runbook доступен из алертов, все дежурные ознакомлены.

5. Критерии приемки (Definition of Done)

• Создана классификация минимум 4 типов ошибок (галлюцинации, бесконечный цикл, зависание, некорректный вызов инструмента).
• Настроен мониторинг (Prometheus + Grafana) со сбором ключевых метрик (шаги, latency, ошибки).
• Алерты отправляются в коммуникационный канал (Slack/Telegram) и содержат ссылку на runbook.
• Runbook содержит разделы «быстрая диагностика», «детальный разбор по типу ошибки», «эскалация» и «чек-лист first responder».
• Проведены симуляции минимум 2 типов инцидентов, MTTD ≤ 5 минут для каждого.
• Runbook версионируется в Git, и его изменения проходят ревью.
• В сообщении алерта содержится рекомендация по запуску скрипта get_runbook_section.py <alert_name>.

6. Ожидаемый результат

Основной артефакт runbook_agent_errors.md — полный документ, содержащий:

• Классификацию ошибок с порогами
• Пошаговые инструкции для диагностики и исправления
• Чек-лист first responder
• Инструкцию по эскалации

Дополнительно (опционально):

• get_runbook_section.py — скрипт быстрого доступа к секции по имени алерта.
• Grafana dashboard JSON (экспорт).
• Alert rules YAML для Prometheus/Alertmanager.
• Quick Reference Card (1 страница).

7. Возможные сложности и их решение

8. Бюджет времени (оценка)

Примечание При первом выполнении (без готового агента) время может увеличиться на 2–4 часа из-за этапа создания агента и симуляции. Опытные инженеры, знакомые с observability стеком, уложатся в 7 часов.

9. Связанные вопросы из базы знаний

10. Чек-лист самопроверки

• Я проверил, что каждый тип ошибки имеет конкретные признаки и пороги срабатывания алерта.
• В runbook указаны временные меры (workaround) и постоянные исправления — не только откаты.
• Настроенные алерты отправляют понятное сообщение, содержащее ссылку на runbook.
• Я протестировал хотя бы один сценарий симуляции и засек MTTD (должно быть ≤ 5 мин).
• Runbook находится в репозитории в директории docs/runbooks/, и на него ведёт ссылка из дашборда и из алертов.