n8n AI-Agent auf eigenem VPS einrichten

Was ein n8n-AI-Agent ist und wie er sich von einer Chain unterscheidet

Ein n8n-AI-Agent ist ein einzelner AI Agent-Node mit daran angeschlossenen Sub-Nodes: ein Chat-Modell, ein oder mehrere Tools und optional ein Memory. Sie geben ein Ziel in natürlicher Sprache vor. Das Modell entscheidet, welche Tools in welcher Reihenfolge aufgerufen werden, bis es eine Antwort geben kann. Alles Folgende beschreibt die Konfiguration rund um diese eine Idee.

Eine Chain funktioniert umgekehrt. In einer Basic LLM Chain legen Sie die Schritte fest, und das Modell füllt nur den Text aus. Bei einem Agenten legt das Modell die Schritte fest. Daher kann dieselbe Frage heute einen Modellaufruf und morgen neun Modellaufrufe verursachen. Dieser eine Unterschied bestimmt jede Einstellung in diesem Leitfaden. Wenn dieses Schleifenprinzip für Sie als Konzept und nicht nur als n8n-Funktion neu ist, sollten Sie es einmal von Hand implementieren, bevor Sie es aus Nodes zusammensetzen. Der Node verbirgt genau den Teil, dessen Verhalten Sie im restlichen Leitfaden analysieren werden.

Dabei wird vorausgesetzt, dass n8n bereits hinter HTTPS auf einer von Ihnen verwalteten Maschine läuft. Falls nicht, beginnen Sie mit dem Self-Hosting von n8n mit Docker und einem gültigen Zertifikat, weil der API-Schlüssel, den Sie gleich speichern, die in diesem Leitfaden geforderte Sicherung des Encryption Keys benötigt. Informationen zu Mustern ohne Agenten, etwa Webhook-Zusammenfassungen und geplanten Klassifizierungen, finden Sie unter Claude- und n8n-Workflow-Mustern.

Prüfen Sie Ihre Version, bevor Sie sich auf die hier genannten Feldnamen verlassen, da n8n die AI-Nodes häufig ändert.

docker compose exec n8n n8n --version

Version 1.82.0 hat die Einstellung für den Agent-Typ zugunsten des Tools Agent als veraltet markiert. Legacy-v1-Nodes enthalten diese Einstellung weiterhin. Laut n8n-Dokumentation soll diese Node-Version mit n8n 3.0 entfernt werden.

Schritt 1: Den Trigger auswählen

Fügen Sie für einen Konversationsagenten einen Chat Trigger-Node hinzu. Lassen Sie Make Chat Publicly Available während der Entwicklung deaktiviert, damit nur das Chat-Panel des Editors darauf zugreifen kann. Aktivieren Sie die Option, wenn der Agent fertig ist und Sie die Authentifizierung festgelegt haben.

Der Chat Trigger übergibt dem Agenten ein Feld namens chatInput. Dieser Name ist in Schritt 3 relevant. Ein falscher Name ist die häufigste Ursache für den ersten Fehler.

Verwenden Sie für einen unbeaufsichtigten Agenten stattdessen einen Schedule Trigger- oder Webhook-Node. Keiner dieser Nodes erzeugt chatInput. Daher müssen Sie den Prompt selbst schreiben.

Schritt 2: Die Modellanmeldedaten

Fügen Sie einen AI Agent-Node auf der Arbeitsfläche ein. n8n zeigt darunter sofort einen leeren Chat Model-Connector an. Fügen Sie dort einen Anthropic Chat Model-Subnode an.

