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 Chatmodell, ein oder mehrere Tools und optional ein Memory. Sie geben ein Ziel in natürlicher Sprache 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.

Bei einer Chain ist es umgekehrt. In einer Basic LLM Chain legen Sie die Schritte fest. Das Modell erzeugt nur den Text. Bei einem Agenten legt das Modell die Schritte fest. Deshalb kann dieselbe Frage heute einen Modellaufruf und morgen neun Modellaufrufe verursachen. Dieser eine Unterschied bestimmt jede Einstellung in diesem Leitfaden. Wenn dieses Konzept für Sie neu ist und nicht nur die n8n-Funktion, sollten Sie den Ablauf zunächst einmal von Hand implementieren, bevor Sie ihn aus Nodes zusammensetzen. Der Node verbirgt genau den Teil, dessen Verhalten Sie im weiteren Verlauf dieses Leitfadens analysieren müssen.

Voraussetzung ist, dass n8n bereits hinter HTTPS auf einer von Ihnen kontrollierten Maschine läuft. Falls nicht, beginnen Sie mit n8n mit Docker und einem gültigen Zertifikat selbst zu hosten, weil der API-Schlüssel, den Sie gleich speichern, die Sicherung des Encryption Key benötigt, auf der dieser Leitfaden ausdrücklich besteht. Informationen zu Mustern ohne Agenten, etwa Webhook-Zusammenfassungen und geplanten Klassifizierungen, finden Sie unter Claude- und n8n-Workflow-Muster.

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

docker compose exec n8n n8n --version

Die Namen in diesem Leitfaden entsprechen dem aktuellen Stable-Release von n8n im Juli 2026. Seit Version 1.82.0 wird jeder AI Agent-Node als Tools Agent ausgeführt. Das Dropdown-Feld 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-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

Ziehen Sie einen AI Agent-Knoten auf die Arbeitsfläche. n8n zeigt darunter sofort einen leeren Chat Model-Anschluss an. Fügen Sie dort einen Anthropic Chat Model-Unterknoten hinzu.

Erstellen Sie die Anmeldedaten in der Anthropic Console unter platform.claude.com. Öffnen Sie dazu Settings und anschließend API Keys. Der Schlüssel wird nur einmal angezeigt. Die API-Nutzung wird pro Token abgerechnet und ist von jedem Claude.ai-Abonnement getrennt. Deshalb muss für das Konto vor dem ersten Lauf die Abrechnung eingerichtet werden.

Wählen Sie das Modell pro Agent und nicht pro Unternehmen. Ein Agent mit einem Tool, der Informationen abruft und ausgibt, läuft problemlos mit Haiku. Im Juli 2026 wird Haiku mit $1 pro Million Eingabetoken und $5 pro Million Ausgabetoken angegeben. 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 und dadurch mehr kostet als ein teures Modell, das einmal das richtige Tool verwendet.

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

Ein Hinweis aus der n8n-Dokumentation führt häufig zu Problemen: Ausdrücke in einem Unterknoten 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 Stammknotens.

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

Öffnen Sie den AI Agent-Knoten. Der Parameter Prompt bietet zwei Einstellungen.

• Take from previous node automatically erwartet ein eingehendes Feld mit dem Namen chatInput. Hinter einem Chat Trigger ist dies die richtige Auswahl.
• Define below zeigt das Feld Prompt (User Message) an. Dort geben Sie statischen Text oder einen Ausdruck ein. Hinter einem Schedule Trigger oder einem Webhook-Knoten ist dies 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 node ohne untergeordnetes Tool lässt sich nicht ausführen. Beginnen Sie mit einem Tool. Ein einzelnes funktionierendes Tool liefert mehr Erkenntnisse als vier halb konfigurierte Tools.

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 dieser curl-Befehl einen Fehler oder eine HTML-Anmeldeseite zurückgibt, schlägt auch der Agent fehl. Der Fehler sieht dann wie ein Modellproblem aus, obwohl tatsächlich ein URL- oder Authentifizierungsproblem vorliegt. Beheben Sie das Problem in der Shell und nicht im Node.

Das Feld Description des Tools ist keine Dokumentation für Ihre Kollegen. Es ist die einzige Information, die das Modell bei der Entscheidung liest, 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. 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 nicht an irgendeiner Stelle ein Feld namens service. Der Ausdruck teilt dem Modell mit: „Erzeuge einen Wert und nenne ihn service.“ Das Modell durchsucht dann die Konversation, die Eingabedaten und die Ergebnisse anderer Tools nach einem passenden Wert. In einem Chat-Workflow fragt es möglicherweise einfach den Benutzer.

Die Websuche ist normalerweise das 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 jede zurückgegebene Seite jedoch als nicht vertrauenswürdigen Text, der sich nun in Ihrem Prompt befindet.

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 die letzte Unterhaltung zu speichern.

