Zelf een n8n AI agent bouwen op een 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 sub-nodes: één chatmodel, een of meer tools en optioneel geheugen. U formuleert een doel in begrijpelijke taal, waarna het model beslist welke tools het aanroept en in welke volgorde, totdat het antwoord kan worden gegeven. Alles hieronder betreft de configuratie rondom dat ene concept.

Een chain werkt precies andersom. In een Basic LLM Chain bepaalt u de stappen en vult het model alleen de tekst in. Bij een agent bepaalt het model de stappen zelf; hierdoor kan dezelfde vraag vandaag één model-aanroep kosten en morgen negen. Dat ene verschil bepaalt elke instelling in deze handleiding.

Deze handleiding gaat ervan uit dat n8n al achter HTTPS draait op een machine die u beheert. Is dat niet het geval, begin dan bij self-hosting n8n on Docker with a real certificate, omdat de API-sleutel die u zo gaat opslaan de back-up van de encryptiesleutel vereist waar die handleiding op aandringt. Voor patronen die geen agents gebruiken, zoals webhook-samenvatters en geplande classificaties, zie Claude and n8n workflow patterns.

Controleer uw versie voordat u vertrouwt op de veldnamen in dit document, aangezien 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 per juli 2026. Sinds versie 1.82.0 draait elke AI Agent-node als een Tools Agent, waardoor het oude dropdown-menu voor agent-types niet meer bestaat.

Stap 1: kies de trigger

Voeg voor een gespreksagent een Chat Trigger-node toe. Laat Make Chat Publicly Available uitgeschakeld terwijl u bouwt, zodat alleen het chatvenster van de editor de agent kan bereiken. Schakel deze optie in wanneer de agent gereed is en u een besluit heeft genomen over de authenticatie.

De Chat Trigger geeft de agent een veld genaamd chatInput. Die naam is van belang in stap 3, en het onjuist invoeren hiervan is de meest voorkomende eerste fout.

Gebruik voor een onbeheerde agent in plaats daarvan een Schedule Trigger- of een Webhook-node. Geen van beide genereert chatInput, dus u zult de prompt zelf moeten schrijven.

Stap 2: de model-credential

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

Maak de credential aan via de Anthropic Console op platform.claude.com, onder Settings en vervolgens API Keys. De sleutel wordt slechts eenmaal getoond. API-gebruik wordt per token gefactureerd en staat los van een eventueel Claude.ai-abonnement; het account moet daarom over een ingestelde facturatiemethode beschikken voordat de eerste run plaatsvindt.

Kies het model per agent, niet per bedrijf. Een agent met één tool die informatie opzoekt en rapporteert, werkt prima op Haiku, dat per juli 2026 geprijsd is op $1 per miljoen input-tokens en $5 per miljoen output-tokens. Zodra de agent over meerdere tools beschikt en hiermee moet plannen, stapt u over op Sonnet. De fout die u hiermee voorkomt, is een goedkoop model dat vier keer de verkeerde tool aanroept, wat duurder uitvalt dan een duurder model dat in één keer de juiste tool aanroept.

Stel Maximum Number of Tokens in bij de opties van de sub-node. Dit begrenst de lengte van elk antwoord dat het model genereert. Indien dit op de ruime standaardwaarde blijft staan, kan één verwarde run een zeer lang antwoord produceren waarvoor u wordt gefactureerd.

Een waarschuwing uit de n8n-documentatie waar iedereen tegenaan loopt: expressies binnen een sub-node worden altijd opgelost op basis van het eerste input-item, nooit per item. Plaats expressies die per item moeten gelden in de prompt-velden van de root-node.

Stap 3: de prompt die de agent ontvangt

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

• Take from previous node automatically verwacht een inkomend veld genaamd 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 schrijft. Dit is de juiste keuze achter een Schedule Trigger of een Webhook-knooppunt.

Met een Webhook-knooppunt ervoor komt de POST-body terecht onder $json.body, waardoor het promptveld er als volgt uitziet.

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 te draaien. Begin met één tool, omdat één werkende tool u meer leert dan vier half geconfigureerde exemplaren.

Koppel een HTTP Request-node aan de Tool-connector van de agent. Configureer deze exact zoals u een normale HTTP Request-node zou configureren 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 foutmelding of een HTML-inlogpagina retourneert, zal de agent ook falen. De foutmelding lijkt dan op een probleem met het model, 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. Het is het enige dat het model leest wanneer het beslist of deze tool relevant is. Schrijf het als een feitelijke omschrijving van wat er wordt geretourneerd: "Returns the current up or down state and the downtime duration for one monitored service, as JSON."

Gebruik de $fromAI()-expressie om het model een deel van het verzoek te laten invullen. Dit werkt alleen in tools die verbonden zijn met een AI Agent-node en werkt niet in de Code-tool.

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

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

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

De key is een hint, geen verwijzing naar bestaande data. $fromAI('service') leest nergens een veld genaamd service uit. Het vertelt het model: "produceer een waarde en noem deze service". Het model doorzoekt vervolgens het gesprek, de invoerdata en andere toolresultaten om er een te vinden. In een chat-workflow kan het model de gebruiker er simpelweg om vragen.

Zoeken op het web is doorgaans de tweede tool. Aangezien dit ook slechts een HTTP-eindpunt is, kunt u deze zelfde node laten verwijzen naar uw eigen SearXNG-instantie in plaats van een betaalde zoek-API, mits u elke pagina die de tool ophaalt behandelt als niet-vertrouwde tekst die zich nu in uw prompt bevindt.

Stap 5: geheugen, en waarom de agent dingen vergeet

Zonder een geheugen-subnode begint elk bericht vanaf nul. Koppel een Simple Memory-subnode om het recente gesprek vast te houden.

