Хорошая системная инструкция для AI-агента описывает рабочий процесс: цель, последовательность действий, доступные инструменты, правила обработки ошибок и формат результата. Формулировки вроде «будь полезным» или «проанализируй данные» задают направление, но оставляют слишком много решений на усмотрение модели.
Устойчивая инструкция отвечает на пять вопросов: какую задачу решает агент, какие шаги выполняет, где получает данные, что делает при сбое или нехватке информации и как оформляет ответ. Такой подход упрощает поддержку промпта и помогает пережить изменение сценариев без полного переписывания правил.
Ниже разобраны восемь правил: сначала карта бизнес-процесса и границы ответственности, затем инструменты, ошибки, проверка чисел, формат ответа, примеры, сокращение промпта и тестирование.
Как писать инструкции для AI-агента: начните с рабочего процесса
Системная инструкция должна работать как спецификация процесса. В ней фиксируют действия агента и условия перехода между ними, а не набор общих пожеланий.
Что должна объяснять хорошая системная инструкция
Минимальная инструкция описывает пять элементов:
- Цель. Какую задачу решает агент и какой результат нужен пользователю.
- Входные данные. Что сообщает пользователь, какие поля обязательны и что агент должен запросить дополнительно.
- Действия. Какие шаги выполняются, в каком порядке и при каких условиях вызывается инструмент.
- Ошибки и неопределенность. Как поступать при пустом ответе, конфликте источников, недоступном API или неполных данных.
- Формат ответа. Что показать сначала, когда использовать таблицу, какие ограничения и источники указать.
Конкретика важнее объема. Правило «проверь данные перед расчетом» слабее инструкции «перед каждым агрегированным показателем проверь выбросы, единицы измерения и актуальность строк; подозрительные записи исключи из расчета или явно пометь как искажающие результат».
Почему общие формулировки не заменяют правила
Запрос «проанализируй данные» не определяет ни источник, ни порядок действий, ни критерий корректности. Один ответ может содержать краткий вывод, другой превратится в пересказ всех строк, а третий будет построен на аномальном значении.
Операционное описание выглядит точнее: получить данные из указанного источника, проверить обязательные поля, найти выбросы, пометить или исключить проблемные строки, выполнить расчет на очищенном наборе и показать пользователю вывод с доказательствами.
Такая запись задает агенту маршрут и условия остановки. Модель получает меньше пространства для случайных интерпретаций, а разработчик видит, какой этап нужно изменить при появлении нового сценария.
Правило 1. Опишите карту бизнес-процесса до написания промпта
Начинайте с карты процесса, а системную инструкцию пишите после нее. Карта помогает отделить цель агента от деталей конкретного API, базы знаний или интерфейса.
Разделите процесс на вход, действия и результат
Для каждого сценария зафиксируйте:
- что передает пользователь;
- каких данных не хватает для старта;
- какие источники использует агент;
- какие операции выполняет после получения данных;
- в какой момент требуется уточнение или подтверждение;
- какой результат возвращается пользователю.
Например, для аналитического агента цепочка может выглядеть так: получить категорию и период, проверить наличие токена, запросить данные через API, проверить пустые поля и аномалии, посчитать показатели, сравнить несколько сущностей, вернуть краткий вывод и таблицу с ограничениями.
У каждой операции должен быть понятный вход и ожидаемый результат. Если агент получает список товаров, инструкция должна уточнять, какие поля обязательны: идентификатор, название, цена, единица измерения, дата обновления. Иначе модель может продолжить расчет по неполному набору.
Зафиксируйте границы ответственности агента
Опишите, что агент решает самостоятельно, когда задает вопрос и какие действия ему запрещены. Например, агент может выбрать подходящий запрос к API, но обязан запросить уточнение при двух разных трактовках названия категории. Он может пометить подозрительную цену, но не должен объявлять ее достоверной без проверки.
Границы нужны и для операций записи. Для действий с побочным эффектом задайте отдельное подтверждение пользователя, минимальные права и понятный способ проверки результата. Подход к подтверждениям и распределению риска подробно разобран в статье о human-in-the-loop для AI-агента.
Карта процесса должна содержать условия остановки: отсутствует обязательное поле, источник недоступен, ответ не соответствует схеме или результат нельзя проверить. Это защищает сценарий от бесконечных попыток и правдоподобных догадок.
Правило 2. Описывайте инструменты и базы знаний как рабочие контракты
Перечня доступных инструментов недостаточно. Агенту нужно понимать назначение каждого инструмента, условия вызова и ограничения полученного результата.
Укажите, когда и зачем использовать каждый инструмент
Для каждого API, скрипта, поискового индекса или базы знаний опишите:
- какую задачу решает инструмент;
- какие параметры принимает;
- какие поля обязательны;
- какой формат ответа возвращает;
- какие коды ошибок возможны;
- какие действуют лимиты и ограничения;
- в каких случаях инструмент использовать нельзя.
Поиск в базе знаний нужен для получения документов и терминов. API возвращает структурированные данные из конкретной системы. Расчет на уже полученном наборе не требует нового вызова, если инструкция не указывает обратное. Такое разделение снижает число лишних обращений и помогает выбрать правильный источник.
Если для работы с API предусмотрены готовые shell scripts, укажите их назначение и порядок запуска. Агенту проще использовать проверенный скрипт с готовой обработкой заголовков и кодов ответа, чем каждый раз собирать HTTP-запрос вручную.
Опишите авторизацию и отсутствие токена
Секреты нужно описывать как часть рабочего сценария. Зафиксируйте, где агент ищет токен, какие переменные окружения имеет приоритет и как проверяет доступ до первого запроса. Внутренние правила скрипта могут задавать загрузку токена из переменной окружения с возможностью переопределения значения из файла.
Отсутствие токена должно приводить к конкретному действию. Для сценария с API можно задать ровно два варианта:
- пользователь отправляет токен в чате;
- агент создает файл и вставляет токен в блок API token.
После выбора варианта агент продолжает работу только после получения секрета. Молчаливый переход к выдуманным данным или бесконечные повторы запроса ломают предсказуемость процесса.
Отделите описание источника от интерпретации данных
Корректный HTTP-код и заполненная строка еще не доказывают, что значение подходит для бизнес-задачи. API может вернуть устаревшую запись, неправильную единицу измерения или ошибку поставщика.
В инструкции разделите два этапа: получить ответ по API contract и проверить смысл данных. В API contract хранят технические детали: базовый URL, параметры, заголовки авторизации, коды ответа, лимиты и схему результата. В системной инструкции задают правила выбора источника, проверки и интерпретации.
Для интеграций с таск-трекерами полезны отдельные ограничения на чтение и запись, защиту токенов, повторные запросы после timeout и проверку результата после мутации. Практический пример такой схемы есть в разборе безопасного подключения AI-агента к таск-трекеру.
Правило 3. Заранее задайте сценарии ошибок и неопределенности
Ошибки нужно проектировать до запуска агента. Иначе модель начнет заполнять пробелы предположениями или повторять неудачный вызов без понятного предела.
Что агент должен делать, если данных недостаточно
Инструкция должна запрещать додумывать отсутствующие значения. Агент сообщает, какого поля или документа не хватает, объясняет влияние пробела и перечисляет данные, необходимые для продолжения.
Отсутствие данных и противоречие между источниками требуют разных действий. При пустом ответе агент может проверить параметры запроса или сообщить, что источник не вернул записи. При конфликте источников он показывает расхождение и использует заранее заданный приоритет, если такой приоритет существует.
Отдельно опишите неоднозначный запрос. Например, при совпадении названий товара в нескольких категориях агент должен запросить категорию или идентификатор, а не выбирать первый результат.
Ограничьте повторные попытки и эскалацию
Для каждого инструмента задайте допустимое число повторов и условия повторного вызова. Один повтор может быть оправдан при временной сетевой ошибке. Повторять запрос после ошибки авторизации бессмысленно, пока не изменились учетные данные.
После исчерпания попыток агент возвращает понятное сообщение: какой инструмент недоступен, на каком шаге произошел сбой и можно ли продолжить вручную. Искусственный результат в такой ситуации опаснее короткого отказа.
Для операций записи добавьте подтверждение перед изменением данных, проверку результата и отдельное поведение при timeout. Подтверждение не должно превращаться в автоматическую формальность: его связывают с риском и возможным масштабом последствий.
Правило 4. Добавьте sanity-check для чисел и аномалий
AI-агент может без колебаний повторить значение, которое технически присутствует в ответе API, но не соответствует контексту. Поэтому проверка качества должна выполняться перед любым важным числом и агрегированным выводом.
Как описать аномалию в инструкции
Операционное правило состоит из трех частей: признак, действие и коммуникация.
- Признак: значение примерно более чем в 10 раз отклоняется от типичного уровня категории или конфликтует с единицей измерения.
- Действие: проверить строку, сравнить связанные поля и решить, включать ли ее в расчет.
- Коммуникация: показать аномалию, назвать вероятную причину и объяснить ее влияние на результат.
Порог в 10 раз подходит как иллюстрация для некоторых товарных категорий, но не универсален. Для лекарств, недвижимости, промышленного оборудования и других областей нужны собственные диапазоны и правила.
Цена салфеток 500 000 рублей за штуку, чехла 50 рублей или холодильника 200 рублей может указывать на ошибку ценника, несоответствие единиц или технический плейсхолдер. Агент не должен сразу считать такие значения фактом.
Почему вывод должен строиться на cleaned data
Sanity-check не приносит пользы, если агент показывает предупреждение, но оставляет аномальную строку в среднем значении. После проверки нужно выбрать действие:
- исключить строку из агрегатов;
- оставить ее, но явно указать, что расчет искажен;
- остановить анализ и запросить подтверждение, если решение зависит от этой записи.
Итоговый вывод должен опираться на cleaned data, то есть на набор после исключения или маркировки проблемных значений. Пользователь должен видеть разницу между исходными данными, обнаруженной аномалией и расчетом, который использован для вывода.
Правило 5. Явно опишите формат ответа и порядок подачи информации
Формат ответа нужно задать заранее. Иначе агент может вернуть длинный журнал действий, сырой JSON или набор цифр без интерпретации.
Сначала вывод, затем подтверждающие данные
Для аналитического сценария задайте порядок:
- краткий ответ на вопрос пользователя;
- ключевые значения и сравнения;
- таблица или другой компактный способ сопоставления;
- методика расчета и использованные данные;
- аномалии, ограничения и условия, влияющие на результат.
Первые строки должны отвечать на задачу. Подробности нужны для проверки и принятия решения, но их не следует смешивать с главным выводом.
Когда использовать текст, таблицу и график
Текст подходит для интерпретации и рекомендации. Таблица удобна для сравнения нескольких товаров, категорий, периодов или сегментов. График нужен для трендов, сегментации и сравнений во времени, если среда поддерживает визуализацию.
Если график недоступен, верните компактное структурированное описание с периодами, значениями и направлением изменения. Сырой JSON оставляйте для машинного обмена или отладки. Финальный ответ для человека должен объяснять смысл чисел.
Правило 6. Подкрепляйте правила короткими примерами
Пример фиксирует поведение модели лучше, чем длинное объяснение абстрактного принципа. Хороший образец показывает вход, ключевое действие и ожидаемый результат.
Пример нормального аналитического ответа
В инструкции можно задать такую структуру:
Вывод: категория A выросла за выбранный период, категория B снизилась.
Сравнение:
| Категория | Период 1 | Период 2 | Изменение |
Пояснение: расчет выполнен по очищенным данным после проверки пропусков и выбросов.
Ограничения: часть строк не содержит даты обновления.Здесь нет вымышленных цифр, но понятны порядок подачи и состав ответа: сначала решение, затем сравнение, объяснение расчета и ограничения.
Пример поведения при проблемной строке
Для подозрительной цены инструкция может требовать следующую последовательность:
- показать строку с ценой 500 000 рублей за штуку;
- объяснить, что значение похоже на ошибку ценника или несоответствие единиц;
- указать, влияет ли строка на среднее и другие агрегаты;
- исключить запись из расчета либо запросить подтверждение;
- сформулировать вывод на очищенных данных.
Пограничные примеры особенно полезны для токенов, пустых ответов API, конфликтующих источников и операций записи. Они показывают, где агент должен остановиться, а не продолжать сценарий по инерции.
Проблемы документации и неоднозначных терминов подробно разобраны в статье о влиянии документации на ответы AI-чатов. Тот же принцип применим к системным инструкциям: проверять нужно не красивый пример, а соблюдение правил в разных условиях.
Правило 7. Уберите из промпта лишний текст и сложную логику
Длинный промпт не гарантирует надежное поведение. Повторы расходуют контекст, усложняют поиск противоречий и увеличивают стоимость поддержки.
Что стоит оставить в системной инструкции
В системной инструкции должны остаться:
- цель агента;
- границы ответственности;
- порядок действий;
- правила выбора инструментов;
- обработка ошибок;
- проверки качества данных;
- формат ответа;
- несколько коротких примеров для нормальных и пограничных сценариев.
Часто меняющиеся параметры лучше хранить в конфигурации или технической документации. Это касается URL окружения, лимитов, названий полей, версий схемы и списков доступных категорий.
Как не превратить инструкцию в набор исключений
Группируйте правила по этапам процесса: вход, получение данных, проверка, расчет, ответ и остановка. Близкие исключения объединяйте. Если правила конфликтуют, задайте приоритет явно: например, безопасность и запрет выдумывать данные имеют приоритет над стремлением дать полный ответ.
Сложную бизнес-логику надежнее вынести в код, валидатор или отдельный инструмент. Промпт должен объяснять, когда вызвать этот компонент и как интерпретировать его результат. Текстовая инструкция плохо подходит для десятков вложенных условий, особенно если правила меняются каждую неделю.
После редактирования проверьте каждое правило вопросом: какое действие оно меняет? Если ответ неясен, формулировка, вероятно, служит пояснением для человека, а не рабочим ограничением агента.
Правило 8. Проверьте инструкцию на реальных и пограничных сценариях
Инструкция считается готовой после проверки поведения агента, а не после вычитки текста. Тесты должны охватывать обычные запросы, ошибки и необычные значения.
Минимальный чек-лист перед запуском агента
- Понятна ли цель агента?
- Перечислены ли обязательные входы и ожидаемые выходы?
- Описаны ли инструменты, параметры, авторизация, коды ошибок и лимиты?
- Есть ли отдельные сценарии для отсутствующего токена, пустого ответа и недоступного API?
- Запрещено ли агенту додумывать отсутствующие значения?
- Выполняется ли sanity-check для выбросов, единиц и устаревших строк?
- Строится ли вывод на cleaned data?
- Задан ли порядок: вывод, доказательства, ограничения?
- Использует ли агент таблицу для сравнения и график для трендов, когда это уместно?
- Нет ли повторов, противоречий и необъяснимых исключений?
Прогоните минимум семь сценариев: корректные данные, отсутствующий токен, пустой ответ API, неоднозначный запрос, аномальное значение, сравнение нескольких сущностей и недоступный инструмент. Проверяйте текст ответа, последовательность вызовов, условия остановки и использование очищенного набора.
Какие признаки говорят, что инструкцию пора переписать
Поводом для пересмотра служат повторяющиеся сбои:
- агент по-разному обрабатывает одинаковые запросы;
- игнорирует подходящий инструмент или вызывает его без причины;
- показывает аномальные числа без предупреждения;
- выдает raw JSON вместо интерпретации;
- застревает на ошибке авторизации или сетевом сбое;
- продолжает расчет при неполных данных;
- после изменения сценария нарушает формат ответа;
- требует все больше частных исключений.
При каждом изменении API, схемы данных или бизнес-процесса обновляйте инструкцию и повторяйте пограничные тесты. Версия инструкции должна быть связана с набором тестовых сценариев, иначе трудно понять, какое изменение вызвало регрессию.
Итог: инструкция для AI-агента как поддерживаемая спецификация
Рабочая инструкция начинается с карты процесса и заканчивается проверкой на реальных сценариях. Внутри нее должны быть границы ответственности, контракты инструментов, правила авторизации, fallback-поведение, sanity-check, формат ответа и короткие примеры.
Короткая формула хорошей инструкции
Цель и процесс + инструменты и данные + ошибки и проверки + формат и примеры + тестирование и регулярное упрощение.
Качество промпта определяется количеством однозначных действий и условий остановки. Лишние объяснения не заменяют отсутствующий шаг, а длинный список исключений не исправляет плохо описанный бизнес-процесс. Начните с карты входов, операций и результата, затем добавьте контракты источников, проверки данных и тесты для пограничных случаев.