Der Subknoten hat zwei Parameter. Session Key legt fest, zu welcher Unterhaltung die Nachricht gehört. Zwei Benutzer mit unterschiedlichen Schlüsseln erhalten dadurch getrennte Verläufe. Context Window Length bestimmt, wie viele vorherige Interaktionen erneut in den Prompt übernommen 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. Bei einem gesprächigen Agenten mit einem Fenster von 20 zahlen Sie für dieselben frühen Nachrichten zwanzigmal.

Simple Memory funktioniert in einem aktiven Produktions-Workflow nicht, wenn n8n im Queue-Modus ausgeführt wird. Der Verlauf wird dann in den Workflow-Daten selbst statt in einem gemeinsam genutzten Speicher abgelegt. Verwenden Sie auf einer Instanz im Queue-Modus stattdessen den Postgres Chat Memory-Subknoten. 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 läuft der Agent in einer Schleife, und was beendet sie?

Unter Options finden Sie außerdem Max Iterations. Der Standardwert ist 10. Eine Iteration besteht aus einem Modellaufruf und einem Tool-Ergebnis, das wieder in den Kontext eingespeist wird. Ein einzelner Agent-Lauf ist daher kein einzelner API-Aufruf, sondern umfasst bis zu zehn Aufrufe. Jeder Aufruf enthält die gesamte wachsende Konversation als Eingabe.

Verringern Sie diesen Wert. Die meisten Agenten mit einem einzelnen Tool sind nach zwei Iterationen fertig. Ein Limit von 3 oder 4 Durchläufen beendet eine Endlosschleife mit einem kontrollierten Fehler, den Sie in der Ausführungsliste sehen können.

Aktivieren Sie während der Fehlersuche Return Intermediate Steps. Die Endausgabe enthält dann auch die Tool-Aufrufe, die der Agent ausgeführt hat. So erkennen Sie, ob das Modell das Tool nie aufgerufen hat oder ob das Tool kein brauchbares Ergebnis zurückgegeben hat. Deaktivieren Sie die Option wieder, bevor Sie den Agenten produktiv einsetzen. Für Endbenutzer sind diese Schritte nur unnötige Ausgaben.

Beobachten Sie eine Ausführung über die Shell.

docker compose logs -f n8n

Einen unbeaufsichtigten Agenten an unbemerktem Verbrauch hindern

Ein Agent hinter einem Chat Trigger hat einen Menschen als Kontrollinstanz. Dieser greift ein, sobald die Antwort falsch wirkt. Ein Agent hinter einem Schedule Trigger wird nicht überwacht. Hier überwachen Sie die Modellkosten und nicht die Lizenzkosten, weil die Agent-, Tool- und Memory-Knoten alle in der kostenlosen selbst gehosteten Edition funktionieren und die Funktionen, für die tatsächlich ein kostenpflichtiger Schlüssel erforderlich ist, größtenteils Team- und Governance-Funktionen sind. Eine vollständige Darstellung finden Sie unter Kostenkontrolle für AI-Agenten auf einem dauerhaft betriebenen VPS. Vier Einstellungen sind dafür besonders wichtig.

• Begrenzen Sie Maximum Number of Tokens im Modell-Subknoten. Dadurch kann keine einzelne Antwort übermäßig 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 einen JSON-Block mit 4,000 Zeilen zurückgibt, übergibt den gesamten Inhalt an den nächsten Modellaufruf und anschließend 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 Zahl.

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

FAQ

Warum verweigert die AI Agent-Node die Ausführung?

Die AI Agent-Node benötigt eine Chat-Modell-Sub-Node und mindestens eine Tool-Sub-Node. Eine Node mit einem Modell, aber ohne Tool schlägt fehl, bevor sie einen API-Aufruf ausführt. Fügen Sie ein Tool hinzu, auch wenn es nur eine triviale Funktion hat, und führen Sie den Workflow 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 nichts darüber aus, 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 jedem Lauf unterschiedlich viel?

Das liegt daran, dass das Modell die Anzahl der Schritte auswählt. Bei jeder Iteration wird die bisherige vollständige Unterhaltung erneut gesendet, einschließlich der vorherigen Tool-Ausgabe. Ein Lauf mit vier Iterationen kostet daher deutlich mehr als das Vierfache eines einzelnen Aufrufs. Max Iterations legt die maximale Anzahl fest. Return Intermediate Steps zeigt, wie viele Schritte der jeweilige Lauf tatsächlich verwendet hat.

Mein Speicher 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 den Ausführungsdaten des Workflows. Diese Daten bleiben nicht erhalten, wenn die Ausführung an einen separaten Worker-Prozess übergeben wird. Deshalb verliert ein aktiver Produktions-Workflow seinen Verlauf. Verwenden Sie stattdessen die Sub-Node Postgres Chat Memory. Sie speichert den Verlauf in der Datenbank, die von allen Workern gemeinsam verwendet wird.