Jak zbudować agenta AI w n8n na własnym VPS

Czym jest agent AI w n8n i czym różni się od łańcucha (chain)

Agent AI w n8n to pojedynczy węzeł AI Agent z podłączonymi do niego podwęzłami: jednym modelem czatu, jednym lub wieloma narzędziami oraz opcjonalną pamięcią. Definiuje się cel w języku naturalnym, a model samodzielnie decyduje, które narzędzia wywołać i w jakiej kolejności, aż do uzyskania odpowiedzi. Cała poniższa konfiguracja opiera się na tej koncepcji.

Łańcuch (chain) działa odwrotnie. W węźle Basic LLM Chain to użytkownik określa kroki, a model jedynie uzupełnia tekst. W przypadku agenta to model decyduje o krokach, dlatego to samo pytanie może dziś wymagać jednego wywołania modelu, a jutro dziewięciu. Ta jedna różnica determinuje wszystkie ustawienia opisane w tym przewodniku.

Zakłada się, że n8n działa już za HTTPS na kontrolowanej maszynie. Jeśli tak nie jest, należy zacząć od self-hosting n8n on Docker with a real certificate, ponieważ klucz API, który zostanie zapisany, wymaga kopii zapasowej klucza szyfrującego, na której kładzie nacisk tamten przewodnik. W przypadku wzorców innych niż agenty, takich jak podsumowywanie webhooków czy klasyfikatory harmonogramowe, zobacz Claude and n8n workflow patterns.

Przed zaufaniem jakiejkolwiek nazwie pola należy sprawdzić wersję, ponieważ n8n często zmienia węzły AI.

docker compose exec n8n n8n --version

Nazwy w tym przewodniku są zgodne z aktualną stabilną wersją n8n na lipiec 2026. Od wersji 1.82.0 każdy węzeł AI Agent działa jako Tools Agent, więc stara lista rozwijana wyboru typu agenta już nie istnieje.

Krok 1: wybór wyzwalacza

W przypadku agenta konwersacyjnego należy dodać węzeł Chat Trigger. Podczas tworzenia projektu opcja Make Chat Publicly Available powinna pozostać wyłączona, aby dostęp do agenta był możliwy wyłącznie z poziomu panelu czatu w edytorze. Opcję tę należy włączyć dopiero po zakończeniu prac nad agentem i podjęciu decyzji dotyczących uwierzytelniania.

Węzeł Chat Trigger przekazuje agentowi pole o nazwie chatInput. Nazwa ta jest istotna w kroku 3, a jej błędne wprowadzenie jest najczęstszą przyczyną niepowodzenia na wczesnym etapie.

W przypadku agenta działającego w trybie bezobsługowym należy użyć węzła Schedule Trigger lub Webhook. Żaden z nich nie generuje pola chatInput, dlatego prompt należy przygotować samodzielnie.

Krok 2: poświadczenia modelu

Umieść węzeł AI Agent na obszarze roboczym. n8n natychmiast wyświetli pod nim pusty konektor Chat Model. Podłącz do niego podwęzeł Anthropic Chat Model.

Utwórz poświadczenia w konsoli Anthropic pod adresem platform.claude.com, w sekcji Settings, a następnie API Keys. Klucz jest wyświetlany tylko raz. Wykorzystanie API jest rozliczane za token i jest niezależne od subskrypcji Claude.ai, dlatego przed pierwszym uruchomieniem należy skonfigurować płatności na koncie.

Dobieraj model do konkretnego agenta, a nie do całej firmy. Agent z jednym narzędziem, który wyszukuje informacje i je raportuje, działa poprawnie na modelu Haiku, który według stanu na lipiec 2026 kosztuje 1 USD za milion tokenów wejściowych i 5 USD za milion wyjściowych. Gdy agent posiada kilka narzędzi i musi planować ich użycie, przejdź na model Sonnet. Unikasz w ten sposób sytuacji, w której tani model czterokrotnie wywołuje niewłaściwe narzędzie, co kosztuje więcej niż jednorazowe wywołanie właściwego narzędzia przez droższy model.

Ustaw Maximum Number of Tokens w opcjach podwęzła. Ogranicza to długość każdej odpowiedzi generowanej przez model. Pozostawienie dużej wartości domyślnej może sprawić, że w przypadku błędnego zapętlenia wygenerowana zostanie bardzo długa odpowiedź, za którą zostaniesz obciążony kosztami.

Ważna uwaga z dokumentacji n8n, o której często zapominają użytkownicy: wyrażenia wewnątrz podwęzła są zawsze rozwiązywane względem pierwszego elementu wejściowego, nigdy dla każdego elementu z osobna. Wyrażenia zależne od poszczególnych elementów umieszczaj w polach promptu węzła głównego.

Krok 3: prompt otrzymywany przez agenta

Otwórz węzeł AI Agent. Parametr Prompt posiada dwa ustawienia.

