Agent AI n8n na własnym VPS: konfiguracja krok po kroku

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

Agent AI n8n to pojedynczy węzeł AI Agent z dołączonymi węzłami podrzędnymi: jednym modelem czatu, co najmniej jednym narzędziem i opcjonalną pamięcią. Należy określić cel w języku naturalnym, a model zdecyduje, które narzędzia wywołać i w jakiej kolejności, aż będzie mógł udzielić odpowiedzi. Wszystkie opisane poniżej ustawienia dotyczą tej jednej koncepcji.

Łańcuch działa odwrotnie. W węźle Basic LLM Chain określa się etapy, a model jedynie generuje tekst. W agencie etapy określa model, dlatego odpowiedź na to samo pytanie może dziś wymagać jednego wywołania modelu, a jutro dziewięciu. Ta różnica wpływa na każde ustawienie opisane w tym przewodniku.

Zakłada się, że n8n już działa za HTTPS na zarządzanej maszynie. Jeśli tak nie jest, należy rozpocząć od samodzielnego hostowania n8n w Docker z prawidłowym certyfikatem, ponieważ przechowywany klucz API wymaga kopii zapasowej klucza szyfrowania, której wymaga ten przewodnik. Wzorce niezwiązane z agentami, czyli podsumowania z webhooków i klasyfikatory uruchamiane zgodnie z harmonogramem, opisano w wzorcach przepływów pracy Claude i n8n.

Przed użyciem dowolnej nazwy pola należy sprawdzić wersję, ponieważ n8n często zmienia węzły AI.

docker compose exec n8n n8n --version

Nazwy w tym przewodniku odpowiadają bieżącej stabilnej wersji n8n z lipca 2026. Od wersji 1.82.0 każdy węzeł AI Agent działa jako Tools Agent, dlatego lista rozwijana ze starym typem agenta już nie istnieje.

Krok 1: wybierz wyzwalacz

W przypadku agenta konwersacyjnego dodaj węzeł Chat Trigger. Podczas tworzenia pozostaw opcję Make Chat Publicly Available wyłączoną, aby można było uzyskać do niego dostęp tylko z panelu czatu edytora. Włącz ją po ukończeniu agenta i wybraniu sposobu uwierzytelniania.

Chat Trigger przekazuje agentowi pole o nazwie chatInput. Ta nazwa ma znaczenie w kroku 3. Jej nieprawidłowe ustawienie jest najczęstszą przyczyną pierwszego niepowodzenia.

W przypadku agenta działającego bez nadzoru użyj węzła Schedule Trigger lub Webhook. Żaden z nich nie generuje chatInput, dlatego monit należy napisać samodzielnie.

Krok 2: dane uwierzytelniające modelu

Umieść węzeł AI Agent na obszarze roboczym. n8n natychmiast wyświetli pod nim pusty konektor Chat Model. Dołącz w tym miejscu węzeł podrzędny Anthropic Chat Model.

Utwórz dane uwierzytelniające w Anthropic Console pod adresem platform.claude.com, wybierając kolejno Settings i API Keys. Klucz jest wyświetlany tylko raz. Korzystanie z API jest rozliczane za token i odbywa się niezależnie od dowolnej subskrypcji Claude.ai. Przed pierwszym uruchomieniem na koncie trzeba skonfigurować rozliczenia.

Model należy dobierać dla agenta, a nie dla całej firmy. Agent korzystający z jednego narzędzia, który wyszukuje informacje i przekazuje wynik, działa poprawnie na modelu Haiku. Według danych z lipca 2026 jego cena wynosi $1 za milion tokenów wejściowych i $5 za milion tokenów wyjściowych. Gdy agent korzysta z kilku narzędzi i musi zaplanować ich użycie, należy przejść na model Sonnet. W ten sposób unika się sytuacji, w której tani model cztery razy wywołuje niewłaściwe narzędzie, generując wyższy koszt niż droższy model, który raz wywoła właściwe narzędzie.

Ustaw opcję Maximum Number of Tokens w opcjach węzła podrzędnego. Ogranicza ona długość każdej odpowiedzi generowanej przez model. Pozostawienie dużej wartości domyślnej może spowodować, że pojedyncze nieprawidłowe wykonanie wygeneruje bardzo długą odpowiedź i zwiększy opłaty.

Dokumentacja n8n wskazuje również istotne ograniczenie: wyrażenia wewnątrz węzła podrzędnego są zawsze obliczane względem pierwszego elementu wejściowego, a nie osobno dla każdego elementu. Wyrażenia zależne od poszczególnych elementów należy umieszczać w polach promptu węzła głównego.

