Обработка ошибок инструментов и частичных результатов в цикле агента

Что это такое

Трём исходам нужны три разных результата. Ошибка протокола (неизвестный инструмент, неверные аргументы, недоступный сервер) означает сбой самого вызова; Model Context Protocol сообщает о таких случаях как об ошибках JSON-RPC. Ошибка выполнения инструмента (вышестоящий API вернул 500, файл не существует, истекло время ожидания запроса) — это допустимый результат, сообщающий, что операция не удалась; MCP возвращает его с isError: true, а документация поставщика по использованию инструментов описывает эквивалентный флаг is_error: true в блоке tool_result, после чего модель учитывает ошибку на следующем шаге. Частичный результат (обработано 7 из 10 файлов, получена первая страница поиска, в пакете отклонены две строки) — это успех, в содержимом которого обязательно должно быть указано, чего не хватает.

Почему это важно

Агент действует на основании результата инструмента. Исключение, о котором модель не узнала, приводит к уверенному ответу без всяких оснований. Ошибка без подробностей приводит к слепым повторам того же вызова. Частичный результат, представленный как полный, приводит к отметке о завершении задачи при незаметной потере строк.

Как применять

• Не допускайте выхода исключения за пределы инструмента; перехватывайте его и возвращайте результат с устойчивым типом ошибки, сообщением и, если известно, указанием, может ли помочь повторная попытка (при 404 — нет, при тайм-ауте — да).
• При частичном результате возвращайте успешную часть вместе с явным списком того, что не удалось и почему, а также курсор или идентификатор для продолжения.
• Текст ошибки должен быть коротким и фактическим; без трассировок стека и вывода вышестоящей системы, который может содержать внедрённые инструкции.
• Ограничивайте повторы в самом цикле, а не инструкцией: после ошибки один и тот же инструмент с теми же аргументами можно вызвать фиксированное число раз, затем цикл возвращает управление с кратким отчётом.
• Делайте инструменты записи идемпотентными или снабжайте их ключом идемпотентности, чтобы повтор после сбоя с неоднозначным исходом не дублировал эффект.
• Различайте «результатов нет» и «ошибка»: пустая поисковая выдача — допустимый полный результат.
• Записывайте каждый результат с ошибкой в журнал вместе с идентификатором запуска; характер ошибок служит отчётом об удобстве использования инструмента.

Типичные ошибки

Возврат null или пустой строки при сбое. Замена всех ошибок одним общим сообщением. Передача модели решения о количестве повторов. Ошибка протокола в ответ на бизнес-условие («заказ не найден» — это результат, а не некорректный вызов). Отражение частичных результатов только в журнале, которого модель не видит.