n8n AI-agent bouwen op uw eigen VPS

Wat een n8n AI-agent is en waarin deze verschilt van een chain

Een n8n AI-agent is één AI Agent-node met daaraan gekoppelde subnodes: één chatmodel, een of meer tools en optioneel geheugen. U beschrijft een doel in gewone taal. Het model bepaalt vervolgens welke tools het aanroept en in welke volgorde, totdat het antwoord kan geven. Alles hieronder gaat over de configuratie rond dat ene concept.

Een chain werkt omgekeerd. In een Basic LLM Chain bepaalt u de stappen en vult het model alleen tekst in. Bij een agent bepaalt het model de stappen. Daardoor kan dezelfde vraag vandaag één modelaanroep kosten en morgen negen. Dat ene verschil bepaalt elke instelling in deze handleiding.

Dit veronderstelt dat n8n al achter HTTPS draait op een machine die u beheert. Als dat niet het geval is, begint u met n8n zelf hosten op Docker met een echt certificaat, omdat de API-sleutel die u zo gaat opslaan de back-up van de encryptiesleutel nodig heeft waarop die handleiding aandringt. Zie voor patronen zonder agents, zoals samenvatters voor webhooks en geplande classifiers, Claude- en n8n-workflowpatronen.

Controleer uw versie voordat u op een veldnaam in deze handleiding vertrouwt, omdat n8n de AI-nodes regelmatig wijzigt.

docker compose exec n8n n8n --version

De namen in deze handleiding komen overeen met de huidige stabiele versie van n8n in juli 2026. Vanaf versie 1.82.0 wordt elke AI Agent-node uitgevoerd als een Tools Agent. De oude vervolgkeuzelijst voor het agenttype bestaat daarom niet meer.

Stap 1: kies de trigger

Voeg voor een conversatieagent een Chat Trigger-node toe. Laat Make Chat Publicly Available uitgeschakeld terwijl u bouwt, zodat alleen het chatvenster van de editor toegang heeft. Schakel dit in wanneer de agent klaar is en u de authenticatie hebt bepaald.

De Chat Trigger geeft de agent een veld met de naam chatInput. Die naam is belangrijk in stap 3. Een onjuiste naam is de meest voorkomende eerste fout.

Gebruik voor een agent zonder toezicht een Schedule Trigger- of Webhook-node. Geen van beide levert chatInput op. Daarom schrijft u de prompt zelf.

Stap 2: de modelreferentie

Plaats een AI Agent-node op het canvas. n8n toont daaronder direct een lege Chat Model-connector. Koppel daar een Anthropic Chat Model-subnode aan.

Maak de referentie aan in de Anthropic Console op platform.claude.com, onder Settings en daarna API Keys. De sleutel wordt slechts eenmaal weergegeven. API-gebruik wordt per token gefactureerd en staat los van een Claude.ai-abonnement. Het account moet daarom vóór de eerste uitvoering voor facturering zijn ingesteld.

Kies het model per agent, niet per bedrijf. Een agent met één tool die iets opzoekt en het resultaat rapporteert, werkt prima met Haiku. Vanaf juli 2026 staat Haiku vermeld voor $1 per miljoen invoertokens en $5 per miljoen uitvoertokens. Zodra de agent meerdere tools heeft en daarover moet plannen, schakelt u over naar Sonnet. U voorkomt hiermee dat een goedkoop model vier keer de verkeerde tool aanroept. Dat kost meer dan een duur model dat eenmaal de juiste tool aanroept.

Stel Maximum Number of Tokens in bij de opties van de subnode. Hiermee begrenst u de lengte van elke reactie die het model genereert. Als u deze instelling op een hoge standaardwaarde laat staan, kan één mislukte uitvoering een zeer lang antwoord genereren. Daarvoor worden dan kosten in rekening gebracht.

Een aandachtspunt uit de n8n-documentatie dat vaak over het hoofd wordt gezien: expressies in een subnode worden altijd geëvalueerd op basis van het eerste invoeritem, nooit per item. Plaats expressies die per item moeten worden geëvalueerd in de promptvelden van de root-node.

Stap 3: de prompt die de agent ontvangt

Open het knooppunt AI Agent. De parameter Prompt heeft twee instellingen.