Erstellen Sie die Anmeldedaten in der Claude Console unter platform.claude.com. Öffnen Sie dazu Settings und anschließend API keys. Der Schlüssel wird nur einmal angezeigt. Beim Erstellen eines Schlüssels fordert die Console außerdem zur Auswahl eines Ablaufdatums auf. Ein unbeaufsichtigter Agent funktioniert ab dem Tag, an dem sein Schlüssel abläuft, nicht mehr. Notieren Sie sich dieses Datum daher an einer Stelle, an der Sie es sehen. Verwenden Sie für einen unbeaufsichtigten Agenten einen auf einen Workspace begrenzten Service-Account-Schlüssel, damit Anfragen keinen separaten Workspace-Header benötigen.

Die API-Nutzung wird pro Token abgerechnet. Die Zahlungsweise hängt vom Claude-Tarif ab, Stand 31 October 2026. Die Tarife Max, Ultra und Team enthalten monatliche API-Guthaben: $100 bei Max, $200 bei Ultra und bis zu $500 als gemeinsames Guthaben bei Team. Sie aktivieren diese Guthaben, indem Sie unter Settings > Billing bei Max oder Ultra beziehungsweise unter Organization settings > Billing bei Team eine Console-Organisation mit dem Tarif verknüpfen. In der Console müssen Sie keine Zahlungsmethode hinterlegen. Neue Abonnenten können das Guthaben nach 7 Tagen im Tarif aktivieren. Nicht verwendete Guthaben verfallen am Ende jedes Abrechnungszeitraums, bei Jahrestarifen monatlich. Wenn das enthaltene Guthaben aufgebraucht ist, werden Anfragen über gekaufte Guthaben abgerechnet. Auto-Reload kann weitere Guthaben kaufen. Organisationen mit Rechnungsabrechnung zahlen für die zusätzliche Nutzung. Anfragen werden angehalten, wenn eine Organisation mit Vorauszahlung kein Guthaben mehr hat. Die API-Nutzung wird niemals Ihrem Claude-Tarif belastet. Die Tarife Free, Pro und Enterprise enthalten keine monatlichen API-Guthaben. Bei diesen Tarifen wird die API daher getrennt vom Abonnement abgerechnet.

Wählen Sie das Modell für jeden Agenten einzeln aus, nicht für das gesamte Unternehmen. Ein Agent mit einem Tool, der Informationen abruft und ausgibt, funktioniert mit Haiku problemlos. Die aktuelle Version Haiku 5.5 wird Stand 12 October 2026 mit $0.10 pro Million Eingabetokens und $0.50 pro Million Ausgabetokens angegeben. Für Anfragen, deren Prompt mehr als 100,000 Tokens umfasst, steigen die Preise auf $0.50 beziehungsweise $2.50. Ein langer Memory-Kontext und große Tool-Ergebnisse können diese Grenze überschreiten. Sobald der Agent mehrere Tools verwendet und deren Ergebnisse einplanen muss, wechseln Sie zu Sonnet. Das Problem, das Sie vermeiden möchten, ist ein günstiges Modell, das viermal das falsche Tool aufruft. Das kann mehr kosten als ein teures Modell, das einmal das richtige Tool aufruft.

Legen Sie in den Optionen des Subnodes Maximum Number of Tokens fest. Damit wird die Länge jeder vom Modell erzeugten Antwort begrenzt. Bei einem hohen Standardwert kann ein einzelner fehlerhafter Lauf eine sehr lange Antwort erzeugen und entsprechend Kosten verursachen.

Ein Hinweis aus der n8n-Dokumentation wird häufig übersehen: Ausdrücke innerhalb eines Subnodes werden immer anhand des ersten Eingabeelements aufgelöst, niemals für jedes Element einzeln. Platzieren Sie Ausdrücke, die sich auf einzelne Elemente beziehen, in den Prompt-Feldern des Root-Nodes.

Schritt 3: Die Eingabeaufforderung, die der Agent erhält

Öffnen Sie den Knoten AI Agent. Der Parameter Source for Prompt (User Message) bietet zwei Einstellungen.

