Як створити AI-агента n8n на власному VPS

Що таке AI-агент n8n і чим він відрізняється від ланцюжка

AI-агент n8n — це один вузол AI Agent із підключеними до нього підвузлами: однією chat model, одним або кількома інструментами та необов’язковою memory. Ви формулюєте мету звичайною мовою, а модель визначає, які інструменти викликати та в якому порядку, доки не зможе надати відповідь. Усе нижче стосується конфігурації навколо цієї ідеї.

Ланцюжок працює інакше. У Basic LLM Chain ви визначаєте кроки, а модель лише генерує текст. В агенті модель визначає кроки, тому одна й та сама відповідь сьогодні може потребувати одного виклику моделі, а завтра — дев’яти. Саме ця відмінність визначає кожне налаштування в цьому посібнику.

Передбачається, що n8n уже працює за HTTPS на машині, якою ви керуєте. Якщо це не так, почніть із самостійного розгортання n8n у Docker зі справжнім сертифікатом, оскільки API key, який ви збираєтеся зберегти, потребує резервної копії encryption-key, на якій наголошено в тому посібнику. Інформацію про шаблони без агентів, зокрема summarizers на основі webhook і scheduled classifiers, див. у матеріалі шаблони робочих процесів Claude і n8n.

Перевірте свою версію, перш ніж покладатися на назви полів у цьому матеріалі, оскільки n8n часто змінює AI-вузли.

docker compose exec n8n n8n --version

Назви в цьому посібнику відповідають поточній стабільній версії n8n станом на July 2026. Починаючи з version 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 Console за адресою platform.claude.com, у розділі Settings, а потім API Keys. Ключ відображається лише один раз. Використання API оплачується за токен і не входить до жодної підписки Claude.ai, тому до першого запуску в обліковому записі потрібно налаштувати оплату.

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

Установіть Maximum Number of Tokens в опціях підвузла. Цей параметр обмежує довжину кожної відповіді, яку генерує модель. Якщо залишити велике значення за замовчуванням, один невдалий запуск може створити дуже довгу відповідь і збільшити витрати.

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

Крок 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 інструмента не є документацією для колег. Це єдине поле, яке модель читає, визначаючи, чи підходить цей інструмент. Сформулюйте звичайне речення про результат: «Повертає поточний стан — up або down — і тривалість простою для однієї контрольованої служби у форматі 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». Потім модель шукає це значення в діалозі, вхідних даних та результатах інших інструментів. У робочому процесі чату вона може просто запитати його в користувача.

Крок 5: пам’ять і причина, через яку агент забуває

Без підвузла пам’яті кожне повідомлення починається з нуля. Додайте підвузол Simple Memory, щоб зберігати недавню розмову.

Він має два параметри. Session Key визначає, до якої розмови належать дані, тому два користувачі з різними ключами отримують окремі історії. Context Window Length визначає, скільки попередніх взаємодій повторно додається до промпту.

Context Window Length впливає на вартість так само, як і на якість, оскільки кожен збережений обмін повідомленнями повторно надсилається як вхідні токени під час кожного наступного виклику. Для балакучого агента вікно розміром 20 означає, що ви двадцять разів оплачуєте надсилання тих самих ранніх повідомлень.

Simple Memory не працює в активному робочому процесі production-середовища, коли n8n працює в queue mode, оскільки історія зберігається у власних даних робочого процесу, а не у спільному сховищі. В екземплярі, що працює в queue mode, використовуйте підвузол Postgres Chat Memory і підключіть його до бази даних, доступної і головному процесу, і worker-процесам.

Крок 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.

Фраза «Завжди викликайте інструмент status перед відповіддю» виконує важливу функцію. Без неї модель, яка вважає, що вже знає відповідь, пропустить інструмент і відповість на основі пам’яті. Така відповідь одразу стане неправильною після зміни вашої інфраструктури.

Чому агент зациклюється і що це зупиняє

У розділі Options також є параметр Max Iterations. За замовчуванням він має значення 10. Одна ітерація — це один виклик моделі та один результат інструмента, переданий назад у контекст. Тому один запуск агента — це не один виклик API, а до десяти викликів. Кожен із них передає на вхід усю накопичену розмову.

Зменште це значення. Більшість агентів, які використовують один інструмент, завершують роботу за дві ітерації. Обмеження у 3 або 4 ітерації перетворює нескінченний цикл на помилку, яку можна побачити у списку виконань.

Під час налагодження увімкніть Return Intermediate Steps. Тоді кінцевий результат міститиме виклики інструментів, які агент виконав у процесі роботи. Це дає змогу відрізнити ситуацію, коли модель взагалі не викликала інструмент, від ситуації, коли інструмент повернув непридатний результат. Перед запуском у робочому середовищі вимкніть цей параметр, оскільки ці кроки не потрібні кінцевому користувачеві.

Перегляньте виконання з оболонки.

docker compose logs -f n8n

Як запобігти непомітним витратам неконтрольованого агента

Агент за Chat Trigger працює за участю людини, і ця людина зупиняє його, якщо відповідь виглядає неправильною. За агентом із Schedule Trigger ніхто не стежить. Повний опис наведено в матеріалі Контроль витрат AI-агента на постійно доступному VPS. Тут основну роботу виконують чотири параметри.

• Обмежте Maximum Number of Tokens у дочірньому вузлі моделі, щоб жодна окрема відповідь не була надто довгою.
• Установіть Max Iterations на найменше значення, за якого завдання ще виконується успішно.
• Обмежуйте обсяг відповідей інструментів. Інструмент, який повертає JSON-об’єкт на 4,000 рядків, передає весь цей обсяг до наступного виклику моделі, а потім і до кожного наступного виклику в межах того самого запуску.
• Перевірте, чи потрібен агенту розклад взагалі. Завдання, яке запускається кожні п’ять хвилин, виконується 288 разів на день. Незалежно від вартості одного запуску, саме на це значення потрібно її помножити.

Деактивуйте workflow на час внесення змін. Активний workflow із Schedule Trigger продовжує працювати з версією, збереженою в n8n, а це не завжди версія, яку ви бачите на екрані.

FAQ

Чому мій вузол AI Agent відмовляється виконуватися?

Вузлу AI Agent потрібні підвузол chat model і принаймні один підвузол tool. Вузол із моделлю, але без інструмента, завершується помилкою ще до виконання будь-якого API-виклику. Додайте один інструмент, навіть найпростіший, і запустіть вузол знову.

Агент відповідає, але ніколи не викликає мій інструмент. У чому проблема?

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

Чому те саме запитання щоразу коштує по-різному?

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

У редакторі пам’ять працює, але у виробничому середовищі — ні. Що змінилося?

Перевірте, чи працює екземпляр у режимі черги. Simple Memory зберігає історію у власних даних виконання workflow. Ці дані не передаються окремому процесу worker, тому активний workflow у виробничому середовищі втрачає історію. Замініть цей підвузол на Postgres Chat Memory, який зберігає історію в базі даних, спільній для всіх worker.