n8n AI Agent auf dem eigenen 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 Chatmodell, ein oder mehrere Tools und optional ein Memory. Sie geben ein Ziel in Klartext vor. Das Modell entscheidet, welche Tools es in welcher Reihenfolge aufruft, bis es antworten 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. Das Modell füllt nur den Text aus. Bei einem Agent entscheidet das Modell über die Schritte. Deshalb kann dieselbe Frage heute einen Modellaufruf und morgen neun Modellaufrufe verursachen. Dieser eine Unterschied bestimmt jede Einstellung in diesem Leitfaden.

Vorausgesetzt wird, dass n8n bereits hinter HTTPS auf einer von Ihnen kontrollierten Maschine läuft. Falls nicht, beginnen Sie mit n8n mit Docker und einem echten Zertifikat selbst hosten, weil der API-Schlüssel, den Sie gleich speichern, die in diesem Leitfaden geforderte Sicherung des encryption-key benötigt. Informationen zu Mustern ohne Agent, darunter Webhook-Zusammenfassungen und geplante Klassifizierungen, finden Sie unter Claude- und n8n-Workflow-Muster.

Prüfen Sie Ihre Version, bevor Sie einem Feldnamen hier vertrauen. n8n ändert die AI-Nodes häufig.

docker compose exec n8n n8n --version

Die Namen in diesem Leitfaden entsprechen dem aktuellen stabilen n8n-Stand von Juli 2026. Seit Version 1.82.0 wird jeder AI Agent-Node als Tools Agent ausgeführt. Das frühere Dropdown für den Agent-Typ ist daher nicht mehr vorhanden.

Schritt 1: Den Trigger auswählen

Fügen Sie für einen Konversationsagenten einen Chat Trigger-Knoten hinzu. Lassen Sie Make Chat Publicly Available während der Entwicklung deaktiviert, damit nur das Chatfenster 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 wichtig. 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-Knoten. Keiner von beiden erzeugt chatInput. Daher müssen Sie den Prompt selbst schreiben.

Schritt 2: Die Modellanmeldedaten

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

Erstellen Sie die Anmeldedaten in der Anthropic Console unter platform.claude.com, zunächst unter Settings und dann unter API Keys. Der Schlüssel wird nur einmal angezeigt. Die API-Nutzung wird pro Token abgerechnet und ist von einem Claude.ai-Abonnement getrennt. Daher muss für das Konto vor dem ersten Lauf die Abrechnung eingerichtet sein.

Wählen Sie das Modell pro Agent und nicht für das gesamte Unternehmen. Ein Agent mit einem Tool, der etwas nachschlägt und das Ergebnis meldet, läuft problemlos mit Haiku. Im Juli 2026 wird Haiku mit $1 pro Million Eingabetoken und $5 pro Million Ausgabetoken aufgeführt. Sobald der Agent mehrere Tools verwendet und deren Nutzung planen muss, wechseln Sie zu Sonnet. Sie vermeiden damit, dass ein günstiges Modell viermal das falsche Tool aufruft. Das kostet mehr als ein teures Modell, das einmal das richtige Tool aufruft.

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

Ein Hinweis aus der n8n-Dokumentation führt häufig zu Problemen: Ausdrücke innerhalb eines Sub-Nodes werden immer anhand des ersten Eingabeelements aufgelöst, niemals pro Element. 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 AI Agent-Knoten. Der Parameter Prompt hat zwei Einstellungen.

• Take from previous node automatically erwartet ein eingehendes Feld mit dem Namen chatInput. Das ist hinter einem Chat Trigger die richtige Auswahl.
• Define below zeigt ein Feld Prompt (User Message) an, in das Sie statischen Text oder einen Ausdruck eingeben. Das ist hinter einem Schedule Trigger oder einem Webhook-Knoten die richtige Auswahl.

Wenn ein Webhook-Knoten vorgeschaltet ist, wird der POST-Body unter $json.body abgelegt. Das Prompt-Feld 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

Ein AI Agent-Knoten ohne Tool-Unterknoten führt die Ausführung nicht aus. Beginnen Sie mit einem Tool. Ein einzelnes funktionierendes Tool liefert mehr Erkenntnisse als vier halb konfigurierte Tools.

Verbinden Sie einen HTTP Request-Knoten mit dem Tool-Anschluss des Agenten. Konfigurieren Sie ihn genau wie einen normalen HTTP Request-Knoten. Testen Sie den Endpunkt anschließend zuerst über eine Shell.

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

Wenn dieser curl-Befehl einen Fehler oder eine HTML-Anmeldeseite zurückgibt, schlägt auch der Agent fehl. Die Fehlermeldung wirkt dann wie ein Modellproblem, obwohl tatsächlich ein URL- oder Authentifizierungsproblem vorliegt. Beheben Sie das Problem in der Shell, nicht im Knoten.

Das Feld Description des Tools ist keine Dokumentation für Ihre Kollegen. Es ist die einzige Information, die das Modell liest, wenn es entscheidet, ob dieses Tool relevant ist. Beschreiben Sie klar, 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-Knoten verbunden sind. Im Code-Tool funktioniert er nicht.

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

Die Argumente sind key, danach 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 ist entweder string, number, boolean oder json. Standardmäßig wird string verwendet. Ein vollständigerer Aufruf sieht so aus.

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

Der Schlüssel ist ein Hinweis und kein Verweis auf vorhandene Daten. $fromAI('service') liest nirgendwo ein Feld namens service. Damit wird dem Modell mitgeteilt: „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.

Schritt 5: Speicher und warum der Agent vergisst