• Take from previous node automatically verwacht een inkomend veld met de naam chatInput. Dit is de juiste keuze achter een Chat Trigger.
• Define below toont een veld Prompt (User Message) waarin u statische tekst of een expressie invoert. Dit is de juiste keuze achter een Schedule Trigger of een Webhook-node.

Met een Webhook-node ervoor komt een POST-body terecht onder $json.body. Het promptveld ziet er dan als volgt uit.

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.

Stap 4: geef de agent één tool

Een AI Agent-node zonder tool-subnode weigert uit te voeren. Begin met één tool, omdat één werkende tool u meer leert dan vier half geconfigureerde tools.

Koppel een HTTP Request-node aan de Tool-connector van de agent. Configureer deze precies zoals een normale HTTP Request-node en test het eindpunt eerst vanuit een shell.

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

Als die curl-opdracht een fout of een HTML-aanmeldpagina retourneert, mislukt de agent ook. De fout lijkt dan een modelprobleem, terwijl het in werkelijkheid een URL- of authenticatieprobleem is. Los dit op in de shell, niet in de node.

Het veld Description van de tool is geen documentatie voor uw collega's. Dit is het enige wat het model leest wanneer het bepaalt of deze tool relevant is. Beschrijf eenvoudig wat de tool retourneert: "Retourneert de huidige up- of down-status en de duur van de downtime voor één gemonitorde service, als JSON."

Gebruik de expressie $fromAI() als u het model een deel van het verzoek wilt laten invullen. Deze werkt alleen in tools die met een AI Agent-node zijn verbonden. De expressie werkt niet in de Code-tool.

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

De argumenten zijn key, gevolgd door optioneel description, type en defaultValue. De sleutel moet 1 tot 64 tekens bevatten en mag alleen letters, cijfers, underscores en koppeltekens bevatten. Het type is een van string, number, boolean of json en heeft standaard de waarde string. Een uitgebreidere aanroep ziet er als volgt uit.

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

De sleutel is een aanwijzing, geen verwijzing naar bestaande gegevens. $fromAI('service') leest nergens een veld met de naam service. Hiermee krijgt het model de instructie: "produceer een waarde en noem deze service". Het model zoekt vervolgens in het gesprek, de invoergegevens en de resultaten van andere tools naar een geschikte waarde. In een chatworkflow kan het model dit eenvoudig aan de gebruiker vragen.

Stap 5: geheugen en waarom de agent vergeet

Zonder een geheugensubnode begint elk bericht zonder context. Voeg een Simple Memory-subnode toe om de recente conversatie bij te houden.

Deze heeft twee parameters. Session Key bepaalt om welke conversatie het gaat. Twee gebruikers met verschillende sleutels krijgen daardoor een afzonderlijke geschiedenis. Context Window Length bepaalt hoeveel eerdere interacties opnieuw in de prompt worden opgenomen.

Context Window Length bepaalt niet alleen de kwaliteit, maar ook de kosten. Elke onthouden beurt wordt bij elke volgende aanroep opnieuw als invoertoken verzonden. Bij een venster van 20 bij een praatgrage agent betaalt u twintig keer voor dezelfde vroege berichten.

Simple Memory werkt niet in een actieve productie-workflow wanneer n8n in queue mode draait. De geschiedenis staat dan in de eigen gegevens van de workflow en niet in een gedeelde opslag. Gebruik op een instance met queue mode in plaats daarvan de Postgres Chat Memory-subnode. Verbind deze met een database die zowel het hoofdproces als de workers kunnen bereiken.

Stap 6: het systeembericht

Open de Options van de agent en voeg een System Message toe. Hierin staat de taakbeschrijving. Dit is de tekst met de grootste invloed op de workflow.

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" heeft hier een belangrijke functie. Zonder deze instructie slaat een model dat denkt het antwoord al te kennen de tool over en antwoordt het uit het geheugen. Zodra uw infrastructuur verandert, is dat antwoord met grote zekerheid onjuist.

Waarom blijft de agent in een lus draaien en wat stopt dit

Onder Options staat ook Max Iterations, met een standaardwaarde van 10. Eén iteratie bestaat uit één modelaanroep plus één toolresultaat dat weer aan de context wordt toegevoegd. Eén agentuitvoering is dus niet één API-aanroep, maar maximaal tien aanroepen. Elke aanroep bevat de volledige, steeds langer wordende conversatie als invoer.

