AI-агент n8n на власному VPS: налаштування
Зберіть AI-агента в n8n: вузол AI Agent, Claude, HTTP Request, memory і trigger. Дізнайтеся, які параметри обмежують кількість викликів і витрати.
Що таке AI-агент n8n і чим він відрізняється від ланцюжка
AI-агент n8n — це один вузол AI Agent із під’єднаними до нього підвузлами: однією chat model, одним або кількома інструментами та, за потреби, memory. Ви формулюєте мету звичайною мовою, а модель вирішує, які інструменти викликати та в якій послідовності, доки не зможе надати відповідь. Усе нижче описує конфігурацію навколо цієї ідеї.
Ланцюжок працює навпаки. У Basic LLM Chain ви визначаєте кроки, а модель лише генерує текст. В агенті кроки визначає модель, тому те саме запитання сьогодні може потребувати одного виклику моделі, а завтра — дев’яти. Ця єдина відмінність визначає кожне налаштування в цьому посібнику. Якщо ця схема циклу для вас нова саме як концепція, а не як функція n8n, варто один раз написати її вручну, перш ніж збирати її з вузлів, оскільки вузол приховує саме ту частину, яку ви далі аналізуватимете в цьому посібнику.
Передбачається, що n8n уже працює за HTTPS на сервері під вашим керуванням. Якщо це не так, почніть із self-hosting n8n у Docker із чинним сертифікатом, оскільки для API key, який ви незабаром збережете, потрібна резервна копія encryption key, на якій наполягає цей посібник. Приклади схем без агентів — summarizers через webhook і планувальники для класифікації — наведено в схемах робочих процесів Claude і n8n.
Перевірте свою версію, перш ніж покладатися на будь-яку назву поля, оскільки n8n часто змінює AI-вузли.
docker compose exec n8n n8n --versionУ версії 1.82.0 налаштування типу агента застаріло; натомість використовується Tools Agent. У застарілих вузлах v1 це налаштування ще доступне; згідно з документацією n8n, видалення цієї версії вузла заплановано для n8n 3.0.
Крок 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.
Створіть облікові дані в Claude Console на platform.claude.com: відкрийте Settings, а потім API keys. Ключ відображається лише один раз. Під час створення ключа Console також просить вибрати строк дії. Автономний агент припинить роботу в день завершення строку дії ключа, тому збережіть цю дату там, де ви її побачите. Для автономного агента використовуйте ключ service account, обмежений workspace. Тоді для запитів не потрібен окремий заголовок workspace.
Використання API оплачується за токен. Спосіб оплати залежить від вашого Claude plan станом на 31 October 2026. Плани Max, Ultra і Team включають щомісячні API credits: $100 для Max, $200 для Ultra і до $500 спільного ліміту для Team. Щоб активувати їх, зв’яжіть організацію Console із планом: відкрийте Settings > Billing у Max або Ultra чи Organization settings > Billing у Team. Додавати спосіб оплати в Console не потрібно. Нові підписники можуть активувати credits після 7 days користування планом. Невикористані credits анулюються наприкінці кожного billing cycle або щомісяця для annual plans. Коли включені credits закінчаться, запити продовжать списуватися з purchased credits. Auto-reload може придбати додаткові credits, а організаціям із виставленням рахунків буде нараховано оплату за надлишкове використання. Запити припиняються, якщо prepaid organization більше не має credits. Використання API ніколи не списується з вашого Claude plan. Плани Free, Pro і Enterprise не включають щомісячних API credits. У цих планах API оплачується окремо від subscription.
Обирайте модель для кожного агента, а не для всієї компанії. Одноінструментальний агент, який знаходить потрібні дані та повертає результат, нормально працює на Haiku. Поточна версія Haiku 5.5 станом на 12 October 2026 коштує $0.10 за million input tokens і $0.50 за million output tokens. Для запитів, у яких prompt перевищує 100,000 tokens, ціни зростають до $0.50 і $2.50 відповідно. До такого обсягу можуть призвести довге memory window і великі результати інструментів. Коли агент має кілька інструментів і повинен планувати роботу між ними, перейдіть на Sonnet. Ви уникаєте ситуації, коли дешева модель чотири рази викликає неправильний інструмент. Це може коштувати дорожче, ніж один правильний виклик дорожчої моделі.
У параметрах підвузла встановіть Maximum Number of Tokens. Цей параметр обмежує довжину кожної відповіді моделі. Якщо залишити велике значення за замовчуванням, один невдалий запуск може створити дуже довгу відповідь і збільшити рахунок.
Є важливе застереження з документації n8n. Вирази всередині підвузла завжди обчислюються для першого вхідного елемента, а не окремо для кожного елемента. Вирази, що залежать від окремого елемента, розміщуйте в полях prompt кореневого вузла.
Крок 3: prompt, який отримує агент
Відкрийте вузол AI Agent. Параметр Source for Prompt (User Message) має 2 налаштування.
- Connected Chat Trigger Node очікує вхідне поле з назвою
chatInput. Це правильний вибір для Chat Trigger. - Define below відкриває поле Prompt (User Message), у якому можна вказати статичний текст або вираз. Це правильний вибір для Schedule Trigger або вузла Webhook.
Якщо перед агентом використовується вузол Webhook, тіло POST-запиту передається в $json.body, тому поле prompt має такий вигляд.
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) відмовляється запускатися лише без chat model. У будь-якому разі почніть з одного інструмента, оскільки один робочий інструмент дає більше інформації, ніж чотири частково налаштовані, а агент без інструмента — це лише ланцюжок із вищими витратами.
Під’єднайте вузол 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", а модель шукає це значення в діалозі, вхідних даних і результатах інших інструментів. У chat workflow вона може просто запитати його в користувача.
Web search — типовий другий інструмент. Оскільки це лише інший HTTP endpoint, можна спрямувати цей самий вузол до власного екземпляра SearXNG замість платного search API, якщо розглядати кожну отриману сторінку як ненадійний текст, який тепер міститься у вашому prompt.
Крок 5: пам’ять і причина, через яку agent забуває
Без sub-node пам’яті кожне повідомлення починається з нуля. Додайте sub-node Simple Memory, щоб зберігати недавню розмову.
У ньому є два параметри. Session Key визначає, до якої розмови належить повідомлення, тому два користувачі з різними ключами отримують окремі історії. Context Window Length визначає, скільки попередніх взаємодій повторно передаватиметься в prompt.
Context Window Length впливає на вартість так само, як і на якість, оскільки кожен збережений хід розмови під час кожного наступного виклику повторно надсилається як вхідні токени. Для балакучого agent вікно розміром 20 означає, що ви двадцять разів оплачуєте ті самі ранні повідомлення.
Simple Memory не працює в активному production workflow, коли n8n працює в queue mode, оскільки зберігає історію в singleton Map, локальній для процесу, з ключами workflow і session IDs, а workers не мають спільного доступу до цієї пам’яті. В instance у queue mode використовуйте натомість sub-node Postgres Chat Memory і підключіть його до database, доступної і main process, і 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-виклик, а до десяти викликів, і кожен із них отримує весь діалог, що постійно збільшується.
Зменште це значення. Більшість агентів з одним інструментом завершують роботу за дві ітерації, а ліміт у 3 або 4 ходи перетворює неконтрольований цикл на помилку, яку можна побачити у списку виконань.
Під час налагодження увімкніть Return Intermediate Steps. Тоді остаточний результат міститиме виклики інструментів, які агент виконав у процесі роботи. Це дає змогу відрізнити ситуацію, коли модель взагалі не викликала інструмент, від ситуації, коли інструмент не повернув корисних даних. Перед переходом у робоче середовище вимкніть цей параметр, оскільки ці кроки не потрібні кінцевому користувачу.
Перегляньте виконання із shell.
docker compose logs -f n8nЯк не дати unattended agent непомітно витрачати кошти
У agent за Chat Trigger є людина, яка зупиняє його, якщо відповідь виглядає неправильною. За agent за Schedule Trigger ніхто не стежить. Тут ви контролюєте витрати на model, а не витрати на ліцензію, оскільки nodes agent, tool і memory працюють у безкоштовній self-hosted edition, а функції, для яких потрібен платний ключ, здебільшого призначені для команд і governance. Повний опис наведено в матеріалі Контроль витрат AI agent на постійно увімкненому VPS. Основну роботу виконують чотири налаштування.
- Обмежте Maximum Number of Tokens у model sub-node, щоб жодна окрема відповідь не була надто довгою.
- Установіть Max Iterations на найменше значення, за якого завдання ще виконується.
- Обмежуйте розмір відповідей tool. Якщо tool повертає JSON blob на 4,000 рядків, увесь цей вміст передається до наступного model call, а потім до кожного наступного виклику в межах того самого запуску.
- Перевірте, чи потрібен agent розклад узагалі. Завдання, яке запускається кожні п’ять хвилин, виконується 288 разів на день. Якою б не була вартість одного запуску, саме на це число потрібно помножити її.
Скасуйте публікацію workflow на час внесення змін або принаймні запам’ятайте, яка версія є активною. Опублікований workflow із Schedule Trigger продовжує виконувати останню опубліковану версію, а не draft на екрані, оскільки n8n зберігає ваші зміни як draft, доки ви не опублікуєте їх повторно.
FAQ
Чому мій вузол AI Agent відмовляється виконуватися?
Спочатку перевірте конектори. Вузлу AI Agent потрібен дочірній вузол chat model. Без нього вузол зупиняється з повідомленням "Please connect a model to the Chat Model input" ще до виконання будь-якого API-виклику. У документації n8n також зазначено, що потрібен щонайменше один дочірній вузол tool. Тому, якщо модель підключена, але вузол і далі відмовляється виконуватися, підключіть один tool, навіть найпростіший, і запустіть вузол повторно.
Агент відповідає, але ніколи не викликає мій tool. У чому проблема?
Майже завжди проблема в полі Description цього tool. Модель вибирає tools за їхніми описами, тому опис на кшталт "HTTP Request" не пояснює, коли саме застосовувати tool. Перепишіть опис так, щоб у ньому було зазначено, які дані повертає tool і у яких ситуаціях він корисний. Потім додайте до System Message рядок із вказівкою агенту викликати цей tool перед відповіддю.
Чому однакове запитання щоразу коштує по-різному?
Тому що кількість кроків визначає модель. На кожній ітерації повторно надсилається весь накопичений діалог, включно з попереднім результатом tool. Тому виконання, яке потребує чотирьох ітерацій, тарифікується за вхідні та вихідні токени в усіх чотирьох викликах. Max Iterations задає максимальну кількість ітерацій, а Return Intermediate Steps показує, скільки кроків фактично використано під час конкретного виконання.
У редакторі пам’ять працює, але в production — ні. Що змінилося?
Перевірте, чи працює instance у queue mode. Simple Memory зберігає історію в singleton Map, локальному для процесу, використовуючи workflow ID і session ID як ключі. Окремі worker-процеси не мають спільного доступу до цієї Map. Замініть її на дочірній вузол Postgres Chat Memory, який зберігає історію в базі даних, спільній для всіх worker-процесів.