n8n pyta, Ragen odpowiada. Jak podpiąć firmową bazę wiedzy do automatyzacji

Jeśli budujesz automatyzacje w n8n, znasz ten moment. Przepływ działa: zgłoszenie wpada z formularza, dane lecą do CRM-a, powiadomienie idzie na Slacka. Wszystko poza jednym krokiem, tym, który wymaga wiedzy o Twojej firmie. Jaka procedura obowiązuje przy tym typie reklamacji. Co obiecaliśmy temu klientowi w umowie. Czy ten wyjątek już kiedyś zatwierdzaliśmy.

Ten krok zwykle wraca do człowieka. I tam zostaje, bo model językowy podpięty do n8n zna internet, a nie Twoje dokumenty.

Ragen zamyka tę lukę jako endpoint HTTP. Konfigurujesz Asystenta AI w panelu razem z dokumentami i uprawnieniami, a potem wywołujesz go z dowolnego miejsca w automatyzacji. To, którego asystenta pytasz, jest zapisane w kluczu API – dzięki temu Ragen odpowiada każdemu klientowi, który zna format OpenAI, natywnym nodom n8n włącznie. Poniżej trzy sposoby, żeby to zrobić, od najprostszego do najbardziej autonomicznego.

Zanim zaczniesz: klucz z zakresem i adres instancji

Dwie rzeczy, które musisz mieć pod ręką. Cała procedura jest w Quickstarcie, tu skrót.

Klucz API i jego zakres. Panel Ragen, Ustawienia → Klucze API → Nowy klucz. Przy tworzeniu wybierasz Zakres: Cała baza wiedzy albo Jeden asystent. Pierwszy, domyślny, odpowiada z dokumentów nieprzypisanych do żadnego asystenta, czyli z tego samego zbioru, który widzi czat bez wybranego asystenta. Drugi odpowiada z dokumentów wskazanego Asystenta AI. Klucz pokazuje się raz, po zamknięciu okna zostaje tylko zamaskowany podgląd. Przy okazji warto włączyć Tryb debug: każda rozmowa przez API zapisuje się wtedy jako wątek w zakładce Wątki API projektu, razem z pytaniem i odpowiedzią. Na etapie budowania przepływu oszczędza to sporo zgadywania.

Zakres jest granicą, nie domyślną wartością. To jedyna rzecz w tym modelu, która potrafi zaskoczyć. Pole assistant_id nie zniknęło, tylko stało się opcjonalne – a jeśli je podasz, musi się zgadzać z kluczem. Klucz wystawiony dla asystenta A, który dostaje żądanie o asystenta B, odpowiada 403, a nie odpowiedzią z B. Klucz na całą bazę wiedzy odrzuca każde assistant_id, nawet poprawne. Najprościej więc pole pomijać i pozwolić decydować kluczowi: jeden klucz na przepływ albo na zespół, zamiast jednego klucza i identyfikatora wklejanego do każdego node’a. Pełna matryca tego, co klucz o danym zakresie może przeczytać i zmienić, jest w dokumentacji uwierzytelniania.

Adres instancji. Ragen jest self-hosted, więc nie ma jednego publicznego hosta. W dokumentacji występuje jako RAGEN_BASE_URL i kończy się na /v1. Lokalnie to http://localhost:3001/v1. Jeśli n8n i Ragen stoją w tej samej sieci Dockera, użyj nazwy usługi, na przykład http://ragen-api:3001/v1, i nie wypuszczaj tego ruchu w internet.

Klucz wstaw do n8n jako osobne poświadczenie, nie do treści node’a. W node HTTP Request: Authentication → Generic Credential Type → Header Auth, nazwa nagłówka Authorization, wartość Bearer sk-.... Dzięki temu klucz nie wycieknie w eksporcie przepływu ani w logach wykonania.

Ścieżka 1: HTTP Request do /v1/chat

Najkrótsza droga do działającego przepływu. Jedno pytanie, jedna odpowiedź, bez historii rozmowy.

Node HTTP Request, metoda POST, URL http://ragen-api:3001/v1/chat, uwierzytelnianie jak wyżej, Send Body włączone, Body Content Type: JSON, treść wpisana jako JSON:

{
  "content": "{{ $json.question }}",
  "context": "{{ $json.ticketBody }}"
}