Krok 3: prompt otrzymywany przez agenta

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

• Take from previous node automatically oczekuje pola wejściowego o nazwie chatInput. Jest to właściwy wybór w przypadku Chat Trigger.
• Define below wyświetla pole Prompt (User Message), w którym można wpisać tekst statyczny lub wyrażenie. Jest to właściwy wybór w przypadku Schedule Trigger lub węzła Webhook.

Jeśli przed węzłem znajduje się Webhook, treść żądania POST trafia do pola $json.body, dlatego 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: udostępnienie agentowi jednego narzędzia

Węzeł AI Agent bez podrzędnego węzła narzędzia odmawia uruchomienia. Należy rozpocząć od jednego narzędzia, ponieważ jedno działające narzędzie dostarcza więcej informacji niż cztery częściowo skonfigurowane.

Należy podłączyć węzeł HTTP Request do złącza Tool agenta. Należy skonfigurować go dokładnie tak jak zwykły węzeł HTTP Request, a następnie najpierw przetestować ten endpoint 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ż zakończy działanie błędem. Błąd będzie wyglądał jak problem z modelem, chociaż w rzeczywistości będzie wynikał z adresu URL lub uwierzytelniania. Należy usunąć problem w powłoce, a nie w węźle.

Pole Description narzędzia nie służy jako dokumentacja dla współpracowników. Jest to jedyna informacja odczytywana przez model podczas ustalania, czy dane narzędzie jest istotne. Należy użyć prostego opisu zwracanych danych: „Zwraca bieżący stan up lub down oraz czas niedostępności jednej monitorowanej usługi w formacie JSON”.

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

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

Argumenty to key, a następnie opcjonalnie description, type i defaultValue. Klucz musi zawierać od 1 do 64 znaków oraz może składać się z liter, cyfr, podkreśleń i łączników. Typ musi być jednym z: string, number, boolean lub json. Domyślnie jest ustawiana wartość 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 miejsca. Informuje model: „wygeneruj wartość i nazwij ją service”, a model wyszukuje ją w konwersacji, danych wejściowych oraz wynikach innych narzędzi. W przepływie czatu może po prostu poprosić o nią użytkownika.

Krok 5: pamięć i przyczyna zapominania przez agenta

Bez podwęzła pamięci każda wiadomość jest przetwarzana od początku. Należy dołączyć podwęzeł Simple Memory, aby przechowywać ostatnią część rozmowy.

Podwęzeł ma dwa parametry. Session Key określa, której rozmowy dotyczy sesja. Dwóch użytkowników z różnymi kluczami otrzymuje oddzielne historie. Context Window Length określa liczbę poprzednich interakcji ponownie przekazywanych w monicie.

Context Window Length wpływa zarówno na koszty, jak i na jakość. Każda zapamiętana tura jest ponownie wysyłana jako tokeny wejściowe przy każdym kolejnym wywołaniu. W przypadku rozmownego agenta okno o wartości 20 oznacza ponoszenie kosztu tych samych początkowych wiadomości dwadzieścia razy.

Simple Memory nie działa w aktywnym środowisku produkcyjnym, gdy n8n działa w trybie kolejkowania, ponieważ historia jest przechowywana w danych samego przepływu pracy, a nie we współdzielonym magazynie. W instancji działającej w trybie kolejkowania należy zamiast tego użyć podwęzła Postgres Chat Memory i wskazać bazę danych dostępną zarówno dla procesu głównego, jak i dla procesów roboczych.

Krok 6: komunikat systemowy

Otwórz Options agenta i dodaj System Message. W tym miejscu należy umieścić 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.

Polecenie „Always call the status tool before answering” ma tutaj praktyczne znaczenie. Bez niego model, który uzna, że zna już odpowiedź, pominie narzędzie i odpowie na podstawie zapamiętanych informacji. Odpowiedź będzie błędna, gdy tylko zmieni się infrastruktura.

Dlaczego agent zapętla się i co go zatrzymuje

W sekcji Options znajduje się również opcja Max Iterations, której wartość domyślna wynosi 10. Jedna iteracja obejmuje jedno wywołanie modelu oraz jeden wynik narzędzia przekazany z powrotem do kontekstu. Pojedyncze uruchomienie agenta nie oznacza więc jednego wywołania API, lecz maksymalnie dziesięć wywołań. Każde z nich przekazuje jako dane wejściowe całą narastającą konwersację.

