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

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

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

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

Предполагается, что n8n уже работает по протоколу HTTPS на контролируемой вами машине. Если это не так, начните с self-hosting n8n on Docker with a real certificate, так как для API-ключа, который вы собираетесь сохранить, требуется резервная копия ключа шифрования, о которой говорится в том руководстве. Информацию о паттернах без использования агентов (обработчики вебхуков для суммаризации и планировщики классификации) см. в Claude and n8n workflow patterns.

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

docker compose exec n8n n8n --version

Названия в этом руководстве соответствуют текущей стабильной версии n8n по состоянию на июль 2026 года. Начиная с версии 1.82.0, каждый узел AI Agent работает как Tools Agent, поэтому выпадающий список выбора типа агента больше не используется.

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

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

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

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

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

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

Создайте учетные данные в консоли Anthropic на сайте platform.claude.com в разделе Settings, а затем API Keys. Ключ отображается только один раз. Использование API оплачивается за каждый токен и не связано с подпиской Claude.ai, поэтому перед первым запуском необходимо настроить биллинг в аккаунте.

Выбирайте модель для каждого агента индивидуально, а не для всей компании. Агент с одним инструментом, который выполняет поиск и выдает отчет, отлично работает на Haiku. По состоянию на июль 2026 года стоимость составляет $1 за миллион входных токенов и $5 за миллион выходных. Как только агент получит несколько инструментов и начнет планировать работу с ними, переходите на Sonnet. Вы избегаете ситуации, когда дешевая модель четыре раза вызывает неверный инструмент, что обходится дороже, чем один вызов верного инструмента дорогой моделью.

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

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

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

Откройте узел AI Agent. Параметр Prompt имеет две настройки.

• Take from previous node automatically ожидает входящее поле с именем 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: добавление одного инструмента агенту

Узел AI Agent без подключенного узла-инструмента не запустится. Начните с одного инструмента: один работающий инструмент даст вам больше понимания, чем четыре настроенных наполовину.

Подключите узел 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), так как история хранится в данных самого рабочего процесса, а не в общем хранилище. Для экземпляра в режиме очереди используйте под-узел Postgres Chat Memory и укажите базу данных, доступную как основному процессу, так и рабочим узлам (workers).

Шаг 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 вызовов, каждый из которых передает на вход всю растущую историю диалога.

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

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

Наблюдайте за выполнением процесса из командной строки.

docker compose logs -f n8n

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

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

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

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

FAQ

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

Узлу AI Agent требуется подчиненный узел с языковой моделью и как минимум один подчиненный узел с инструментом. Узел, у которого есть модель, но нет инструмента, завершается с ошибкой до выполнения любого API-запроса. Подключите один инструмент, даже самый простой, и запустите узел снова.

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

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

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

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

Моя память работает в редакторе, но не в production. Что изменилось?

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