Odpowiedź jest tak prosta, jak się da:

{
  "text": "Zgodnie z procedurą reklamacyjną klient ma 30 dni od odbioru..."
}

W kolejnym node’zie sięgasz po nią przez {{ $json.text }}.

Nie ma tu assistant_id, bo o asystenta odpowiada klucz. Możesz go dopisać, jeśli lubisz jawność, ale wtedy musi wskazywać dokładnie tego asystenta, dla którego klucz został wystawiony.

Pole content przyjmuje od 1 do 10 000 znaków i jest właściwym pytaniem. Pole context jest opcjonalne, mieści do 20 000 znaków i służy do doklejenia materiału, którego nie ma w bazie wiedzy: treści maila, opisu zgłoszenia, zawartości strony. content steruje wyszukiwaniem w dokumentach, context tylko dokłada tło do odpowiedzi.

Szczegóły pól, kodów błędów i format strumieniowania opisuje referencja Chat API. Strumieniowania w n8n nie włączaj, node i tak czeka na całą odpowiedź, a zdarzenia SSE musiałbyś sklejać ręcznie.

Dokumentacja poleca /v1/chat/completions jako domyślny wybór dla nowych integracji, i słusznie: prędzej czy później zechcesz historię rozmowy albo raport zużycia. /v1/chat zostaje prostszą drogą, kiedy pytanie jest jedno i na tym koniec.

Ta ścieżka wystarcza do większości automatyzacji: kwalifikacja zgłoszenia, odpowiedź pierwszej linii wsparcia, podsumowanie dokumentu do CRM-a, sprawdzenie procedury przed zatwierdzeniem wniosku.

Ścieżka 2: /v1/chat/completions i natywne nody OpenAI

Drugi endpoint mówi formatem OpenAI i daje to, czego /v1/chat nie ma: historię rozmowy, systemowy prompt na żądanie, wybór modelu, temperaturę, limit tokenów i raport zużycia. Pełna specyfikacja jest w referencji Chat Completions.

