Как создать AI-агента в n8n на собственном VPS

Что такое AI-агент в n8n и чем он отличается от цепочки (chain)

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

Цепочка (chain) работает иначе. В узле Basic LLM Chain вы сами определяете шаги, а модель лишь заполняет текст. В агенте модель сама определяет шаги, поэтому на один и тот же вопрос сегодня может уйти один запрос к модели, а завтра — девять. Это единственное различие определяет все настройки в данном руководстве. Если концепция цикла для вас нова (не как функция n8n, а как идея), стоит написать его вручную один раз, прежде чем собирать из узлов, так как узел скрывает именно ту часть, логику которой вы будете разбирать на протяжении всего руководства.

Предполагается, что n8n уже работает по HTTPS на подконтрольной вам машине. Если это не так, начните с самостоятельного развертывания n8n в Docker с реальным сертификатом, так как для API-ключа, который вы собираетесь сохранить, требуется резервная копия ключа шифрования, о которой говорится в том руководстве. Информацию о паттернах, не связанных с агентами (обработчики вебхуков для суммаризации и классификаторы по расписанию), см. в паттернах рабочих процессов Claude и n8n.

Проверьте свою версию, прежде чем доверять названиям полей в этом тексте, так как n8n часто меняет AI-узлы.

docker compose exec n8n n8n --version

В версии 1.82.0 настройка типа агента была признана устаревшей в пользу Tools Agent. В старых узлах версии v1 эта настройка сохраняется; документация n8n планирует удаление этой версии узла к выходу n8n 3.0.

Шаг 1: выбор триггера

Для диалогового агента добавьте узел Chat Trigger. Оставьте параметр Make Chat Publicly Available выключенным на этапе разработки, чтобы доступ к нему был только через панель чата в редакторе. Включите его, когда агент будет готов и вы определитесь с аутентификацией.

Chat Trigger передает агенту поле с именем chatInput. Это имя важно на шаге 3, и ошибки в нем — самая частая причина сбоев на первом этапе.

Для автономного агента используйте узел Schedule Trigger или Webhook. Ни один из них не создает chatInput, поэтому промпт вам придется составить самостоятельно.

Шаг 2: учетные данные модели

Перетащите узел AI Agent на рабочую область. n8n сразу отобразит под ним пустой коннектор Chat Model. Присоедините к нему под-узел Anthropic Chat Model.

Создайте учетные данные в консоли Claude по адресу platform.claude.com в разделе Settings, а затем API keys. Ключ отображается только один раз. Консоль также предложит выбрать срок действия при создании ключа. Автономный агент перестанет работать в день истечения срока действия ключа, поэтому сохраните эту дату там, где вы ее увидите. Для автономного агента используйте ключ сервисной учетной записи, привязанный к рабочей области (workspace), чтобы запросам не требовался отдельный заголовок рабочей области.

Использование API оплачивается за токен. Порядок оплаты зависит от вашего тарифного плана Claude по состоянию на 31 октября 2026 года. Планы Max, Ultra и Team включают ежемесячные кредиты API: $100 для Max, $200 для Ultra и до $500 в общем пуле для Team. Вы можете активировать их, связав организацию в консоли с тарифным планом в разделе Settings > Billing для Max или Ultra, либо в Organization settings > Billing для Team. Добавлять способ оплаты в консоли не требуется. Новые подписчики могут активировать кредиты через 7 дней после оформления плана. Неиспользованные кредиты сгорают в конце каждого расчетного периода или ежемесячно для годовых планов. Когда включенные кредиты заканчиваются, запросы продолжают выполняться за счет купленных кредитов; автопополнение может приобрести дополнительные, а организации с оплатой по счету получают счета за превышение лимита. Запросы прекращаются, если у предоплаченной организации не осталось кредитов. Использование API никогда не списывается со стоимости вашего плана Claude. Планы Free, Pro и Enterprise не включают ежемесячные кредиты API, поэтому в них API оплачивается отдельно от подписки.

Выбирайте модель для каждого агента индивидуально, а не для всей компании. Агент с одним инструментом, который выполняет поиск и формирует отчет, отлично работает на Haiku. Текущая версия, Haiku 5.5, стоит $0.10 за миллион входных токенов и $0.50 за миллион выходных по состоянию на 12 октября 2026 года. Стоимость возрастает до $0.50 и $2.50 для любого запроса, промпт которого превышает 100,000 токенов, что может произойти при большом окне памяти или объемных результатах работы инструментов. Как только у агента появляется несколько инструментов и ему приходится планировать их использование, переходите на Sonnet. Вы избегаете ситуации, когда дешевая модель четыре раза вызывает неверный инструмент, что обходится дороже, чем один вызов верного инструмента дорогой моделью.

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

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

