AI-агент n8n на власному VPS: налаштування

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

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

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

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

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

docker compose exec n8n n8n --version

Назви в цьому посібнику відповідають поточній стабільній версії n8n станом на July 2026. Починаючи з version 1.82.0 кожен AI Agent node працює як Tools Agent, тому старого списку вибору типу agent більше немає.

Крок 1: виберіть тригер

Для conversational agent додайте вузол Chat Trigger. Поки ви створюєте agent, залиште параметр Make Chat Publicly Available вимкненим, щоб доступ до нього мала лише панель чату в редакторі. Увімкніть цей параметр, коли agent буде готовий і ви визначитеся зі способом автентифікації.

Chat Trigger передає agent поле з назвою chatInput. Ця назва важлива на кроці 3. Неправильна назва — найпоширеніша причина першої помилки.

Для agent без оператора використовуйте вузол Schedule Trigger або Webhook. Жоден із них не створює chatInput, тому prompt потрібно буде написати самостійно.

Крок 2: облікові дані моделі

Додайте на canvas вузол 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, про яке часто забувають: вирази всередині підвузла завжди обчислюються відносно першого вхідного елемента, а не окремо для кожного елемента. Вирази, які мають обчислюватися для кожного елемента, розміщуйте в полях 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, а потім спочатку перевірте цей endpoint із shell.

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

Якщо цей curl повертає помилку або HTML-сторінку входу, агент також завершиться помилкою. При цьому проблема виглядатиме як проблема моделі, хоча насправді це проблема URL або автентифікації. Виправте її в shell, а не у вузлі.

Поле 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", а модель шукає це значення в розмові, вхідних даних та результатах інших інструментів. У workflow чату модель може просто запитати його в користувача.

Вебпошук зазвичай є другим інструментом. Оскільки це лише інший HTTP endpoint, цей самий вузол можна спрямувати на власний екземпляр SearXNG замість платного пошукового API, якщо кожну отриману ним сторінку розглядати як ненадійний текст, який тепер потрапляє у prompt.

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

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

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

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

Simple Memory не працює в активному production workflow, коли n8n працює в queue mode, оскільки історія зберігається у власних даних workflow, а не в спільному сховищі. В інстансі, що працює в 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.

Фраза «Always call the status tool before answering» справді виконує важливу функцію. Без неї модель, яка вважає, що вже знає відповідь, пропустить виклик інструмента й відповість із пам’яті. Щойно інфраструктура зміниться, така відповідь буде впевнено неправильною.

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

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

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

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

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

docker compose logs -f n8n

Як не допустити непомітних витрат необмеженого агента

За агентом із Chat Trigger стоїть людина. Вона зупиняє його, якщо відповідь виглядає неправильно. За агентом із Schedule Trigger ніхто не стежить. Тут ви контролюєте витрати на використання моделі, а не витрати на ліцензію, оскільки вузли агента, інструментів і пам’яті працюють у безкоштовній self-hosted edition, а функції, для яких потрібен платний ключ, здебільшого стосуються командної роботи та governance. Повний розбір наведено в матеріалі Контроль витрат AI-агента на постійно увімкненому VPS. Основну роботу виконують чотири параметри.

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

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

FAQ

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

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

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

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

Чому однакове запитання щоразу має різну вартість?

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

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

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