Zmniejsz tę wartość. Większość agentów korzystających z jednego narzędzia kończy pracę po dwóch iteracjach. Limit 3 lub 4 zamienia niekończącą się pętlę w kontrolowany błąd widoczny na liście wykonań.

Podczas debugowania włącz opcję Return Intermediate Steps. Końcowy wynik będzie wtedy zawierał wywołania narzędzi wykonane przez agenta. Umożliwia to rozróżnienie sytuacji, w której model nigdy nie wywołał narzędzia, od sytuacji, w której narzędzie nie zwróciło użytecznych danych. Przed przejściem do środowiska produkcyjnego wyłącz tę opcję, ponieważ te kroki są zbędne dla użytkownika końcowego.

Obserwuj przebieg wykonania z poziomu powłoki.

docker compose logs -f n8n

Zapobieganie cichym wydatkom agenta działającego bez nadzoru

Agent uruchamiany przez Chat Trigger ma człowieka, który go nadzoruje i zatrzymuje, gdy odpowiedź wygląda na błędną. Agent uruchamiany przez Schedule Trigger nie jest nadzorowany. Pełny opis znajduje się w Kontrola kosztów agenta AI na stale działającym VPS. W tym przypadku najważniejsze są cztery ustawienia.

• Ustaw limit Maximum Number of Tokens w podwęźle modelu, aby pojedyncza odpowiedź nie mogła być zbyt długa.
• Ustaw Max Iterations na najmniejszą wartość, przy której zadanie jest nadal wykonywane do końca.
• Ogranicz rozmiar odpowiedzi narzędzi. Narzędzie zwracające obiekt JSON zawierający 4,000 wierszy przekazuje całą jego zawartość do następnego wywołania modelu, a następnie do każdego kolejnego wywołania w tym samym przebiegu.
• Sprawdź, czy agent w ogóle musi działać według harmonogramu. Zadanie uruchamiane co pięć minut jest wykonywane 288 razy dziennie. Koszt jednego przebiegu należy pomnożyć przez tę wartość.

Na czas wprowadzania zmian dezaktywuj workflow. Aktywny workflow z Schedule Trigger nadal działa na podstawie wersji zapisanej przez n8n, która nie zawsze jest wersją widoczną na ekranie.

FAQ

Dlaczego mój węzeł AI Agent odmawia wykonania?

Węzeł AI Agent wymaga podrzędnego węzła modelu czatu oraz co najmniej jednego podrzędnego węzła narzędzia. Węzeł z modelem, ale bez narzędzia, kończy działanie przed wykonaniem wywołania API. Należy podłączyć jedno narzędzie, nawet proste, a następnie uruchomić węzeł ponownie.

Agent odpowiada, ale nigdy nie wywołuje mojego narzędzia. Jaki jest problem?

Prawie zawsze przyczyną jest pole Description narzędzia. Model wybiera narzędzia na podstawie ich opisów, dlatego opis taki jak „HTTP Request” nie informuje go, kiedy należy użyć narzędzia. Należy zmienić opis tak, aby określał, jakie dane są zwracane i w jakiej sytuacji narzędzie jest przydatne. Następnie należy dodać w polu System Message instrukcję nakazującą agentowi wywołać to narzędzie przed udzieleniem odpowiedzi.

Dlaczego to samo pytanie kosztuje inną kwotę przy każdym uruchomieniu?

Ponieważ model wybiera liczbę kroków. W każdej iteracji ponownie wysyłana jest cała dotychczasowa rozmowa, w tym wyniki wcześniejszych wywołań narzędzi. Dlatego uruchomienie wymagające czterech iteracji kosztuje znacznie więcej niż czterokrotność pojedynczego wywołania. Max Iterations określa maksymalną liczbę iteracji, a Return Intermediate Steps pokazuje, ile kroków faktycznie wykorzystano podczas danego uruchomienia.

Pamięć działa w edytorze, ale nie działa w środowisku produkcyjnym. Co się zmieniło?

Należy sprawdzić, czy instancja działa w trybie kolejki. Simple Memory przechowuje historię w danych wykonania własnych dla danego workflow. Dane te nie są przekazywane do oddzielnego procesu workera, dlatego aktywny workflow produkcyjny traci historię. Należy użyć podrzędnego węzła Postgres Chat Memory, który przechowuje historię w bazie danych współdzielonej przez wszystkie workery.