Jak zbudować agenta AI w n8n na własnym VPS
Instrukcja konfiguracji węzła AI Agent z modelem Claude, narzędziem HTTP Request oraz pamięcią. Dowiedz się, jak ustawić limity kosztów i poprawnie wdrożyć automatyzację na 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 kilkoma narzędziami oraz opcjonalną pamięcią. Użytkownik określa cel w języku naturalnym, a model decyduje, które narzędzia wywołać i w jakiej kolejności, aż do uzyskania odpowiedzi. Cała poniższa treść dotyczy konfiguracji opartej na tej koncepcji.
Łańcuch (chain) działa w odwrotny sposób. W węźle Basic LLM Chain to użytkownik decyduje o krokach, a model jedynie uzupełnia tekst. W przypadku agenta to model decyduje o krokach, dlatego to samo pytanie może wymagać jednego wywołania modelu dzisiaj, a dziewięciu jutro. Ta pojedyncza różnica determinuje każde ustawienie w tym przewodniku. Jeśli ta pętla jest nowym pojęciem, a nie tylko funkcją n8n, warto napisać ją raz ręcznie, zanim zostanie złożona z węzłów, ponieważ węzeł ukrywa dokładnie ten element, nad którym będziesz analizować przez resztę tego przewodnika.
Zakłada się, że n8n działa już za HTTPS na maszynie, którą zarządzasz. Jeśli tak nie jest, zacznij od samodzielnego hostowania n8n w Dockerze z poprawnym certyfikatem, ponieważ klucz API, który zamierzasz zapisać, wymaga kopii zapasowej klucza szyfrującego, na której kładzie nacisk tamten przewodnik. W przypadku wzorców innych niż agent, takich jak podsumowywanie webhooków czy planowane klasyfikatory, zobacz wzorce przepływów pracy Claude i n8n.
Sprawdź wersję przed zaufaniem jakiejkolwiek nazwie pola w tym dokumencie, ponieważ n8n często zmienia węzły AI.
docker compose exec n8n n8n --versionWersja 1.82.0 wycofała ustawienie typu agenta na rzecz Tools Agent. Starsze węzły w wersji v1 nadal posiadają to ustawienie; dokumentacja n8n przewiduje usunięcie tej wersji węzła w n8n 3.0.
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 Claude pod adresem platform.claude.com, w sekcji Settings, a następnie API keys. Klucz wyświetlany jest tylko raz. Konsola podczas tworzenia klucza wyświetla monit o wybór daty wygaśnięcia, a zautomatyzowany agent przestaje działać w dniu wygaśnięcia klucza, dlatego zapisz tę datę w widocznym miejscu. W przypadku zautomatyzowanego agenta użyj klucza konta serwisowego przypisanego do obszaru roboczego, aby żądania nie wymagały osobnego nagłówka obszaru roboczego.
Wykorzystanie API jest rozliczane za token, a sposób płatności zależy od planu Claude, według stanu na 31 października 2026. Plany Max, Ultra oraz Team obejmują miesięczne kredyty API: 100 USD w planie Max, 200 USD w planie Ultra oraz do 500 USD w puli w planie Team. Kredyty odbiera się poprzez powiązanie organizacji w konsoli z planem w sekcji Settings > Billing (dla planów Max lub Ultra) lub Organization settings > Billing (dla planu Team); nie ma potrzeby dodawania metody płatności w konsoli. Nowi subskrybenci mogą odebrać kredyty po 7 dniach od rozpoczęcia planu, a niewykorzystane środki wygasają z końcem każdego cyklu rozliczeniowego lub co miesiąc w planach rocznych. Po wyczerpaniu kredytów w ramach planu żądania są rozliczane z zakupionych środków, funkcja auto-reload może dokupić kolejne, a organizacje rozliczane fakturami otrzymują rachunek za nadmiarowe użycie. Żądania są wstrzymywane, gdy organizacja przedpłacona nie posiada dostępnych kredytów; wykorzystanie API nigdy nie jest obciążeniem planu Claude. Plany Free, Pro oraz Enterprise nie obejmują miesięcznych kredytów API, więc w ich przypadku API jest rozliczane oddzielnie od subskrypcji.
Wybieraj model dla każdego agenta z osobna, a nie dla całej firmy. Agent z jednym narzędziem, który wyszukuje informacje i je raportuje, działa poprawnie na modelu Haiku. Bieżąca wersja, Haiku 5.5, kosztuje 0,10 USD za milion tokenów wejściowych i 0,50 USD za milion wyjściowych według stanu na 12 października 2026. Stawki rosną do 0,50 USD i 2,50 USD dla każdego żądania, którego prompt przekroczy 100 000 tokenów, co może nastąpić przy długim oknie pamięci i dużych wynikach działania narzędzi. Gdy agent posiada kilka narzędzi i musi planować ich użycie, przejdź na model Sonnet. Unikasz w ten sposób błędu polegającego na użyciu taniego modelu, który czterokrotnie wywołuje niewłaściwe narzędzie, co kosztuje więcej niż jednokrotne 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 sprawia, że jeden błędny przebieg może wygenerować bardzo długą odpowiedź, za którą zostaniesz obciążony.
Jedno zastrzeżenie z dokumentacji n8n, które sprawia trudności wielu użytkownikom: wyrażenia wewnątrz podwęzła zawsze odnoszą się do pierwszego elementu wejściowego, nigdy do każdego elementu z osobna. Wyrażenia dla 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 Source for Prompt (User Message) posiada dwa ustawienia.
- Connected Chat Trigger Node oczekuje przychodzącego pola o nazwie
chatInput. Jest to właściwy wybór w przypadku użycia węzła 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 użycia węzła Schedule Trigger lub Webhook.
Jeśli przed agentem znajduje się węzeł 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
Dokumentacja n8n wskazuje, że do węzła AI Agent należy podłączyć co najmniej jeden podwęzeł narzędzia, chociaż obecny kod węzła (wersja 3.1) blokuje uruchomienie jedynie w przypadku braku modelu czatu. Należy zacząć od jednego narzędzia, ponieważ jedno działające narzędzie uczy więcej niż cztery skonfigurowane połowicznie, a agent bez narzędzi to jedynie kosztowniejsza wersja łańcucha.
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 punkt końcowy bezpośrednio z poziomu powłoki.
curl -s -H 'Accept: application/json' \
https://status.example.com/api/status/database | head -c 400Jeśli polecenie curl zwróci błąd lub stronę logowania w formacie HTML, agent również nie zadziała. Błąd zostanie zinterpretowany jako problem z modelem, podczas gdy w rzeczywistości przyczyną będzie nieprawidłowy adres URL lub błąd uwierzytelniania. Problem należy rozwiązać w powłoce, a nie w węźie.
Pole Description narzędzia nie służy jako dokumentacja dla współpracowników. Model odczytuje je wraz z nazwą narzędzia i schematem parametrów, aby zdecydować, czy narzędzie jest przydatne. Należy je sformułować jako jasny opis zwracanych danych: "Zwraca bieżący stan (up/down) oraz czas przestoju dla jednej monitorowanej usługi w formacie 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') }}Argumenty to 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 stanowi wskazówkę, a nie odwołanie do istniejących danych. $fromAI('service') nie odczytuje pola o nazwie service z żadnego źródła. Informuje 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 to zazwyczaj drugie narzędzie. 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 traktowana jako początek konwersacji. Należy dołączyć podwęzeł Simple Memory, aby przechowywać historię ostatnich interakcji.
Węzeł ten posiada 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 liczbę poprzednich interakcji, które są ponownie wstrzykiwane do promptu.
Parametr Context Window Length wpływa zarówno na jakość, jak i na koszty, ponieważ każda zapamiętana wymiana zdań jest przesyłana jako tokeny wejściowe przy każdym kolejnym wywołaniu. Ustawienie okna o wartości 20 dla aktywnego agenta oznacza, że za te same początkowe wiadomości użytkownik płaci dwudziestokrotnie.
Mechanizm Simple Memory nie działa w środowisku produkcyjnym, gdy n8n pracuje w trybie kolejkowym (queue mode). Wynika to z faktu, że historia jest przechowywana w lokalnej mapie procesu (singleton Map), indeksowanej identyfikatorami workflow i sesji, do której procesy robocze (workers) nie mają wspólnego dostępu. 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 procesów roboczych.
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 pojedyncze wywołanie modelu, które kończy się albo żądaniem użycia narzędzia, albo zwróceniem ostatecznej odpowiedzi; wyniki działania narzędzi są przekazywane do kolejnego wywołania. Zatem pojedyncze uruchomienie agenta nie jest jednym wywołaniem API, lecz procesem obejmującym do dziesięciu wywołań, z których każde otrzymuje na wejściu całą rosnącą historię konwersacji.
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 czytelny błąd, widoczny na liście wykonywanych zadań.
Podczas debugowania należy włączyć opcję Return Intermediate Steps. Ostateczny wynik 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ą zbędny szum dla użytkownika końcowego.
Przebieg działania można monitorować z poziomu powłoki.
docker compose logs -f n8nZapobieganie niekontrolowanemu zużyciu zasobów przez agenta działającego w tle
Agent uruchamiany przez Chat Trigger posiada nadzór człowieka, który zatrzymuje proces w przypadku nieprawidłowej odpowiedzi. Agent uruchamiany przez Schedule Trigger działa bez nadzoru. W tym przypadku monitorowane jest zużycie modelu, a nie licencja, ponieważ węzły agenta, narzędzi i pamięci działają w darmowej wersji self-hosted, a funkcje wymagające płatnego klucza dotyczą głównie pracy zespołowej i zarządzania. Pełne opracowanie tematu znajduje się w kontrola kosztów agenta AI na serwerze VPS działającym w trybie ciągłym. Cztery ustawienia odpowiadają za większość optymalizacji.
- Ogranicz Maximum Number of Tokens w podwęźle modelu, aby pojedyncza odpowiedź nie mogła być zbyt długa.
- Ustaw Max Iterations na najniższą wartość, która pozwala na wykonanie zadania.
- Ograniczaj rozmiar odpowiedzi narzędzi. Narzędzie zwracające obiekt JSON o długości 4000 linii przesyła go w całości do kolejnego wywołania modelu, a następnie do każdego kolejnego wywołania w ramach tego samego uruchomienia.
- Rozważ, czy agent rzeczywiście wymaga harmonogramu. Zadanie uruchamiane co pięć minut wykonuje się 288 razy dziennie. Koszt jednego uruchomienia należy pomnożyć przez tę wartość.
Wycofaj publikację workflow na czas wprowadzania zmian lub pamiętaj, która wersja jest aktywna. Opublikowany workflow z Schedule Trigger wykonuje ostatnio opublikowaną wersję, a nie wersję roboczą widoczną na ekranie, ponieważ n8n przechowuje edycje w wersji roboczej do momentu ponownej publikacji.
FAQ
Dlaczego węzeł AI Agent odmawia wykonania zadania?
W pierwszej kolejności należy sprawdzić konektory. Węzeł AI Agent wymaga podwęzła modelu czatu; w przeciwnym razie zatrzymuje się z komunikatem "Please connect a model to the Chat Model input" przed wykonaniem jakiegokolwiek wywołania API. Dokumentacja n8n wskazuje również, że wymagany jest co najmniej jeden podwęzeł narzędzia (tool). Jeśli model jest podłączony, a węzeł nadal odmawia pracy, należy dodać jedno narzędzie, nawet trywialne, i uruchomić proces ponownie.
Agent odpowiada, ale nigdy 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 tych opisów, więc opis typu "HTTP Request" nie informuje go, kiedy należy użyć danego narzędzia. Należy go przeredagować tak, aby zawierał informacje o tym, jakie dane są zwracane i w jakiej sytuacji narzędzie jest przydatne. Następnie należy dodać wiersz w System Message z instrukcją dla agenta, aby wywołał to narzędzie 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 z poprzednich narzędzi. Uruchomienie wymagające czterech iteracji jest rozliczane za tokeny wejściowe i wyjściowe ze wszystkich czterech wywołań. 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.
Pamięć działa w edytorze, ale nie działa na produkcji. Co się zmieniło?
Należy sprawdzić, czy instancja działa w trybie kolejki (queue mode). Mechanizm Simple Memory przechowuje historię w lokalnej dla procesu mapie (singleton Map), indeksowanej identyfikatorami przepływu pracy i sesji, do której oddzielne procesy robocze (worker processes) nie mają dostępu. Należy zastąpić go podwęzłem Postgres Chat Memory, który przechowuje historię w bazie danych współdzielonej przez wszystkie procesy robocze.