Промпты для ИИ-агентов: инструкции, инструменты и рабочие процессы

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

Рабочий процесс или агент

Сначала решите, нужен ли вам агент вообще.

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

Части промпта агента

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

1. Системный промпт

Охватите шесть вещей.

Роль и цель. Для чего нужен агент, в двух предложениях.

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

Границы. Чего он не должен делать и что требует подтверждения.

Как обрабатывать проблемы. Ошибки инструментов, отсутствующая информация, неоднозначность.

Когда останавливаться. Условие, означающее, что задача выполнена, и предел усилий.

Как отчитываться. Что содержит итоговый ответ.

You are a coding agent working in the user's repository.

## How to work
- Read the relevant files before proposing a change.
- Make the smallest change that satisfies the task.
- After editing, run the tests that cover the change.

## Boundaries
- Do not modify files outside the repository.
- Do not delete files or run destructive commands without asking.
- Do not change public interfaces unless the task says so.

## When things go wrong
- If a command fails, read the error and try a different approach once.
  If it fails again, stop and report what you tried.
- If the task is ambiguous, ask one question before starting.

## When to stop
- Stop when the acceptance criteria are met and the tests pass.

## Final report
- What changed and why, files touched, how it was verified, and
  anything left undone.

Объясняйте причину правила, когда она неочевидна. Агент встречает ситуации, которых вы не перечислили, и правило с причиной обобщается лучше, чем голый запрет.

2. Определения инструментов

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

• Называйте инструменты по тому, что они делают: search_orders, а не query2.
• Описывайте, когда использовать каждый и когда не использовать.
• Говорите, что возвращается, включая формат и ограничения.
• Делайте параметры однозначными: типы, форматы, допустимые значения, пример.
• Избегайте пересекающихся инструментов. Если справиться с работой могут два инструмента, модель будет выбирать непоследовательно.
• Возвращайте ошибки, на которые можно отреагировать: «дата должна быть в формате ГГГГ-ММ-ДД», а не «неверный ввод».

Немного хорошо описанных инструментов лучше большого набора похожих. Model Context Protocol стандартизирует, как инструменты описываются и предлагаются агентам.

3. Промпт задачи

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

## Objective
Add rate limiting to the public API.

## Requirements
- 100 requests per minute per API key.
- Return 429 with a Retry-After header when exceeded.

## Constraints
- Existing clients must keep working: no changes to response schemas.

## Acceptance criteria
- New tests cover the limit and the 429 response.
- The existing test suite passes.

Критерии приёмки дают агенту способ понять, что он закончил, а вам — способ проверить. Расширение PromptFlowEngine для VS Code превращает задачу в одну строку в такую структуру и прикрепляет нужные файлы.

4. Управление контекстом

Всё, что читает агент, остаётся в его контексте и перечитывается на каждом шаге. Если ничего не делать, контекст заполняется устаревшим выводом инструментов, стоимость растёт, а качество падает.

• Возвращайте компактные результаты инструментов. Нужные поля, а не всю нагрузку.
• Суммируйте или отбрасывайте старые результаты после использования.
• Для долгих задач храните долговременные заметки вне контекста, в файле, который агент может читать и обновлять.
• Делегируйте. Передайте самодостаточную подзадачу субагенту со свежим контекстом и заберите только его вывод.

См. оптимизацию токенов.

Как писать промпты для субагентов

Когда один агент ставит задачу другому, задание — это всё, что знает получатель. Хороший промпт делегирования указывает:

1. Цель и почему она важна.
2. Что уже известно, чтобы не повторять работу.
3. Точный нужный вывод и его формат.
4. Границы: что трогать, а что оставить в покое.

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

Безопасность агентов

Агенты действуют, поэтому ошибки и атаки имеют последствия.

• Наименьшие привилегии. У каждого инструмента самое узкое разрешение, при котором он работает. По умолчанию только чтение.
• Подтверждение необратимых действий. Удаление, отправка, оплата, развёртывание.
• Считайте результаты инструментов ненадёжными. Веб-страница или файл могут содержать инструкции, нацеленные на агента. См. инъекцию промптов.
• Лимиты. Максимум шагов, максимум расходов и тайм-ауты.
• Не держите секреты в контексте. Передавайте учётные данные инструментам напрямую. См. обнаружение персональных данных и секретов.
• Логируйте каждый вызов инструмента, чтобы запуск можно было проверить.

Типичные режимы сбоев

Оценка агентов

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

О цикле рассуждений, лежащем в основе всего этого, см. промптинг ReAct.