• Connected Chat Trigger Node erwartet ein eingehendes Feld namens chatInput. Diese Einstellung ist hinter einem Chat Trigger die richtige Wahl.
• Define below blendet ein Feld Prompt (User Message) ein, in das Sie statischen Text oder einen Ausdruck schreiben. Diese Einstellung ist hinter einem Schedule Trigger oder einem Webhook-Knoten die richtige Wahl.

Bei einem vorgeschalteten Webhook-Knoten wird der POST-Body unter $json.body abgelegt. Das Eingabefeld für die Eingabeaufforderung sieht dann so aus.

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.

Schritt 4: Geben Sie dem Agenten ein Tool

In der n8n-Dokumentation steht, dass Sie mindestens ein Tool-Sub-Node mit einem AI Agent-Node verbinden müssen. Der aktuelle Node-Code (Version 3.1) verweigert die Ausführung jedoch nur, wenn kein Chat-Modell vorhanden ist. Beginnen Sie trotzdem mit einem Tool. Ein einzelnes funktionierendes Tool liefert mehr Erkenntnisse als vier halb konfigurierte Tools. Ein Agent ohne Tool ist außerdem nur eine Kette, die mehr kostet.

Verbinden Sie einen HTTP Request-Node mit dem Tool-Anschluss des Agenten. Konfigurieren Sie ihn genau wie einen normalen HTTP Request-Node. Testen Sie den Endpunkt anschließend zuerst aus einer Shell.

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

Wenn curl einen Fehler oder eine HTML-Anmeldeseite zurückgibt, schlägt auch der Agent fehl. Der Fehler sieht dann wie ein Modellproblem aus, ist aber tatsächlich ein URL- oder Authentifizierungsproblem. Beheben Sie es in der Shell, nicht im Node.

Das Feld Description des Tools ist keine Dokumentation für Ihre Kollegen. Das Modell liest den Inhalt zusammen mit dem Namen und dem Parameterschema des Tools, wenn es entscheidet, ob dieses Tool relevant ist. Formulieren Sie eine einfache Aussage darüber, was zurückgegeben wird: „Gibt den aktuellen Status (up oder down) und die Dauer des Ausfalls für einen überwachten Dienst als JSON zurück.“

Damit das Modell einen Teil der Anfrage ausfüllen kann, verwenden Sie den Ausdruck $fromAI(). Er funktioniert nur in Tools, die mit einem AI Agent-Node verbunden sind, und nicht im Code-Tool.

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

Die Argumente sind key, anschließend optional description, type und defaultValue. Der Schlüssel muss 1 bis 64 Zeichen lang sein und darf Buchstaben, Ziffern, Unterstriche und Bindestriche enthalten. Der Typ muss string, number, boolean oder json sein. Standardmäßig wird string verwendet. Ein vollständigerer Aufruf sieht folgendermaßen aus.

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

Der Schlüssel ist ein Hinweis und kein Verweis auf bereits vorhandene Daten. $fromAI('service') liest nicht irgendwo ein Feld namens service. Der Ausdruck weist das Modell an: „Erzeuge einen Wert und nenne ihn service.“ Das Modell sucht anschließend in der Konversation, den Eingabedaten und den Ergebnissen anderer Tools nach einem passenden Wert. In einem Chat-Workflow fragt es möglicherweise einfach den Benutzer.

Die Websuche ist das übliche zweite Tool. Da sie nur ein weiterer HTTP-Endpunkt ist, können Sie denselben Node auf Ihre eigene SearXNG-Instanz statt auf eine kostenpflichtige Such-API verweisen. Behandeln Sie dabei jede zurückgegebene Seite als nicht vertrauenswürdigen Text, der sich nun innerhalb Ihres Prompts befindet.

Schritt 5: Speicher und warum der Agent vergisst

Ohne einen Memory-Sub-Node beginnt jede Nachricht ohne Kontext. Verbinden Sie einen Simple Memory-Sub-Node, um den bisherigen Gesprächsverlauf zu speichern.