Odkąd assistant_id jest opcjonalne, ten endpoint da się wywołać klientem, który zna wyłącznie format OpenAI – a to znaczy, że do podłączenia Ragena nie potrzebujesz już node’a HTTP Request. W poświadczeniu OpenAI Account wpisujesz klucz Ragena jako API Key i adres swojej instancji jako Base URL (http://ragen-api:3001/v1). Od tej pory OpenAI Chat Model, Basic LLM Chain i zwykły node OpenAI rozmawiają z Twoją bazą wiedzy zamiast z OpenAI, bez ani jednego pola ustawianego ręcznie.

Pole modelu w n8n domyślnie pobiera listę z GET /v1/models, który Ragen obsługuje. Dostajesz przecięcie trzech rzeczy: katalogu modeli, tego, co obsługuje brama modeli w Twojej instalacji, i tego, co dopuścił administrator organizacji. Jeśli wolisz, przełącz pole w tryb wpisywania i podaj identyfikator z ręki – oba sposoby działają.

Jedno ograniczenie, o którym lepiej wiedzieć zawczasu. Node AI Agent dokłada do żądania pole tools, bo tak działa agent w LangChainie. Ragen odrzuca tools, tool_choice i response_format błędem 400, i robi to świadomie: wybór narzędzi jest po stronie projektu, przez integracje MCP, a nie w treści pojedynczego żądania. Zwykłe nody modelu tego pola nie wysyłają i działają bez zmian. Jeśli potrzebujesz agenta, który sam decyduje, kiedy sięgnąć do wiedzy, jest do tego ścieżka 3.

Kiedy chcesz ułożyć treść żądania samodzielnie – bo trzymasz historię rozmowy w swojej bazie albo składasz systemowy prompt ze zmiennych – HTTP Request nadal jest najkrótszą drogą. Ten sam node, URL .../v1/chat/completions, treść:

{
  "model": "gpt-5.4",
  "temperature": 0.2,
  "messages": [
    {
      "role": "system",
      "content": "Odpowiadaj po polsku, maksymalnie trzy zdania. Jeśli w dokumentach nie ma odpowiedzi, napisz: brak podstawy w dokumentacji."
    },
    { "role": "user", "content": "Jaki mamy SLA na zgłoszenia krytyczne?" },
    { "role": "assistant", "content": "Cztery godziny robocze." },
    { "role": "user", "content": "{{ $json.question }}" }
  ]
}

Odpowiedź ma standardową strukturę OpenAI, więc tekst wyciągasz przez {{ $json.choices[0].message.content }}, a zużycie tokenów przez {{ $json.usage.total_tokens }}. To drugie warto zapisywać, na przykład do arkusza albo bazy: po dwóch tygodniach masz realny koszt przepływu zamiast szacunków.

Kilka rzeczy, które oszczędzą Ci debugowania:

• Pytaniem jest ostatnia wiadomość user. Wcześniejsze wiadomości stanowią historię rozmowy, a instrukcje systemowe dokładają się do instrukcji projektu, nie zastępują ich.
• Tablica messages mieści od 1 do 100 wiadomości. Jeśli trzymasz historię w bazie, przycinaj ją po swojej stronie.
• Pozostałe standardowe parametry OpenAI – top_p, stop, seed, presence_penalty i resztę tej listy – są przyjmowane i walidowane, choć część z nich nie zmienia dziś odpowiedzi. Chodzi o to, żeby klient mówiący formatem OpenAI nie musiał najpierw czyścić żądania.
• assistant_id możesz pominąć albo podać. Podane musi zgadzać się z zakresem klucza, inaczej dostajesz 403.

Jeśli wolisz kod, w self-hosted n8n możesz też użyć node’a Code z oficjalnym SDK @webamigos/ragen-sdk-ts, po dopisaniu go do zmiennej NODE_FUNCTION_ALLOW_EXTERNAL.

Ścieżka 3: serwer MCP, kiedy pyta agent

Dwie pierwsze ścieżki zakładają, że to Ty decydujesz, kiedy sięgnąć do bazy wiedzy. Przy agencie w n8n decyzja należy do modelu, a Ragen jest jednym z narzędzi na jego liście.

Ragen wystawia serwer MCP pod $RAGEN_MCP_URL/mcp (transport Streamable HTTP, domyślnie port 3300), uwierzytelniany tym samym kluczem API w nagłówku Authorization: Bearer. W n8n podłączasz go node’em MCP Client Tool wpiętym pod AI Agent, z uwierzytelnianiem typu Bearer. Nowsze wersje n8n pozwalają wybrać transport, starsze przyjmują wyłącznie endpoint SSE, więc jeśli w node’zie widzisz tylko pole „SSE Endpoint”, zaktualizuj n8n.

Model samego agenta zostaje przy Twoim dostawcy. Tutaj Ragen jest narzędziem, nie modelem, więc ograniczenie z pola tools opisane w ścieżce 2 tej drogi nie dotyczy.

Agent dostaje wtedy trzy narzędzia:

• ragen_chat – wyślij pytanie i odbierz odpowiedź opartą o dokumenty,
• ragen_search_knowledge_base – przeszukaj bazę wiedzy i odbierz same fragmenty dokumentów, bez generowanej odpowiedzi,
• ragen_list_assistants – wypisz asystentów widocznych dla Twojego klucza, razem z ich identyfikatorami.

W żadnym z nich nie musisz podawać assistant_id: pole jest opcjonalne, a decyzję podejmuje zakres klucza, dokładnie tak jak po stronie REST API. Klucz wystawiony dla jednego asystenta odpowiada z niego bez pytania, a ragen_list_assistants zwróci wtedy tylko jego.

Jest tu jedna pułapka, o której warto uprzedzić agenta w jego instrukcji. Klucz na całą bazę wiedzy wylistuje wszystkich asystentów organizacji, ale odpowiedzieć z żadnego z nich nie potrafi: odrzuci każde wywołanie wskazujące asystenta błędem 403. Model, który posłusznie wywoła najpierw ragen_list_assistants, a potem ragen_chat ze znalezionym identyfikatorem, trafi dokładnie w to 403. Przy takim kluczu wystarczy assistant_id pomijać.

Konfigurację klienta, przykłady wywołań i format odpowiedzi opisuje dokumentacja serwera MCP.

Wywołania MCP zawsze wracają w całości, bez strumieniowania. Jeśli agent obsługuje kilka źródeł naraz, opisz w jego instrukcji, kiedy ma sięgać do Ragena: „pytania o procedury, umowy i dokumentację wewnętrzną kieruj do ragen_chat”. Bez tego model potrafi odpowiadać z własnej pamięci, co jest dokładnie tym, czego chciałeś uniknąć.

Kiedy nie potrzebujesz odpowiedzi, tylko fragmentów

Jest jeszcze czwarty wariant. Endpoint POST /v1/search przeszukuje bazę wiedzy i zwraca przygotowany blok kontekstu razem z identyfikatorami plików źródłowych, bez wywoływania modelu generującego:

{
  "query": "warunki wypowiedzenia umowy ramowej",
  "max_results": 5
}

W odpowiedzi dostajesz context i file_ids. To samo trafia do modelu przy zwykłej rozmowie, tyle że tutaj decyzję, co dalej, podejmuje Twój przepływ. Wychodzi taniej i szybciej, a wynik jest przewidywalny: kiedy porównujesz, klasyfikujesz albo tylko sprawdzasz, czy w dokumentach w ogóle coś na dany temat jest, generowanie zdań jest zbędnym krokiem. To samo narzędzie jest dostępne dla agentów jako ragen_search_knowledge_base.

Limity i błędy

Cztery rzeczy, na które warto zwrócić uwagę w trakcie integracji.

Limity są liczone po adresie IP. 20 żądań na minutę dla /v1/chat i 10 dla /v1/chat/completions, bo za każdym stoi pełen pipeline RAG: wyszukiwanie w dokumentach, rerank wyników i wywołanie modelu. Twoja instancja n8n wychodzi zwykle z jednego adresu, więc ten budżet dzielą wszystkie przepływy naraz. Przy przetwarzaniu listy wstaw Loop Over Items i node Wait, zamiast wysyłać sto żądań w pętli. Osobno od tego działają limity zespołowe: jeśli w panelu ustawiono zespołowi rpm albo tpm, przepływ obije się o nie niezależnie od limitu na adres IP.

429 i 502 to błędy przejściowe. W ustawieniach node’a włącz Retry On Fail i ustaw Max Tries na 3. Wait Between Tries to jedno pole ze stałym opóźnieniem, więc odczekiwanie coraz dłuższe i z losowym rozrzutem musisz zbudować sam: pętlą z node’em Wait i czasem wyliczonym z numeru próby. Warto przy tym pamiętać, że ponawianie łata pojedyncze potknięcie, ale nie podnosi limitu. Jeśli 429 wraca regularnie, trzy próby co kilka sekund trafią w to samo okno, a odpowiedzią jest rozłożenie żądań w czasie, nie agresywniejsze ponawianie. 401 i 403 przejściowe nie są: pierwsze oznacza zły klucz, drugie klucz dezaktywowany albo żądanie wykraczające poza zakres klucza, i ponawianie nic tu nie da. Treść błędu 403 mówi wprost, o który z tych przypadków chodzi.

Domyślny timeout bywa za krótki. Odpowiedź z pełnego pipeline’u potrafi zająć kilkanaście sekund, zwłaszcza przy dłuższych dokumentach. Ustaw Timeout w opcjach node’a świadomie, na przykład 60 000 ms.

Pytanie ma być pytaniem. Wrzucenie do content całego maila razem ze stopką i historią korespondencji psuje wyszukiwanie, bo połowa tekstu to szum. Wyciągnij samo pytanie, a resztę przekaż w context.

Co wybrać

Wspólny mianownik jest taki, że konfigurację robisz raz, w panelu: dokumenty, uprawnienia, instrukcje asystenta, wybór modelu, a od niedawna również to, do czego klucz ma dostęp. Przepływy w n8n tylko pytają. Kiedy do bazy wiedzy dojdzie nowy dokument albo zmieni się procedura, nie ruszasz żadnego przepływu.

Ragen jest oprogramowaniem open source na licencji Apache 2.0, więc całe to API możesz uruchomić u siebie i sprawdzić na własnych dokumentach, zanim podejmiesz decyzję. Kod jest na GitHubie, a dokumentacja na docs.ragen.ai.

Jeśli masz już procesy w n8n i zastanawiasz się, który z nich pierwszy zyska na dostępie do firmowej wiedzy, chętnie przejdziemy przez to na konkretach. Umów bezpłatną konsultację.