• Take from previous node automatically oczekuje przychodzącego pola o nazwie chatInput. Jest to właściwy wybór w przypadku umieszczenia węzła za Chat Trigger.
• Define below odsłania pole Prompt (User Message), w którym wpisuje się tekst statyczny lub wyrażenie. Jest to właściwy wybór w przypadku umieszczenia węzła za Schedule Trigger lub węzłem Webhook.

Jeśli przed węzłem znajduje się Webhook, treść żądania POST trafia do $json.body, więc pole promptu wygląda następująco.

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.

Krok 4: dodanie jednego narzędzia do agenta

Węzeł AI Agent bez podpiętego narzędzia nie uruchomi się. Należy zacząć od jednego, ponieważ pojedyncze działające narzędzie uczy więcej niż cztery nieskonfigurowane poprawnie.

Podłącz węzeł HTTP Request do złącza Tool agenta. Skonfiguruj go dokładnie tak samo, jak standardowy węzeł HTTP Request, a następnie przetestuj dany punkt końcowy z poziomu powłoki.

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

Jeśli polecenie curl zwraca błąd lub stronę logowania HTML, agent również zgłosi błąd. Błąd ten może wyglądać na problem z modelem, podczas gdy w rzeczywistości jest to problem z adresem URL lub uwierzytelnianiem. Należy go naprawić w powłoce, a nie w węźle.

Pole Description narzędzia nie służy jako dokumentacja dla współpracowników. Jest to jedyny tekst, który model odczytuje, decydując o przydatności narzędzia. Należy je sformułować jako jasne stwierdzenie dotyczące zwracanych danych, na przykład: "Returns the current up or down state and the downtime duration for one monitored service, as JSON."

Aby pozwolić modelowi na uzupełnienie części żądania, należy użyć wyrażenia $fromAI(). Działa ono wyłącznie w narzędziach podłączonych do węzła AI Agent i nie funkcjonuje w narzędziu Code.

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

Argumentami są key, a następnie opcjonalne description, type oraz defaultValue. Klucz musi mieć od 1 do 64 znaków i składać się z liter, cyfr, podkreślników oraz myślników. Typ musi być jednym z string, number, boolean lub json, a wartością domyślną jest string. Pełniejsze wywołanie wygląda następująco.

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

Klucz jest wskazówką, a nie odwołaniem do istniejących danych. $fromAI('service') nie odczytuje pola o nazwie service z żadnego źródła. Informuje ono model: "wygeneruj wartość i nazwij ją service", a model przeszukuje konwersację, dane wejściowe oraz wyniki innych narzędzi, aby ją znaleźć. W przepływie czatu model może po prostu zapytać użytkownika.

Wyszukiwarka internetowa jest zazwyczaj drugim dodawanym narzędziem. Ponieważ jest to kolejny punkt końcowy HTTP, można skierować ten sam węzeł na własną instancję SearXNG zamiast płatnego API wyszukiwarki, pod warunkiem traktowania każdej pobranej strony jako niezaufanego tekstu, który trafia bezpośrednio do promptu.

Krok 5: pamięć i przyczyny utraty kontekstu przez agenta

Bez podwęzła pamięci każda wiadomość jest przetwarzana w izolacji. Należy dołączyć podwęzeł Simple Memory, aby przechowywać historię niedawnej konwersji.

Posiada on dwa parametry. Session Key określa identyfikator konwersacji, dzięki czemu użytkownicy z różnymi kluczami mają odrębne historie. Context Window Length definiuje, ile poprzednich interakcji zostanie ponownie wstrzykniętych do promptu.

Parametr Context Window Length wpływa zarówno na jakość, jak i na koszty, ponieważ każda zapamiętana tura jest przesyłana jako tokeny wejściowe przy każdym kolejnym wywołaniu. Ustawienie okna na 20 w przypadku aktywnego agenta oznacza, że za te same początkowe wiadomości płaci się dwudziestokrotnie.

Podwęzeł Simple Memory nie działa w środowisku produkcyjnym, gdy n8n pracuje w trybie kolejkowym (queue mode), ponieważ historia jest przechowywana w danych samego workflow, a nie we współdzielonym magazynie. W instancjach działających w trybie kolejkowym należy użyć podwęzła Postgres Chat Memory i wskazać bazę danych dostępną zarówno dla głównego procesu, jak i dla workerów.

Krok 6: Komunikat systemowy

Otwórz Options agenta i dodaj System Message. W tym miejscu umieszcza się opis zadania; jest to tekst o największym wpływie na działanie całego procesu.

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.

Instrukcja "Always call the status tool before answering" pełni tu kluczową rolę. Bez niej model, który zakłada, że zna odpowiedź, pominie narzędzie i udzieli odpowiedzi na podstawie pamięci. Będzie ona błędna w momencie, gdy infrastruktura ulegnie zmianie.

Dlaczego agent wpada w pętlę i co ją przerywa

W sekcji Options znajduje się również parametr Max Iterations, którego wartość domyślna wynosi 10. Jedna iteracja to jedno wywołanie modelu oraz wynik działania narzędzia przekazany z powrotem do kontekstu. Pojedyncze uruchomienie agenta nie jest zatem jednym wywołaniem API, lecz procesem obejmującym do 10 kroków, z których każdy przesyła całą rosnącą historię konwersacji jako dane wejściowe.