Er hat zwei Parameter. Session Key legt fest, zu welcher Unterhaltung die Nachricht gehört. Zwei Benutzer mit unterschiedlichen Schlüsseln erhalten daher getrennte Verläufe. Context Window Length legt fest, wie viele vorherige Interaktionen erneut in den Prompt übernommen werden.

Context Window Length beeinflusst die Kosten ebenso stark wie die Qualität. Jede gespeicherte Interaktion wird bei jedem späteren Aufruf erneut als Input-Token übertragen. Bei einem gesprächigen Agenten mit einem Fenster von 20 bezahlen Sie daher für dieselben frühen Nachrichten zwanzigmal.

Simple Memory funktioniert in einem aktiven Produktions-Workflow nicht, wenn n8n im Queue-Modus ausgeführt wird. Es speichert den Verlauf in einer prozesslokalen Singleton-Map, die nach Workflow- und Sitzungs-IDs indiziert ist. Die Worker teilen diesen Speicher jedoch nicht. Verwenden Sie bei einer Instanz im Queue-Modus stattdessen den Postgres Chat Memory-Sub-Node. Verweisen Sie ihn auf eine Datenbank, die sowohl der Hauptprozess als auch die Worker erreichen können.

Schritt 6: Die Systemnachricht

Öffnen Sie die Options des Agenten und fügen Sie eine System Message hinzu. Hier wird die Aufgabenbeschreibung hinterlegt. Dieser Text hat im gesamten Ablauf die größte Wirkung.

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“ erfüllt dabei eine wichtige Funktion. Ohne diese Vorgabe überspringt ein Modell, das die Antwort bereits zu kennen glaubt, das Tool und antwortet aus dem Gedächtnis. Sobald sich Ihre Infrastruktur ändert, ist diese Antwort mit hoher Wahrscheinlichkeit falsch.

Warum wiederholt sich die Agent-Schleife, und was beendet sie?

Unter Options finden Sie außerdem Max Iterations. Der Standardwert ist 10. Eine Iteration entspricht einem Modellaufruf. Dabei fordert das Modell entweder Tools an oder gibt die endgültige Antwort zurück. Die Tool-Ergebnisse fließen in den nächsten Aufruf ein. Ein einzelner Agent-Lauf besteht daher nicht aus einem API-Aufruf, sondern aus bis zu zehn Aufrufen. Jeder Aufruf enthält die gesamte bisher angewachsene Konversation als Eingabe.

Setzen Sie den Wert herab. Die meisten Agenten, die nur ein Tool verwenden, werden in zwei Iterationen fertig. Ein Limit von 3 oder 4 macht aus einer Endlosschleife einen kontrolliert fehlschlagenden Lauf, den Sie in der Ausführungsliste sehen.

Aktivieren Sie während der Fehlersuche Return Intermediate Steps. Die endgültige Ausgabe enthält dann die Tool-Aufrufe, die der Agent auf dem Weg ausgeführt hat. Dadurch können Sie unterscheiden, ob das Modell das Tool nie aufgerufen hat oder ob das Tool keine verwertbaren Ergebnisse geliefert hat. Deaktivieren Sie die Option vor dem produktiven Einsatz wieder. Für Endbenutzer sind diese Zwischenschritte nur störende Zusatzinformationen.

Beobachten Sie einen Lauf aus der Shell.

docker compose logs -f n8n

Einen unbeaufsichtigten Agenten von unbemerkten Ausgaben abhalten

Ein Agent hinter einem Chat Trigger hat einen Menschen als Aufsicht. Dieser Mensch stoppt ihn, wenn die Antwort falsch aussieht. Ein Agent hinter einem Schedule Trigger wird von niemandem überwacht. Hier geht es um die Ausgaben für das Modell, nicht um Lizenzkosten, weil die Agent-, Tool- und Memory-Nodes alle in der kostenlosen selbst gehosteten Edition funktionieren und die Funktionen, die tatsächlich einen kostenpflichtigen Schlüssel benötigen, überwiegend Team- und Governance-Funktionen sind. Eine vollständige Erläuterung finden Sie unter Kostenkontrolle für AI Agents auf einem dauerhaft laufenden VPS. Vier Einstellungen leisten dabei den größten Teil der Arbeit.