Шаг 3: промпт, который получает агент

Откройте узел AI Agent. Параметр Source for Prompt (User Message) имеет две настройки.

• Connected Chat Trigger Node ожидает входящее поле с именем chatInput. Это верный выбор при использовании узла Chat Trigger.
• Define below открывает поле Prompt (User Message), в котором вы пишете статический текст или выражение. Это верный выбор при использовании узла Schedule Trigger или Webhook.

Если перед агентом стоит узел Webhook, тело POST-запроса попадает в $json.body, поэтому поле промпта выглядит следующим образом.

Check the current status of {{ $json.body.service }} and tell me
whether it is up. If it is down, say for how long. No preamble.

Шаг 4: добавьте агенту один инструмент

Документация n8n гласит, что к узлу AI Agent необходимо подключить как минимум один подузел инструмента, хотя текущая версия кода узла (3.1) блокирует запуск только при отсутствии модели чата. В любом случае начните с одного инструмента: один работающий инструмент даст вам больше понимания, чем четыре настроенных наполовину, а агент без инструментов — это просто цепочка, которая обходится дороже.

Подключите узел HTTP Request к разъему Tool агента. Настройте его точно так же, как обычный узел HTTP Request, но сначала протестируйте этот эндпоинт из командной строки.

curl -s -H 'Accept: application/json' \
  https://status.example.com/api/status/database | head -c 400

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

Поле Description инструмента — это не документация для коллег. Модель читает его вместе с именем инструмента и схемой параметров, когда решает, подходит ли этот инструмент для задачи. Пишите описание как простое утверждение о том, что именно вернется: "Returns the current up or down state and the downtime duration for one monitored service, as JSON."

Чтобы позволить модели заполнить часть запроса, используйте выражение $fromAI(). Оно работает только в инструментах, подключенных к узлу AI Agent, и не работает в инструменте Code.

{{ $fromAI('service', 'The name of the service to look up', 'string') }}

Аргументы: key, затем необязательные description, type и defaultValue. Ключ должен содержать от 1 до 64 символов, включая буквы, цифры, знаки подчеркивания и дефисы. Тип — один из string, number, boolean или json, по умолчанию используется string. Более полный вызов выглядит так.

{{ $fromAI('limit', 'How many records to return', 'number', 20) }}

Ключ — это подсказка, а не ссылка на существующие данные. $fromAI('service') не считывает поле с именем service откуда-либо. Оно говорит модели: "создай значение и назови его service", после чего модель просматривает историю диалога, входные данные и результаты работы других инструментов, чтобы найти подходящее значение. В чат-процессе модель может просто спросить пользователя.

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

Шаг 5: память и причины, по которым агент «забывает»

Без узла памяти каждое сообщение начинается с чистого листа. Подключите под-узел Simple Memory для хранения истории недавнего диалога.

У него есть два параметра. Session Key определяет идентификатор диалога: пользователи с разными ключами получают раздельные истории. Context Window Length задает количество предыдущих взаимодействий, которые будут повторно включены в промпт.

Параметр Context Window Length влияет как на качество, так и на стоимость, поскольку каждое запомненное сообщение повторно отправляется в качестве входных токенов при каждом последующем вызове. Если установить окно 20 для активного агента, вы будете оплачивать одни и те же ранние сообщения двадцать раз.

Узел Simple Memory не работает в активной производственной среде, если n8n запущен в режиме очереди (queue mode). Это связано с тем, что история хранится в локальной для процесса структуре Map, привязанной к идентификаторам рабочего процесса и сессии, а воркеры не имеют общего доступа к этой памяти. В режиме очереди используйте под-узел Postgres Chat Memory, указав базу данных, доступную как основному процессу, так и воркерам.

Шаг 6: Системное сообщение

Откройте Options агента и добавьте System Message. Здесь указывается описание задачи; это наиболее значимый текст в рабочем процессе.

You are an infrastructure status assistant. Always call the status
tool before answering a question about whether something is running.
Never guess. If the tool returns an error, say so and stop.

Фраза "Always call the status tool before answering" выполняет здесь реальную работу. Без неё модель, которая считает, что уже знает ответ, пропустит инструмент и ответит по памяти. Это приведет к уверенному, но неверному ответу в тот момент, когда ваша инфраструктура изменится.

