Отладка агентных систем: диагностика сбоев и стратегии исправления

Таксономия сбоев агентных систем

Классифицируйте сбои по уровню возникновения:

Сбои модели:

• Галлюцинации: модель утверждает факты, не подтверждённые инструментами
• Неправильный выбор инструмента: модель вызывает не тот инструмент или с неверными параметрами
• Зависание в цикле: агент многократно вызывает один инструмент без прогресса
• Преждевременная остановка: агент отвечает, не выполнив все необходимые шаги

Сбои инструментов:

• Timeout: внешний сервис не отвечает вовремя
• Некорректные данные: инструмент возвращает неожиданный формат
• Ошибки авторизации: истёкшие токены или отозванные права
• Rate limiting: превышение лимитов внешних API

Сбои контекста:

• Context overflow: задача превысила размер окна контекста
• Context corruption: агент «забыл» ранее полученную информацию
• Prompt injection: входные данные содержат инструкции, переопределяющие системный промпт

Сбои координации (в MAS):

• Deadlock: агенты ожидают друг друга
• Conflicting decisions: агенты приняли противоречивые решения
• State inconsistency: разные агенты видят разное состояние системы

Инструменты диагностики

Эффективная диагностика невозможна без надлежащего логирования. Минимальный набор логов для каждого шага агента:

log_entry = {

    "timestamp": "...",

    "session_id": "...",

    "step": 3,

    "thought": "Нужно проверить наличие товара...",

    "action": {"tool": "check_inventory", "params": {"sku": "ABC123"}},

    "observation": {"success": True, "data": {"quantity": 0}},

    "tokens_used": 847,

    "latency_ms": 234

}

Для воспроизведения сбоев реализуйте session replay: сохраняйте все входные данные и состояния инструментов для возможности точного воспроизведения проблемной сессии.

Инструменты диагностики:

• LangSmith Debugger: визуализация цепочки вызовов, сравнение шагов
• IPython/Jupyter: интерактивный replay шагов агента
• pytest с мокированием инструментов: детерминированное воспроизведение сценариев

Диагностика и лечение галлюцинаций

Галлюцинации — наиболее коварный тип сбоев, потому что агент «уверенно» выдаёт неверную информацию. Диагностика: сравните утверждения агента с наблюдениями (Observations) в логах. Если утверждение не подтверждено ни одним наблюдением — это галлюцинация.

Стратегии снижения галлюцинаций:

1. Явная инструкция в промпте: «Отвечай только на основе информации, полученной от инструментов. Если данных недостаточно — скажи об этом явно»
2. Grounding check: добавьте шаг верификации, где агент должен привести источник (номер наблюдения) для каждого факта в ответе
3. Structured output с citations: требуйте от агента структурированный ответ, где каждый факт привязан к ID наблюдения
4. Temperature: снизьте temperature до 0 или 0.1 для задач, требующих точности фактов

Диагностика и устранение зависаний в цикле

Loop detection — обязательный компонент любого production-агента. Реализуйте его на уровне executor:

class LoopDetector:

    def __init__(self, max_repeats=3):

        self.action_history = []

        self.max_repeats = max_repeats

def check(self, action: dict) -> bool:

        action_key = f"{action['tool']}:{json.dumps(action['params'], sort_keys=True)}"

        recent = self.action_history[-self.max_repeats:]

        if action_key in recent and recent.count(action_key) >= self.max_repeats:

            return True  # Loop detected

        self.action_history.append(action_key)

        return False

При обнаружении цикла: прервите выполнение и передайте агенту специальный системный сигнал: «Обнаружен повторяющийся паттерн действий. Попробуй другой подход или сообщи пользователю о препятствии».

Причины циклов: несоответствие ожиданий агента и формата возврата инструмента, неверная инструкция в промпте, отсутствие инструмента для решения промежуточной задачи.

A/B-тестирование исправлений

Исправление сбоев агента (особенно изменение промптов) может неожиданно ухудшить другие сценарии. Обязательно тестируйте изменения на regression suite перед деплоем.

Минимальный процесс:

1. Сформируйте тестовый набор: 50+ задач, покрывающих основные сценарии использования
2. Запустите текущую версию агента на тестовом наборе, зафиксируйте baseline
3. Примените исправление
4. Запустите тот же набор, сравните с baseline по всем метрикам
5. Разрешайте деплой только если нет статистически значимой регрессии

Для быстрых итераций используйте кешированные ответы инструментов — это снижает стоимость тестового прогона в 10–100 раз.

Заключение

Систематический подход к отладке агентов строится на трёх принципах: детальное логирование каждого шага, классификация сбоев по уровню возникновения и верификация исправлений на regression suite. Инвестируйте в инфраструктуру отладки с первого дня разработки — retrospective debugging без достаточных логов крайне дорог и ненадёжен. Каждый обнаруженный сбой конвертируйте в автоматизированный тест для предотвращения регрессий.