Структурированные ответы об ошибках для MCP-инструментов

Суть

Общая ошибка («Operation failed») — глухая стена: агент не может рассудить, как восстанавливаться. Структурированная ошибка несёт категорию (transient/validation/business/permission), флаг повторяемости (isRetryable) и человекочитаемое сообщение.

Пустой результат — не ошибка

Пустой результат успешного запроса — это успех, а не ошибка; пометка isError: true сбивает логику решений агента и плодит лишние повторы. Нарушения бизнес-правил не повторяемы (isRetryable: false) — иначе бесконечный цикл повторов. Частичные результаты упавшей операции ценны: их стоит включить в partialResults.

Структурированный ответ об ошибке MCP

{
  "isError": true,
  "errorCategory": "transient",
  "isRetryable": true,
  "message": "Сервис заказов превысил тайм-аут. Повтор безопасен.",
  "attemptedQuery": "order_id: ORD-8821",
  "partialResults": null
}

Anti-patterns

Ловушка	Почему не работает	Верный паттерн
Возвращать общий статус «Operation failed»	Скрывает тип сбоя и повторяемость — агент не решит, что делать	Вернуть `errorCategory` + `isRetryable` + описательное сообщение
Возвращать `isError: true` на пустой результат	Пустой результат валидного запроса — успех, не ошибка; провоцирует повторы	Успех с пустым массивом; `isError` — только для реальных сбоев
Субагент рушит весь процесс при тайм-ауте	Уничтожает всю проделанную работу; у координатора могли быть стратегии	Сначала локальный повтор; иначе структурированная ошибка + частичные результаты
Помечать нарушение бизнес-правила повторяемым	Бесконечные повторы — правило не «разрешится» при повторе	`isRetryable: false` + понятное клиенту сообщение

Exam traps

Ловушка	Почему не работает	Верный паттерн
Считать общий статус достаточным для восстановления	Агент не поймёт, есть ли смысл в повторе — зациклится или зависнет	Каждая ошибка несёт категорию, повторяемость и контекст
Трактовать пустой результат как состояние ошибки	Портит сигнал, по которому координатор решает продолжать	Успех с пустым массивом — валидное завершение

Практическое задание (T2)

Transient: тайм-аут 5с возвращает повторяемую ошибку с запросом и любыми частичными результатами.
Validation: отсутствующий/неверный order_id — неповторяемая ошибка с указанием конкретного поля.
Business: возврат >$500 — неповторяемая ошибка с понятным клиенту объяснением политики.
Permission: истёкший токен — структурированная ошибка, ведущая координатор к повторной аутентификации.
Empty: клиент без заказов — успех с пустым массивом, НЕ ошибка.

Проверка знаний

Многоагентная исследовательская система

Поисковый субагент упал по тайм-ауту на сложной теме. Как организовать возврат сбоя координатору для разумного восстановления?

A Вернуть структурированный контекст ошибки: тип сбоя, запрос, частичные результаты, возможные альтернативы
B Внутри субагента повторять с экспоненциальной паузой; после исчерпания — общий статус «search unavailable»
C Поймать тайм-аут и вернуть пустой результат как успешный
D Пробросить исключение тайм-аута наверх и завершить весь процесс исследования

Агент поддержки клиентов

process_refund вызван на $750 при лимите $500; инструмент вернул {"error": "Operation failed"}. Агент повторяет 4 раза и зависает. Что исправить?

A Добавить лимит повторов — стоп после 3 попыток независимо от типа ошибки
B Вернуть {"isError": true, "errorCategory": "business", "isRetryable": false, "message": "Сумма возврата превышает лимит $500. Нужно одобрение менеджера."}
C Вернуть {"isError": true, "errorCategory": "validation", "isRetryable": true}, сигнализируя о коррекции ввода
D Инструкция в system prompt: «не повторять вызовы возврата более двух раз»

Агент поддержки клиентов

search_orders возвращает {"isError": true, "message": "No orders found"}, когда у клиента нет истории заказов. Координатор повторяет, считая сбой временным. Причина и решение?

A Логика повторов координатора неверна — искать «No orders found» в строке сообщения
B Инструмент ошибочно возвращает isError: true на пустой результат — пустой результат валиден; нужно вернуть успех с пустым массивом
C Добавить isRetryable: false, чтобы координатор перестал повторять
D Инструкция в system prompt не повторять, когда заказов нет