Verlaag deze waarde. De meeste agents die één tool gebruiken, zijn na twee iteraties klaar. Met een limiet van 3 of 4 verandert u een onbeheersbare lus in een duidelijke fout die u in de uitvoeringslijst kunt zien.

Schakel tijdens het opsporen van problemen Return Intermediate Steps in. De uiteindelijke uitvoer bevat dan ook de toolaanroepen die de agent onderweg heeft gedaan. Zo kunt u onderscheiden of het model de tool nooit heeft aangeroepen of dat de tool niets bruikbaars heeft geretourneerd. Schakel deze optie weer uit voordat u de agent in productie neemt. Deze stappen zijn voor eindgebruikers alleen ruis.

Volg een uitvoering vanuit de shell.

docker compose logs -f n8n

Voorkomen dat een agent ongemerkt kosten maakt

Een agent achter een Chat Trigger heeft een mens die ingrijpt wanneer het antwoord onjuist lijkt. Bij een agent achter een Schedule Trigger kijkt niemand mee. De volledige uitleg staat in Kostenbeheersing voor AI-agents op een VPS die altijd actief is. Vier instellingen doen hier het meeste werk.

• Stel Maximum Number of Tokens op het model-subknooppunt in op een maximumwaarde, zodat geen enkele respons lang kan doorgaan.
• Stel Max Iterations in op het kleinste aantal waarmee de taak nog wordt voltooid.
• Houd toolresponsen klein. Een tool die een JSON-blok van 4,000 regels retourneert, voegt alles daarvan toe aan de volgende modelaanroep en daarna aan elke volgende aanroep binnen dezelfde uitvoering.
• Ga na of de agent überhaupt een schema nodig heeft. Een taak die elke vijf minuten wordt uitgevoerd, start 288 keer per dag. Vermenigvuldig de kosten van één uitvoering met dat aantal.

Deactiveer de workflow terwijl u iteraties uitvoert. Een actieve workflow met een Schedule Trigger blijft werken met de versie die n8n heeft opgeslagen. Dat is niet altijd de versie die op uw scherm staat.

FAQ

Waarom weigert mijn AI Agent-node de uitvoering?

De AI Agent-node vereist een chatmodel-subnode en ten minste één tool-subnode. Een node met een model maar zonder tool mislukt voordat deze een API-aanroep uitvoert. Koppel één tool, zelfs een eenvoudige, en voer de node opnieuw uit.

De agent geeft antwoord, maar roept mijn tool nooit aan. Wat is er mis?

Bijna altijd ligt dit aan het veld Description van de tool. Het model kiest tools door deze beschrijvingen te lezen. Een beschrijving zoals "HTTP Request" geeft niet aan wanneer de tool van toepassing is. Herschrijf de beschrijving zodat deze vermeldt welke gegevens worden geretourneerd en in welke situatie de tool nuttig is. Voeg vervolgens een regel toe aan het System Message waarin u de agent opdraagt deze tool aan te roepen voordat de agent antwoord geeft.

Waarom kost dezelfde vraag per uitvoering een ander bedrag?

Omdat het model het aantal stappen kiest. Bij elke iteratie wordt de volledige conversatie tot dat moment opnieuw verzonden, inclusief eerdere tooluitvoer. Daardoor kost een uitvoering met vier iteraties veel meer dan vier keer één aanroep. Max Iterations bepaalt het maximum. Return Intermediate Steps laat zien hoeveel stappen een specifieke uitvoering daadwerkelijk heeft gebruikt.

Mijn geheugen werkt in de editor, maar niet in productie. Wat is er gewijzigd?

Controleer of de instantie in queue mode wordt uitgevoerd. Simple Memory slaat de geschiedenis op in de uitvoeringsgegevens van de workflow zelf. Deze gegevens blijven niet behouden wanneer de workflow aan een afzonderlijk worker-proces wordt overgedragen. Daardoor raakt een actieve productieworkflow de geschiedenis kwijt. Vervang Simple Memory door de subnode Postgres Chat Memory. Deze bewaart de geschiedenis in de database die door alle workers wordt gedeeld.