Deze heeft twee parameters. Session Key bepaalt om welk gesprek het gaat, zodat twee gebruikers met verschillende sleutels gescheiden geschiedenissen krijgen. Context Window Length bepaalt hoeveel eerdere interacties opnieuw in de prompt worden ingevoegd.

Context Window Length is zowel een knop voor kosten als voor kwaliteit, omdat elke onthouden interactie bij elke latere aanroep opnieuw als input-tokens wordt verstuurd. Een window van 20 bij een spraakzame agent betekent dat u twintig keer betaalt voor dezelfde vroege berichten.

Simple Memory werkt niet in een actieve productie-workflow wanneer n8n in queue-modus draait, omdat de geschiedenis in de eigen data van de workflow leeft in plaats van in een gedeelde opslag. Gebruik op een instantie in queue-modus in plaats daarvan de Postgres Chat Memory-subnode en verwijs deze naar een database die zowel door het hoofdproces als door de workers bereikt kan worden.

Stap 6: het Systeembericht

Open de Options van de agent en voeg een System Message toe. Hier plaatst u de functiebeschrijving; dit is de tekst met de grootste impact in 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.

"Roep altijd de status tool aan voordat u antwoordt" is hier een essentiële instructie. Zonder deze instructie zal een model dat denkt het antwoord al te kennen de tool overslaan en antwoorden vanuit het geheugen. Dit leidt tot zelfverzekerde maar onjuiste antwoorden zodra uw infrastructuur wijzigt.

Waarom de agent in een lus raakt en wat dit stopt

Onder Options vindt u ook Max Iterations, dat standaard op 10 staat. Eén iteratie bestaat uit één modelaanroep plus één toolresultaat dat wordt teruggekoppeld in de context. Een enkele agent-run is dus niet één API-aanroep, maar maximaal tien, waarbij elke aanroep het volledige, groeiende gesprek als input meeneemt.

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

Schakel tijdens het debuggen Return Intermediate Steps in. De uiteindelijke output bevat dan de tool-aanroepen die de agent onderweg heeft gedaan. Hiermee kunt u het verschil zien tussen "het model heeft de tool nooit aangeroepen" en "de tool gaf niets nuttigs terug". Schakel dit weer uit voordat u live gaat, omdat deze stappen ruis zijn voor de eindgebruiker.

Volg een run vanuit de shell.

docker compose logs -f n8n

Voorkomen dat een onbeheerde agent ongemerkt kosten maakt

Een agent achter een Chat Trigger heeft een mens die de uitvoering stopt zodra het antwoord onjuist lijkt. Bij een agent achter een Schedule Trigger kijkt niemand mee. Hier bewaakt u het modelverbruik, niet de licentiekosten, omdat de agent-, tool- en memory-nodes allemaal werken in de gratis self-hosted edition en de functies waarvoor wel een betaalde sleutel nodig is, voornamelijk op teams en governance zijn gericht. De volledige behandeling staat in Kostenbeheersing voor AI-agents op een altijd actieve VPS. Met vier instellingen bereikt u hier het meeste resultaat.

• Beperk het Maximum Number of Tokens in de sub-node van het model, zodat een enkel antwoord niet te lang kan worden.
• Stel Max Iterations in op het laagste aantal waarmee de taak nog steeds wordt voltooid.
• Houd tool-antwoorden klein. Een tool die een JSON-blob van 4.000 regels teruggeeft, plaatst deze volledig in de volgende model-aanroep, en daarna in elke volgende aanroep binnen dezelfde run.
• Vraag uzelf af of de agent überhaupt een schema nodig heeft. Een taak die elke vijf minuten draait, wordt 288 keer per dag uitgevoerd. Wat één run ook kost, dat is het bedrag waarmee u moet vermenigvuldigen.

Deactiveer de workflow terwijl u wijzigingen aanbrengt. Een actieve workflow met een Schedule Trigger blijft draaien op de versie die n8n heeft opgeslagen, wat niet altijd de versie is die u op uw scherm ziet.

FAQ

Waarom weigert mijn AI Agent-node uit te voeren?

De AI Agent-node vereist een chatmodel-subnode en ten minste één tool-subnode. Een node met een model maar zonder tool faalt voordat er een API-aanroep wordt gedaan. Koppel één tool, zelfs een triviale, en voer de actie opnieuw uit.

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

Dit ligt bijna altijd aan het veld Description van de tool. Het model kiest tools door deze beschrijvingen te lezen; een beschrijving als "HTTP Request" vertelt het model niets over wanneer de tool moet worden toegepast. Herschrijf de beschrijving zodat duidelijk is welke gegevens worden geretourneerd en in welke situatie de tool nuttig is. Voeg vervolgens een regel toe aan het System Message waarin de agent wordt geïnstrueerd om die tool aan te roepen voordat er een antwoord wordt gegeven.

Waarom kost dezelfde vraag elke keer een ander bedrag?

Omdat het model zelf het aantal stappen kiest. Elke iteratie verstuurt het volledige gesprek tot dan toe opnieuw, inclusief de eerdere output van de tool. Een run die vier iteraties vereist, kost daarom veel meer dan vier keer een enkele aanroep. Max Iterations vormt het maximum hiervoor, en Return Intermediate Steps laat zien hoeveel stappen een specifieke run daadwerkelijk heeft gebruikt.

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

Controleer of de instantie in queue-modus draait. Simple Memory slaat de geschiedenis op in de eigen uitvoeringsgegevens van de workflow. Deze gegevens overleven het niet wanneer ze worden overgedragen aan een apart worker-proces, waardoor een actieve productie-workflow de geschiedenis verliest. Vervang dit door de Postgres Chat Memory-subnode, die de geschiedenis opslaat in de database die door alle workers wordt gedeeld.