Фраза агента «готово» должна опираться на проверенный исход операции. Ответ инструмента может означать принятие задания, прикладную ошибку внутри HTTP 200 или отсутствие подтверждения после тайм-аута. Разделите эти состояния в договоре инструмента. Начните с заглушки, которая возвращает явный отказ, и проверьте, какой статус сохраняет исполнитель.
Не поручайте модели угадывать успех по доброжелательному тексту. Адаптер возвращает структурированный результат, идентичность операции и допустимый следующий шаг. Если ответ не соответствует схеме, он не считается успешным автоматически. Проверка проводится на тестовом объекте без писем, платежей и иных реальных внешних изменений.
Уровни результата не сводятся к одному коду
| Уровень | Пример | Что известно |
|---|---|---|
| Транспорт | Сервер ответил | Связь состоялась, бизнес-исход ещё не установлен |
| Прикладной результат | Операция отклонена | Действие не принято по договору API |
| Выполнение | Задание ожидает обработки | Конечный результат пока отсутствует |
| Целевое состояние | Нужная версия объекта прочитана | Есть предусмотренное подтверждение результата |
RFC 9110 определяет 202 Accepted как принятие запроса к обработке без завершения обработки. Проверено 14 октября 2026 года. Конкретный API может вернуть идентификатор фоновой задачи; предусмотренный endpoint состояния и конечные статусы берутся из его документации. Принятие не является доказательством публикации, создания записи или доставки сообщения.
Договор результата сохраняет неизвестность
Условный ответ адаптера:
operation_id: <стабильный ID>
outcome: succeeded / failed / pending / unknown
external_object: <если подтверждён>
evidence: <тип проверенного подтверждения>
error_code: <без секретов>
next_step: inspect / wait / stop / continueHTTP 200 с полем прикладной ошибки разбирается по схеме конкретного сервиса. Строка «ошибка» в произвольном пользовательском тексте тоже не является универсальным критерием отказа. Валидация должна знать контракт, а не искать одно слово во всём ответе. Тело ответа и диагностические сведения ограничиваются безопасным необходимым набором.
После потери ответа действие могло выполниться. Unknown не переводится в failed только ради повтора. Сначала найдите исход прежней операции по поддерживаемому идентификатору или статусу. Если подтвердить нельзя, процесс выбирает предусмотренную паузу или разбор. Новый случайный ID при повторе способен создать ещё один объект.
Даже succeeded должен означать определённый уровень гарантии. Создание записи в очереди не равно обработке внешней системой, а отправка сообщения не равна прочтению человеком. В интерфейсе используйте формулировку, соответствующую подтверждению. Проверка результата не расширяет права агента на исправление чужого объекта.
Приёмка намеренно ломает успешную цепочку
- Вернуть прикладной отказ внутри HTTP-ответа.
- Вернуть pending и затем конечный результат.
- Потерять ответ после тестовой записи.
- Передать ответ неверной схемы.
- Проверить итоговый статус процесса и сообщение пользователю.
Для частично выполненной пакетной операции нужен отдельный договор: какие элементы завершены, какие отклонены и что можно повторять. Один общий флаг success скрывает неудачные строки. Итог агента перечисляет подтверждённый объём, не выдумывая завершение оставшихся элементов.
Сохраните обезличенные примеры ответов и ожидаемые переходы состояния как регрессионные тесты адаптера. Откат не должен пометить незавершённые операции успешными. Для разбора нужны схема результата, идентичность вызова и источник подтверждения. Критерий готовности прост: отказ остаётся отказом, ожидание видно, а «готово» появляется только на согласованном доказательстве.