n8n AI-agent bouwen op uw eigen VPS
Bouw een werkende n8n AI-agent met de AI Agent-node, Claude, een HTTP Request-tool, geheugen, trigger en instellingen die kosten begrenzen.
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 modelaanroep kosten en morgen negen. Dat ene verschil vormt de basis voor elke instelling in deze handleiding. Als deze lus als concept nieuw voor u is, in plaats van enkel als n8n-functie, is het de moeite waard om er eens een handmatig te schrijven voordat u deze uit nodes opbouwt. De node verbergt namelijk precies dat onderdeel waar u de rest van deze handleiding over zult moeten nadenken.
Deze handleiding gaat ervan uit dat n8n al achter HTTPS draait op een machine die u beheert. Is dat niet het geval, begin dan met n8n zelf hosten op Docker met een geldig certificaat, 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, raadpleeg Claude en n8n workflow-patronen.
Controleer uw versie voordat u vertrouwt op de veldnamen in dit document, aangezien n8n de AI-nodes regelmatig wijzigt.
docker compose exec n8n n8n --versionVersie 1.82.0 heeft de instelling voor het agent-type als verouderd gemarkeerd ten gunste van de Tools Agent. Legacy v1-nodes bevatten de instelling nog wel; de documentatie van n8n voorziet de verwijdering van die node-versie in n8n 3.0.
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-referentie
Plaats een AI Agent-node op het canvas. n8n toont direct een lege Chat Model-connector eronder. Koppel hier een Anthropic Chat Model-sub-node aan.
Maak de referentie aan via de Claude Console op platform.claude.com, onder Settings en vervolgens API keys. De sleutel wordt eenmalig getoond. De Console vraagt u ook om een verloopdatum te kiezen bij het aanmaken van een sleutel. Een onbeheerde agent stopt met werken zodra de sleutel verloopt; noteer deze datum dus op een plek waar u deze terugvindt. Gebruik voor een onbeheerde agent een service account-sleutel die is beperkt tot een workspace, zodat verzoeken geen aparte workspace-header vereisen.
API-gebruik wordt per token gefactureerd. Hoe u hiervoor betaalt, hangt af van uw Claude-abonnement, zoals dat geldt op 31 oktober 2026. Max-, Ultra- en Team-abonnementen bevatten maandelijkse API-credits: $100 bij Max, $200 bij Ultra en tot $500 gebundeld bij Team. U claimt deze door een Console-organisatie te koppelen aan het abonnement via Settings > Billing bij Max of Ultra, of Organization settings > Billing bij Team. U hoeft in de Console geen betaalmethode toe te voegen. Nieuwe abonnees kunnen deze na 7 dagen in het abonnement claimen. Ongebruikte credits vervallen aan het einde van elke factuurcyclus, of maandelijks bij jaarabonnementen. Wanneer de inbegrepen credits op zijn, gaan verzoeken door tegen aangekochte credits; auto-reload kan meer aankopen en gefactureerde organisaties krijgen het meerverbruik in rekening gebracht. Verzoeken stoppen wanneer een prepaid-organisatie geen credits meer heeft; API-gebruik wordt nooit in rekening gebracht bij uw Claude-abonnement. Free-, Pro- en Enterprise-abonnementen bevatten geen maandelijkse API-credits; bij deze abonnementen wordt de API apart van het abonnement gefactureerd.
Kies het model per agent, niet per bedrijf. Een agent met één tool die iets opzoekt en rapporteert, werkt prima op Haiku. De huidige versie, Haiku 5.5, kost $0.10 per miljoen input-tokens en $0.50 per miljoen output-tokens per 12 oktober 2026. Dit stijgt naar $0.50 en $2.50 voor elk verzoek waarvan de prompt de 100,000 tokens overschrijdt, wat kan gebeuren door een lang geheugenvenster en grote tool-resultaten. Zodra de agent over meerdere tools beschikt en hiermee moet plannen, stapt u over naar Sonnet. De fout die u wilt vermijden, is een goedkoop model dat vier keer de verkeerde tool aanroept; dit kost meer dan het dure model dat éé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. Als u dit op de standaardwaarde laat staan, kan een verwarde run een zeer lang antwoord produceren waarvoor u betaalt.
Eén 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 per item in de prompt-velden van de root-node.
Stap 3: de prompt die de agent ontvangt
Open de AI Agent-node. De parameter Source for Prompt (User Message) heeft twee instellingen.
- Connected Chat Trigger Node verwacht een inkomend veld genaamd
chatInput. Dit is de juiste keuze achter een Chat Trigger. - Define below toont een Prompt (User Message)-veld waarin u statische tekst of een expressie schrijft. Dit is de juiste keuze achter een Schedule Trigger of een Webhook-node.
Met een Webhook-node ervoor komt de POST-body terecht onder $json.body, waardoor het prompt-veld 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
De documentatie van n8n stelt dat u ten minste één tool-subnode moet verbinden met een AI Agent-node, hoewel de huidige node-code (versie 3.1) alleen weigert te draaien zonder chatmodel. Begin hoe dan ook met één tool, omdat één werkende tool u meer leert dan vier half geconfigureerde, en een agent zonder tool slechts een keten is die meer kost.
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 dat eindpunt eerst vanuit een shell.
curl -s -H 'Accept: application/json' \
https://status.example.com/api/status/database | head -c 400Als die curl een foutmelding of een HTML-inlogpagina retourneert, zal de agent ook falen. De foutmelding zal lijken op 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. Het model leest dit samen met de naam van de tool en het parameterschema wanneer het beslist of deze tool relevant is. Schrijf het als een feitelijke verklaring van wat er wordt geretourneerd: "Retourneert de huidige up- of down-status en de downtime-duur voor één gemonitorde service, als 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 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", waarna het model de conversatie, de invoerdata en andere toolresultaten doorzoekt om er een te vinden. In een chat-workflow kan het simpelweg de gebruiker vragen.
Zoeken op het web is meestal de tweede tool, en aangezien dit slechts een ander HTTP-eindpunt is, kunt u deze zelfde node richten op uw eigen SearXNG-instantie in plaats van een betaalde zoek-API, mits u elke pagina die het teruggeeft 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 afzonderlijke geschiedenissen krijgen. Context Window Length bepaalt hoeveel eerdere interacties opnieuw in de prompt worden afgespeeld.
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 verzonden. Een venster 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. Dit komt doordat de geschiedenis wordt opgeslagen in een proces-lokale singleton Map, geindexeerd op workflow- en sessie-ID's, en workers delen dat geheugen niet. Gebruik op een instantie in queue-modus in plaats daarvan de Postgres Chat Memory-subnode en verwijs deze naar 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. 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 loopt de agent in een lus en wat stopt dit
Onder Options vindt u ook Max Iterations, dat standaard op 10 staat. Eén iteratie is één modelaanroep, die ofwel tools aanvraagt of het definitieve antwoord geeft; toolresultaten worden teruggevoerd in de volgende aanroep. Een enkele agent-run is dus niet één API-aanroep, maar maximaal tien, waarbij elke aanroep het volledige groeiende gesprek als invoer meeneemt.
Verlaag deze waarde. De meeste agents die één tool gebruiken, zijn in twee iteraties klaar. 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 uitvoer 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 vormen voor de eindgebruiker.
Volg een run vanuit de shell.
docker compose logs -f n8nVoorkomen dat een onbeheerde agent ongemerkt kosten maakt
Een agent achter een Chat Trigger heeft een menselijke gebruiker die de agent stopt wanneer het antwoord onjuist lijkt. Een agent achter een Schedule Trigger wordt door niemand gecontroleerd. Waar u hier op let, zijn de kosten voor het model in plaats van licentiekosten, aangezien de agent-, tool- en memory-nodes allemaal werken in de gratis self-hosted editie, en de functies waarvoor wel een betaalde sleutel nodig is, zijn grotendeels gericht op team- en governance-beheer. De volledige aanpak staat in AI agent kostenbeheersing op een altijd actieve VPS. Vier instellingen doen hier het meeste werk.
- Begrens het Maximum Number of Tokens op de model-sub-node, zodat geen enkel antwoord buitensporig lang kan worden.
- Stel Max Iterations in op het kleinste aantal dat de taak nog steeds voltooit.
- Houd tool-antwoorden klein. Een tool die een JSON-blob van 4.000 regels teruggeeft, plaatst deze volledig in de volgende model-aanroep, en vervolgens in elke daaropvolgende aanroep in 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 vermenigvuldigt.
Haal de workflow van de publicatie af terwijl u wijzigingen aanbrengt, of onthoud in ieder geval welke versie live staat. Een gepubliceerde workflow met een Schedule Trigger blijft de versie draaien die u als laatste heeft gepubliceerd, niet het concept op uw scherm, omdat n8n uw bewerkingen in concept houdt totdat u opnieuw publiceert.
FAQ
Waarom weigert mijn AI Agent node uit te voeren?
Controleer eerst de connectoren. De AI Agent node vereist een chatmodel-subnode; zonder deze stopt de node met de melding "Please connect a model to the Chat Model input" voordat er een API-aanroep wordt gedaan. De documentatie van n8n vermeldt ook dat ten minste één tool-subnode vereist is. Als het model is verbonden en de node nog steeds weigert, voeg dan een tool toe, zelfs een eenvoudige, en voer de node 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 wordt welke data wordt geretourneerd en in welke situatie de tool nuttig is. Voeg vervolgens een regel toe aan het System Message waarin u de agent instrueert om die tool aan te roepen voordat er antwoord wordt gegeven.
Waarom kost dezelfde vraag elke keer een ander bedrag?
Dit komt doordat het model zelf het aantal stappen kiest. Elke iteratie verstuurt het volledige gesprek tot dat moment opnieuw, inclusief de output van eerdere tools. Een uitvoering die vier iteraties vereist, brengt dus de input- en output-tokens voor alle vier de aanroepen in rekening. Max Iterations vormt het maximum hiervan, en 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 veranderd?
Controleer of de instantie in queue mode draait. Simple Memory slaat de geschiedenis op in een proces-lokale singleton Map, gekoppeld aan workflow- en sessie-ID's; afzonderlijke worker-processen delen dit geheugen niet. Vervang dit door de Postgres Chat Memory subnode, die de geschiedenis opslaat in de database die door alle workers wordt gedeeld.