Ohne einen Speicher-Subknoten beginnt jede Nachricht ohne Kontext. Fügen Sie einen Simple Memory-Subknoten hinzu, um den aktuellen Gesprächsverlauf zu speichern.

Er hat zwei Parameter. Session Key legt fest, um welche Unterhaltung es sich handelt. Zwei Benutzer mit unterschiedlichen Schlüsseln erhalten daher getrennte Verläufe. Context Window Length legt fest, wie viele vorherige Interaktionen erneut in den Prompt eingefügt werden.

Context Window Length beeinflusst nicht nur die Qualität, sondern auch die Kosten. Jede gespeicherte Interaktion wird bei jedem späteren Aufruf erneut als Eingabetoken übertragen. Ein Fenster von 20 bedeutet bei einem gesprächigen Agenten, dass Sie für dieselben frühen Nachrichten zwanzigmal bezahlen.

Simple Memory funktioniert in einem aktiven Produktions-Workflow nicht, wenn n8n im Queue-Modus ausgeführt wird. Der Verlauf befindet sich dann in den eigenen Daten des Workflows und nicht in einem gemeinsam genutzten Speicher. Verwenden Sie auf einer Instanz im Queue-Modus stattdessen den Postgres Chat Memory-Subknoten. Verweisen Sie damit auf eine Datenbank, die sowohl der Hauptprozess als auch die Worker erreichen können.

Schritt 6: die Systemnachricht

Öffnen Sie die Optionen des Agenten und fügen Sie eine Systemnachricht hinzu. Hier wird die Aufgabenbeschreibung hinterlegt. Dieser Text hat im Workflow den größten Einfluss.

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 hier 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 der Agent, und was verhindert das?

Unter Options finden Sie auch Max Iterations. Der Standardwert ist 10. Eine Iteration besteht aus einem Modellaufruf und einem Tool-Ergebnis, das wieder in den Kontext übernommen wird. Ein einzelner Agent-Lauf ist daher nicht nur ein API-Aufruf, sondern umfasst bis zu zehn Aufrufe. Jeder Aufruf enthält die gesamte bisher gewachsene Konversation als Eingabe.

Verringern Sie den Wert. Die meisten Agenten mit nur einem Tool sind nach zwei Iterationen fertig. Ein Limit von 3 oder 4 macht aus einer Endlosschleife einen kontrollierten Fehler, den Sie in der Ausführungsliste sehen können.

Aktivieren Sie beim Debuggen Return Intermediate Steps. Die endgültige Ausgabe enthält dann die Tool-Aufrufe, die der Agent ausgeführt hat. So können Sie unterscheiden, ob das Modell das Tool nie aufgerufen hat oder ob das Tool kein verwertbares Ergebnis zurückgegeben hat. Deaktivieren Sie die Option vor dem Produktivbetrieb wieder. Für Endbenutzer sind diese Schritte nur überflüssige Ausgaben.

Beobachten Sie eine Ausführung über die Shell.

docker compose logs -f n8n

Verhindern, dass ein unbeaufsichtigter Agent unbemerkt Kosten verursacht

Ein Agent hinter einem Chat Trigger enthält einen Menschen. Dieser Mensch stoppt ihn, wenn die Antwort falsch aussieht. Ein Agent hinter einem Schedule Trigger wird nicht überwacht. Die vollständige Beschreibung finden Sie unter KI-Agentenkosten auf einem dauerhaft betriebenen VPS kontrollieren. Vier Einstellungen leisten dabei den größten Teil der Arbeit.

• Begrenzen Sie Maximum Number of Tokens im Modell-Subnode. Dadurch kann keine einzelne Antwort unnötig lang werden.
• 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 in derselben Ausführung.
• 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 Zahl.

Deaktivieren Sie den Workflow während der Iteration. Ein aktiver Workflow mit einem Schedule Trigger wird weiterhin mit der von n8n gespeicherten Version ausgeführt. Das ist nicht immer die Version, die auf Ihrem Bildschirm angezeigt wird.

FAQ

Warum weigert sich mein AI Agent-Knoten, die Ausführung zu starten?

Der AI Agent-Knoten benötigt einen Chatmodell-Unterknoten und mindestens einen Tool-Unterknoten. Ein Knoten mit einem Modell, aber ohne Tool, schlägt fehl, bevor er einen API-Aufruf ausführt. Fügen Sie ein Tool hinzu, auch wenn es nur eine triviale Funktion hat, und führen Sie den Knoten erneut aus.

Der Agent antwortet, ruft mein Tool aber nie auf. Was ist falsch?

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

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

Das Modell bestimmt die Anzahl der Schritte. Bei jeder Iteration wird die bisherige vollständige Unterhaltung erneut gesendet, einschließlich der vorherigen Tool-Ausgabe. Eine Ausführung mit vier Iterationen kostet daher deutlich mehr als das Vierfache eines einzelnen Aufrufs. Max Iterations legt die Obergrenze fest. Return Intermediate Steps zeigt, wie viele Schritte die jeweilige Ausführung tatsächlich verwendet hat.

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

Prüfen Sie, ob die Instanz im Queue-Modus ausgeführt wird. Simple Memory speichert den Verlauf in den eigenen Ausführungsdaten des Workflows. Diese Daten bleiben nicht erhalten, wenn der Workflow an einen separaten Worker-Prozess übergeben wird. Daher verliert ein aktiver Produktions-Workflow seinen Verlauf. Verwenden Sie stattdessen den Unterknoten Postgres Chat Memory. Er speichert den Verlauf in der Datenbank, die von allen Workern gemeinsam verwendet wird.