Агент прочитал первые 20 записей и решил, что проверил всё. Ошибка в контракте инструмента
Чтобы сократить контекст, результат инструмента часто обрезают: возвращают первые записи, сокращают длинные поля, убирают лишние детали. Но вместе с объёмом нельзя потерять главное: агент должен понимать, получил он полный результат или только его часть.
Пустой список и неполный список — разные ответы
Представим задачу: найти все неоплаченные счета клиента.
Инструмент возвращает первые 20 счетов. Среди них нет просроченных. Агент отвечает: «Просроченной задолженности нет».
Но подходящий счёт находится на следующей странице.
Это учебный сценарий, а не описание реального инцидента. Его удобно использовать как проверку контракта: достаточно ли информации получил агент, чтобы отличить «ничего не найдено» от «ещё не всё просмотрено»?
Я бы начал не с усиления промпта, а с формата ответа инструмента.
Ограничивать объём нужно, но явно
Фильтрация, пагинация и выбор нужных полей помогают не расходовать контекст на нерелевантные данные. Anthropic также рекомендует использовать эти механизмы для объёмных ответов инструментов. Однако наличие пагинации само по себе ещё не задаёт правило, когда задача считается завершённой. (anthropic.com)
Для задачи со счетами я бы предложил такой ответ:
{ "items": [ { "invoice_id": "inv_1042", "status": "overdue" } ], "coverage": { "complete": false, "returned": 1, "next_cursor": "opaque_cursor", "reason": "page_limit" } }
Здесь важны не названия полей, а их смысл:
- complete — завершён ли просмотр в пределах заданного запроса;
- returned — сколько записей находится в этом ответе;
- next_cursor — как продолжить;
- reason — почему результат неполный.
Если сервер не знает точного общего количества, я бы не добавлял выдуманный total. Для принятия решения полезнее честный признак неполноты.
Пустая страница не должна означать конец
Есть неприятный пограничный случай: страница пуста, но продолжение существует.
Например, сервер прочитал очередную порцию записей, применил дополнительный фильтр и не нашёл подходящих элементов. Следующая порция ещё не проверена.
По предлагаемому контракту такой ответ допустим:
{ "items": [], "coverage": { "complete": false, "returned": 0, "next_cursor": "next_page", "reason": "page_limit" } }
Поэтому условие завершения должно опираться на контракт, а не на привычное:
if not items: break
Для этого примера я бы разрешал окончательный отрицательный вывод только после complete=true.
Формулировки тоже стоит разделить:
«В просмотренной части просроченные счета не найдены».
И:
«Проверка завершена: просроченные счета не найдены».
Это разные обещания пользователю.
Проверить контракт можно до следующего вызова модели
Ниже — небольшой учебный валидатор. Он не реализует обход страниц и не проверяет правильность поиска. Его задача — отклонить противоречивое описание результата.
def validate_page(page): items = page["items"] coverage = page["coverage"] if not isinstance(items, list): raise ValueError("items must be a list") complete = coverage["complete"] cursor = coverage.get("next_cursor") if type(complete) is not bool: raise ValueError("complete must be boolean") if type(coverage["returned"]) is not int: raise ValueError("returned must be integer") if coverage["returned"] != len(items): raise ValueError("returned count mismatch") if complete and cursor is not None: raise ValueError("complete result has a cursor") if not complete: if not isinstance(cursor, str) or not cursor: raise ValueError("incomplete result needs a cursor")
В этом варианте неполный результат обязательно должен позволять продолжение. Если ваш инструмент может завершиться частичным ответом без возможности продолжить, ему нужно отдельное состояние — например, partial_unrecoverable. Не стоит маскировать его под обычную страницу.
Где лучше убрать работу у агента
Для запроса «покажи несколько последних счетов» достаточно одной страницы.
Для запроса «найди все просроченные счета» я бы сначала рассмотрел серверный фильтр:
list_invoices( customer_id=..., status="overdue" )
А если пользователю нужна только сумма задолженности — отдельную агрегирующую операцию.
Так агенту не приходится переносить все счета через контекст ради одного числа. Идея возвращать релевантную информацию вместо полного массива также соответствует рекомендациям Anthropic по проектированию инструментов. (anthropic.com)
Но здесь есть архитектурный выбор: специализированные операции упрощают типовые задачи, зато требуют поддерживать дополнительные серверные контракты. Универсальный поиск гибче, однако больше ответственности остаётся у вызывающей стороны.
Бюджет закончился — проверка не завершилась
В предлагаемой реализации я бы ограничил число страниц и общее время обхода.
Однако достижение лимита не должно превращать частичный результат в полный.
Если удалось проверить только часть данных, итог должен содержать:
- что уже найдено;
- что проверка не завершена;
- почему она остановилась;
- можно ли её продолжить.
Ограниченный бюджет — нормальное состояние системы. Уверенное «проверено всё» при незавершённом обходе — уже ошибка контракта.
Что проверить перед внедрением
Я бы добавил в тестовый набор пять случаев:
- Нужная запись находится только на второй странице.
- Первая страница пустая, но содержит продолжение.
- Источник повторно возвращает тот же курсор.
- Лимит обхода достигнут до завершения.
- Последняя страница корректно сообщает complete=true.
Отдельно стоит определить поведение при изменении данных между страницами. Для строгой проверки «всех записей» может понадобиться снимок или зафиксированная верхняя граница выборки. Просто наличие курсора не стоит считать обещанием неизменности набора.
Вывод
Я бы экономил контекст через фильтры, выбор полей и серверные агрегаты. Но признак полноты оставлял бы обязательной частью ответа.
«Ничего не найдено» — вывод о проверенных данных. «Больше проверять нечего» — отдельный факт, который должен подтвердить инструмент.
А ваши агенты явно различают полный и частичный результат — или окончательный ответ зависит от того, заметит ли модель поле с курсором?