Почему агент зацикливается и что его останавливает

В разделе Options также находится параметр Max Iterations, значение которого по умолчанию равно 10. Одна итерация — это один вызов модели, который либо запрашивает инструменты, либо возвращает финальный ответ; результаты работы инструментов передаются в следующий вызов. Таким образом, один запуск агента — это не один API-запрос, а до 10 вызовов, каждый из которых содержит всю растущую историю диалога в качестве входных данных.

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

Во время отладки включите Return Intermediate Steps. Тогда финальный вывод будет содержать вызовы инструментов, которые агент совершил в процессе. Это позволяет отличить ситуацию «модель не вызвала инструмент» от ситуации «инструмент не вернул ничего полезного». Отключите эту настройку перед запуском в эксплуатацию, так как эти шаги являются лишними данными для конечного пользователя.

Отслеживайте выполнение процесса из командной строки.

docker compose logs -f n8n

Предотвращение неконтролируемых расходов автономного агента

Агент, работающий по триггеру Chat Trigger, находится под контролем человека, который останавливает его при получении некорректных ответов. Агент, работающий по триггеру Schedule Trigger, работает без присмотра. В данном случае речь идет о расходах на использование модели, а не о стоимости лицензии, так как узлы агента, инструментов и памяти работают в бесплатной self-hosted версии, а функции, требующие платного ключа, в основном относятся к командной работе и управлению. Полное руководство приведено в разделе Контроль расходов AI-агента на постоянно работающем VPS. Основную часть работы выполняют четыре настройки.

• Ограничьте Maximum Number of Tokens в подузле модели, чтобы ни один ответ не мог быть слишком длинным.
• Установите Max Iterations на минимально возможное значение, при котором задача всё ещё выполняется.
• Следите за тем, чтобы ответы инструментов были небольшими. Инструмент, возвращающий JSON-объект на 4000 строк, передает весь этот объем в следующий вызов модели, а затем во все последующие вызовы в рамках одного запуска.
• Подумайте, действительно ли агенту нужно расписание. Задача, запускаемая каждые пять минут, выполняется 288 раз в день. Стоимость одного запуска — это сумма, которую нужно умножить на это число.

Отменяйте публикацию (unpublish) рабочего процесса во время внесения изменений или хотя бы помните, какая версия является активной. Опубликованный рабочий процесс с триггером Schedule Trigger продолжает выполнять последнюю опубликованную версию, а не черновик на вашем экране, так как n8n сохраняет правки в черновике до тех пор, пока вы не опубликуете их снова.

FAQ

Почему мой узел AI Agent отказывается выполнять работу?

Сначала проверьте коннекторы. Узлу AI Agent требуется вложенный узел модели чата (chat model), и без него он останавливается с ошибкой "Please connect a model to the Chat Model input" еще до выполнения API-запроса. В документации n8n также указано, что требуется как минимум один вложенный узел инструмента (tool). Если модель подключена, а узел все равно не работает, добавьте один инструмент, даже самый простой, и запустите процесс снова.

Агент отвечает, но не вызывает мой инструмент. В чем проблема?

Почти всегда дело в поле Description инструмента. Модель выбирает инструменты, анализируя их описания. Описание вроде "HTTP Request" не дает модели информации о том, когда следует применять этот инструмент. Перепишите его так, чтобы было понятно, какие данные возвращаются и в каких ситуациях это полезно. Затем добавьте в System Message инструкцию для агента вызывать этот инструмент перед ответом.

Почему один и тот же вопрос стоит по-разному при каждом запуске?

Потому что модель сама выбирает количество шагов. Каждая итерация повторно отправляет всю историю переписки, включая результаты работы инструментов, поэтому выполнение, требующее четырех итераций, оплачивается по количеству входных и выходных токенов для всех четырех вызовов. Параметр Max Iterations ограничивает это количество, а опция Return Intermediate Steps позволяет увидеть, сколько шагов было фактически использовано в конкретном запуске.

Почему память работает в редакторе, но не работает в продакшене? Что изменилось?

Проверьте, работает ли ваш экземпляр в режиме очереди (queue mode). Simple Memory хранит историю в локальной для процесса карте (Map), привязанной к ID рабочего процесса и сессии, поэтому отдельные рабочие процессы (workers) не имеют к ней общего доступа. Замените его на вложенный узел Postgres Chat Memory, который сохраняет историю в базе данных, доступной всем рабочим процессам.