Warto zmniejszyć tę wartość. Większość agentów korzystających z pojedynczego narzędzia kończy pracę w dwóch iteracjach, a limit 3 lub 4 tur zmienia niekontrolowaną pętlę w czysty błąd, który można zidentyfikować na liście wykonania.

Podczas debugowania należy włączyć opcję Return Intermediate Steps. Wynik końcowy będzie wtedy zawierał wywołania narzędzi wykonane przez agenta, co pozwala odróżnić sytuację, w której „model nigdy nie wywołał narzędzia”, od sytuacji, w której „narzędzie nie zwróciło żadnych przydatnych danych”. Przed uruchomieniem produkcyjnym należy wyłączyć tę opcję, ponieważ kroki te stanowią szum informacyjny dla użytkownika końcowego.

Przebieg wykonania można monitorować z poziomu powłoki.

docker compose logs -f n8n

Zapobieganie niekontrolowanym kosztom agenta działającego w tle

Agent uruchamiany przez Chat Trigger ma po drugiej stronie człowieka, który zatrzymuje go, gdy odpowiedź wygląda na błędną. Agent uruchamiany przez Schedule Trigger nie jest przez nikogo nadzorowany. W tym przypadku monitorowane są koszty użycia modelu, a nie koszty licencji, ponieważ w bezpłatnej wersji self-hosted działają węzły agenta, narzędzi i pamięci, a funkcje wymagające płatnego klucza dotyczą głównie pracy zespołowej i zarządzania. Pełny opis znajduje się w Kontrola kosztów agenta AI na stale działającym VPS. Większość pracy wykonują tutaj cztery ustawienia.

• Ogranicz Maximum Number of Tokens w podwęźle modelu, aby żadna pojedyncza odpowiedź nie była nadmiernie długa.
• Ustaw Max Iterations na najniższą wartość pozwalającą na wykonanie zadania.
• Ograniczaj rozmiar odpowiedzi narzędzi. Narzędzie zwracające 4000 linii JSON przesyła całą treść do kolejnego wywołania modelu, a następnie do każdego kolejnego wywołania w ramach tego samego uruchomienia.
• Rozważ, czy agent faktycznie wymaga harmonogramu. Zadanie uruchamiane co pięć minut wykonuje się 288 razy dziennie. Koszt pojedynczego uruchomienia należy pomnożyć przez tę liczbę.

Dezaktywuj workflow na czas wprowadzania zmian. Aktywny workflow z Schedule Trigger jest uruchamiany w wersji zapisanej w n8n, która nie zawsze jest tożsama z wersją widoczną na ekranie.

FAQ

Dlaczego węzeł AI Agent odmawia wykonania zadania?

Węzeł AI Agent wymaga podwęzła modelu czatu oraz co najmniej jednego podwęzła narzędzia. Węzeł posiadający model, lecz pozbawiony narzędzia, kończy działanie przed wykonaniem jakiegokolwiek wywołania API. Należy dołączyć jedno narzędzie, nawet o podstawowej funkcjonalności, i uruchomić proces ponownie.

Agent odpowiada, ale nie wywołuje mojego narzędzia. Co jest nie tak?

Przyczyną jest niemal zawsze pole Description narzędzia. Model wybiera narzędzia na podstawie analizy ich opisów, więc opis typu "HTTP Request" nie dostarcza informacji o tym, kiedy narzędzie powinno zostać użyte. Należy przeredagować opis tak, aby wskazywał, jakie dane są zwracane i w jakiej sytuacji narzędzie jest przydatne, a następnie dodać w System Message instrukcję nakazującą agentowi wywołanie tego narzędzia przed udzieleniem odpowiedzi.

Dlaczego to samo pytanie kosztuje różną kwotę przy każdym uruchomieniu?

Wynika to z faktu, że model samodzielnie wybiera liczbę kroków. Każda iteracja przesyła ponownie całą dotychczasową historię konwersacji, w tym dane wyjściowe poprzednich narzędzi, dlatego uruchomienie wymagające czterech iteracji kosztuje znacznie więcej niż czterokrotność pojedynczego wywołania. Parametr Max Iterations stanowi górny limit tych działań, a opcja Return Intermediate Steps pozwala sprawdzić, ile kroków faktycznie wykorzystano w danym uruchomieniu.

Moja pamięć działa w edytorze, ale nie na produkcji. Co się zmieniło?

Należy sprawdzić, czy instancja działa w trybie kolejki (queue mode). Simple Memory przechowuje historię w danych wykonania samego workflow, które nie są zachowywane przy przekazywaniu zadania do oddzielnego procesu roboczego (worker), przez co aktywny workflow produkcyjny traci te dane. Należy zastąpić go podwęzłem Postgres Chat Memory, który przechowuje historię w bazie danych współdzielonej przez wszystkie procesy robocze.