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

Агент отличается от чат-бота тем, что сам выбирает шаги и вызывает инструменты. Поэтому требования к нему описывают не только то, что он делает, но и то, чего делать не имеет права. Ниже — структура спецификации и разбор частей, которые чаще всего забывают.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Курс «ИИ для аналитика»: тесты о требованиях к ИИ-системам
• Тема «Требования к ИИ-системам: агенты, guardrails, метрики»
• MCP: что это и как настроить аналитику
• ИИ и системный аналитик: что делать, чтобы не заменили
• Подписка: доступ ко всем тестам и темам

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

Частые вопросы