Чем спецификация агента отличается от обычного ТЗ?

Обычное ТЗ описывает последовательность действий, спецификация агента — рамку: цель, инструменты, запреты и поведение при неудаче. Путь к результату агент выбирает сам, поэтому важно ограничить пространство решений.

Сколько кейсов нужно для проверки?

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

Нужно ли писать в требованиях про промпт?

Промпт — часть реализации, а не требование. В спецификации важны роль, границы и метрики; как именно это сформулировано в инструкции, решает разработчик и аналитик вместе.

Кто отвечает за ошибку агента?

Человек и организация, которая систему запустила. Поэтому в требованиях фиксируют подтверждения, журнал и запреты: они переводят ответственность из плоскости «модель ошиблась» в проверяемый процесс.

Что делать, если заказчик не хочет ограничений?

Показать цену ошибки на примерах: отправка неверных данных клиенту, изменение записи без подтверждения. Разговор из «можно или нельзя» переходит в «какие решения и с какой ценой ошибки мы готовы автоматизировать».

Требования к ИИ-агенту: спецификация, guardrails, метрики

Чем агент отличается от обычной интеграции

Интеграция выполняет заранее заданную последовательность: пришло событие — вызвался метод. Агент сам решает, какие шаги сделать и какие инструменты вызвать, чтобы дойти до цели. Это даёт гибкость и создаёт новую категорию рисков.

Главное следствие для требований: нельзя описать поведение только списком шагов. Нужно описать цель, доступные средства и ограничения — то есть рамку, внутри которой агент действует сам.

Вторая особенность — недетерминированность: один и тот же запрос может привести к разным путям. Значит, приёмка строится на наборе сценариев, а не на одном демонстрационном примере.

Интеграция повторяет сценарий, агент выбирает шаги сам.
Описываем рамку: цель, инструменты, границы, отказ.
Приёмка — по набору сценариев, а не по одному показу.

Структура спецификации агента

Рабочий минимум — восемь разделов: роль, цель, входные данные, доступные инструменты, границы полномочий, поведение при отказе, точки участия человека, метрики качества.

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

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

Роль, цель, входы, инструменты, границы, отказ, человек в контуре, метрики.
Цель — результат, а не действие.
У каждого инструмента указаны права и лимиты.

Границы полномочий: что агент не имеет права делать

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

Формулируйте запрет проверяемо: «агент не вызывает инструменты записи» лучше, чем «агент действует осторожно». Проверяемое ограничение можно протестировать, а вежливое пожелание — нет.

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

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

Поведение при отказе

Отказ — это сценарий, а не сбой. Требование должно описывать, что делает агент, если данных мало, инструмент недоступен, запрос противоречив или выходит за границы роли.

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

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

Отказ описывается как отдельный сценарий.
Сообщение пользователю: чего не хватает и что делать дальше.
Лимит попыток и стоимости на одну задачу.

Человек в контуре

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

Подтверждение должно быть осмысленным: человеку показывают, что именно произойдёт, с какими данными и что будет после. Кнопка «согласен» без контекста создаёт иллюзию контроля.

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

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

Guardrails: ограничения в работе

Guardrails — технические и процессные ограничения: запрет на вызов опасных инструментов, фильтрация вывода, лимиты по времени и стоимости, проверка того, что ответ опирается на разрешённые источники.

Опасность, которую учитывают в первую очередь, — внедрение инструкций через данные. Если агент читает письма, страницы или задачи, в них может оказаться текст, который модель примет за указание. Поэтому в спецификации фиксируют, какие источники считаются доверенными, а какие — только данными.

Список типовых рисков LLM-приложений удобно брать из отраслевых подборок, например OWASP: там перечислены внедрение инструкций, утечка данных, небезопасный вывод и избыточные права.

Ограничения: запреты, лимиты, фильтрация вывода.
Доверенные источники отделены от недоверенных данных.
Типовые риски берём из отраслевых подборок, а не придумываем заново.

Метрики для недетерминированной системы

Поскольку ответы не повторяются, качество измеряют на наборе сценариев: 20–50 реальных кейсов с ожидаемым результатом. После каждого изменения (промпт, модель, инструменты) набор прогоняют и сравнивают результат с предыдущим.

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

Приёмка формулируется числами: например, «на наборе из 30 кейсов не меньше 27 верных результатов и ни одного случая записи без подтверждения». Такое требование можно проверить, в отличие от «агент работает качественно».

Набор кейсов с ожидаемым результатом — база приёмки.
Метрики: верность, отказы, правки, стоимость, время.
Числа в требованиях вместо общих слов о качестве.

Шаблон спецификации

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

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

И перечитывайте её при каждом изменении инструментов: список прав устаревает быстрее, чем кажется.

Восемь разделов: роль, цель, входы, инструменты, запреты, отказ, человек, метрики.
Спецификация — в текстовом файле с историей изменений.
Пересматриваем при изменении инструментов и прав.

Что сделать: короткий чеклист

Описана роль агента и цель как результат, а не как действие.
Перечислены инструменты с правами и лимитами по каждому.
Сформулированы проверяемые запреты.
Описано поведение при отказе и лимит попыток.
Указаны точки подтверждения человеком и что именно он видит.
Определены доверенные и недоверенные источники данных.
Собраны 20–50 кейсов с ожидаемым результатом для приёмки.
Метрики записаны числами, а не словами «качественно».

Где тренировать

Темы из гайда разобраны в тестах портала — каждый вопрос с объяснением ответа:

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

Требования к ИИ-агенту: спецификация, guardrails и метрики