• Begrenzen Sie Maximum Number of Tokens im Modell-Subnode, damit keine einzelne Antwort unnötig lang wird.
• Setzen Sie Max Iterations auf die kleinste Anzahl, mit der die Aufgabe noch abgeschlossen wird.
• Halten Sie Tool-Antworten klein. Ein Tool, das ein JSON-Objekt mit 4,000 Zeilen zurückgibt, übergibt den gesamten Inhalt an den nächsten Modellaufruf und danach an jeden weiteren Aufruf desselben Laufs.
• Prüfen Sie, ob der Agent überhaupt einen Zeitplan benötigt. Ein Job, der alle fünf Minuten ausgeführt wird, startet 288-mal pro Tag. Multiplizieren Sie die Kosten eines einzelnen Laufs mit dieser Anzahl.

Heben Sie die Veröffentlichung des Workflows während der Iteration auf. Merken Sie sich zumindest, welche Version aktiv ist. Ein veröffentlichter Workflow mit einem Schedule Trigger führt weiterhin die zuletzt veröffentlichte Version aus, nicht den Entwurf auf Ihrem Bildschirm, weil n8n Ihre Änderungen als Entwurf speichert, bis Sie sie erneut veröffentlichen.

FAQ

Warum führt mein AI Agent-Knoten die Ausführung nicht aus?

Prüfen Sie zuerst die Verbindungen. Der AI Agent-Knoten benötigt einen Chat-Modell-Subknoten. Ohne diesen bricht er mit der Meldung "Please connect a model to the Chat Model input" ab, bevor er einen API-Aufruf ausführt. In der n8n-Dokumentation ist außerdem mindestens ein Tool-Subknoten als erforderlich angegeben. Wenn das Modell verbunden ist und der Knoten weiterhin die Ausführung verweigert, fügen Sie ein Tool hinzu, auch wenn es nur eine einfache Funktion hat, und führen Sie den Knoten erneut aus.

Der Agent antwortet, ruft mein Tool aber nie auf. Woran liegt das?

Fast immer liegt es am Feld Description des Tools. Das Modell wählt Tools anhand dieser Beschreibungen aus. Eine Beschreibung wie "HTTP Request" sagt ihm nicht, wann das Tool geeignet ist. Formulieren Sie die Beschreibung so um, dass sie angibt, welche Daten zurückgegeben werden und in welcher Situation das Tool nützlich ist. Ergänzen Sie anschließend im System Message eine Zeile, die den Agent anweist, dieses Tool vor der Antwort aufzurufen.

Warum kostet dieselbe Frage bei jeder Ausführung unterschiedlich viel?

Weil das Modell die Anzahl der Schritte auswählt. Bei jeder Iteration wird die bisherige vollständige Konversation erneut gesendet, einschließlich vorheriger Tool-Ausgaben. Eine Ausführung mit vier Iterationen berechnet daher die Eingabe- und Ausgabetokens für alle vier Aufrufe. Max Iterations legt die Obergrenze fest. Return Intermediate Steps zeigt, wie viele Schritte eine bestimmte Ausführung tatsächlich verwendet hat.

Meine Memory funktioniert im Editor, aber nicht in der Produktion. Was hat sich geändert?

Prüfen Sie, ob die Instanz im Queue-Modus läuft. Simple Memory speichert den Verlauf in einer prozesslokalen Singleton-Map, die nach Workflow- und Session-IDs indiziert ist. Separate Worker-Prozesse teilen diese Map nicht. Verwenden Sie stattdessen den Subknoten Postgres Chat Memory. Er speichert den Verlauf in der Datenbank, die von allen Workern gemeinsam verwendet wird.