Восстановление после сбоев инструментов в агентных системах¶

Ошибки инструментов редко заканчиваются простым error. Чаще команда сталкивается с более неприятными состояниями:

неизвестно, был ли побочный эффект;
частичный успех;
устаревшая сверка состояния;
повторный вызов, который уже опаснее исходной ошибки.

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

1. Почему восстановление после сбоя инструмента это отдельный слой¶

Когда путь выполнения ломается, команда обычно хочет “просто повторить”. Но у инструментов разные последствия:

читающий инструмент можно повторить безопаснее;
записывающий инструмент может создать дубль;
соединитель может успеть выполнить действие, но не вернуть подтверждение;
внешняя система может оказаться в промежуточном состоянии.

Именно поэтому логика восстановления должна быть частью слоя контрактов.

2. Какие классы исходов полезно различать¶

Минимально полезная классификация выглядит так:

success
retryable_failure
validation_failure
permission_failure
side_effect_unknown
partial_side_effect
manual_reconciliation_required

Если слой выполнения не различает эти классы, агент почти неизбежно начинает принимать слишком грубые решения о восстановлении.

3. Что делать с `side_effect_unknown`¶

Это самый неприятный класс отказов.

Канонические сценарии восстановления

Ветка восстановления должна различать поверхности отказа для трех канонических сценариев. Триаж обращений поддержки фокусируется на side_effect_unknown, поиске по ключу идемпотентности, предотвращении дубля тикета, ручной сверке и регрессии оценки/поэтапного выпуска. Внутренний ассистент знаний фокусируется на устаревшем поиске, сбое поиска источника, восстановлении после отказа доступа, откате записи в память и повторной проверке обоснованного ответа. Координация инцидентов фокусируется на частичной доставке уведомлений, повторе эскалации, исправлении передачи владельца, решении об экстренном откате и фиксации обучения после инцидента.

Вместо наивного повтора обычно полезнее:

проверить текущее состояние во внешней системе;
найти объект по ключу идемпотентности;
перевести возможность во временный ограниченный режим;
запросить проверку человеком;
зафиксировать неопределенность в трассе и записи об инциденте.

Главная цель: не умножать побочные эффекты, пока состояние не восстановлено.

4. Что делать с `partial_side_effect`¶

Здесь система уже изменила внешний мир, но не дошла до чистого завершения.

Полезные стратегии:

компенсирующее действие, если оно допустимо;
явный шаг сверки состояния;
остановка с явным показом частичного завершения;
отдельная последующая задача вместо тихого повтора.

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

5. Когда восстановление должно требовать человека¶

Шлюз человеческого подтверждения особенно полезен, если:

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

То есть проверка человеком нужна не только для исходного действия, но и для некоторых путей восстановления.

6. Какие поля полезно хранить в контракте инструмента¶

Качество восстановления сильно зависит от того, что знает слой выполнения о контракте инструмента.

Минимально полезны такие поля:

idempotent
retry_on
reconcile_on_unknown
requires_manual_recovery
compensating_action
external_lookup_key

Без этого решения о восстановлении часто становятся ситуативными.

7. Что проверять в трассах¶

Во время проверки восстановления полезно быстро увидеть:

какой статус вернул инструмент;
был ли повтор;
какой ключ идемпотентности использовался;
делалась ли сверка состояния;
какая полезная нагрузка реально пошла в записывающий путь;
кто принял окончательное решение о восстановлении.

Если эти вещи не видны в трассах, инциденты восстановления будут расследоваться слишком долго.

8. Как это связано с оценками¶

Восстановление после сбоя инструмента полезно явно проверять в наборе оценочных данных:

тайм-аут после записи;
разрыв соединения после фиксации действия;
попытка повторного дубля;
частичный успех, требующий следующего шага;
ручное подтверждение для пути восстановления.

Это особенно важно потому, что многие тяжелые производственные инциденты происходят не на счастливом пути, а именно в ветке восстановления.

9. Что сделать сразу¶

Сначала пройди по короткому списку и отдельно отметь все ответы «нет»:

Различает ли слой выполнения retryable_failure и side_effect_unknown?
Есть ли явный путь восстановления для partial_side_effect?
Видно ли в трассах, какое решение о восстановлении было принято?
Есть ли инструменты, где повтор запрещен по умолчанию?
Есть ли сценарии ветки восстановления в наборе оценочных данных?
Может ли опасный путь восстановления требовать проверки человеком?