Vom Prompt zur Produktion: Eine Headless-Workflow-Lösung bauen

Natürliche Sprache in Workflows verwandeln

Vom Prompt zur Produktion: Eine Headless-Workflow-Lösung bauen

Jake Byman
Staff Software Engineer
View author profile
Jake Byman
Staff Software Engineer
View author profile
Table of contents

Wie wir in einfacher Sprache einen Workflow beschreiben und einen funktionierenden zurückbekommen. Erfahren Sie, wie wir auf n8n aufgebaut haben, ganz ohne Workflow-Editor und ohne Vorlagen.

In n8n gebaute Workflows kodieren mehrstufige, komplexe Interaktionen, um Dinge über mehrere Systeme hinweg zu erledigen. Wir erkunden Wege, einen Workflow in einfacher Sprache zu beschreiben und einen funktionierenden zurückzubekommen, um den Prozess drastisch zu vereinfachen und dabei n8n weiterhin als leistungsstarken Orchestrator zu nutzen.

n8n headless betreiben

Mit einem Editor und einem Chat als einziger Oberfläche kann alles andere dahinter liegen.

Ein n8n-Projekt pro Tenant

Tenants voneinander zu isolieren ist entscheidend. Nach Gesprächen mit dem n8n-Team haben wir uns entschieden, Daten pro Projekt zu trennen. Workflows, Credentials und Ausführungen jedes Tenants leben in einem eigenen n8n-Projekt, und n8n erzwingt diese Grenze für uns. Wir mussten keine eigene Isolationsschicht darüber bauen.

Hot und Cold Shards

Wir können Workflows erstellen, die in beliebigem Volumen laufen, also mussten wir mit lauten Nachbarn („Noisy Neighbors“) planen. Ein einzelner Tenant kann zehn- oder hunderttausende Ausführungen einreihen, und wir wollten nicht, dass alle anderen in derselben Warteschlange dahinter warten.

Dafür haben wir unsere Infrastruktur in temperaturbasierte „Shards“ aufgeteilt. Jeder Shard hat einen n8n-Main-Node, Worker-Nodes, Redis und Postgres und läuft im Queue-Modus. Hot Nodes übernehmen sofortige, kritische Ausführungen. Cold Nodes übernehmen Bulk- und Hintergrundarbeit. Innerhalb eines Shards teilen sich Hot und Cold Nodes die Postgres-Datenbank dieses Shards, die die Workflow-Metadaten enthält.

Credentials

Kund:innen müssen ihre Workflows mit externen Diensten verbinden, und auch andere Teile unseres Produkts brauchten Zugriff auf diese Drittanbieter-Credentials. Also haben wir uns vor n8n gestellt.

Webflow kann die OAuth-App betreiben, hält die Tokens und verantwortet die Rotation. Das kanonische Credential liegt dann verschlüsselt in einem Secret-Store-Dienst. n8n erhält eine Spiegelung dieses Credentials, die es bei der Workflow-Ausführung nutzt. Ein Binding ordnet eine Webflow-Verbindung einem n8n-Credential zu, pro Projekt und Shard. Läuft ein Token bald ab, rotiert ein geplanter Job es, schreibt das neue Token in den Secret Store und aktualisiert jedes an diese Verbindung gebundene n8n-Credential.

Trigger

Da n8n headless läuft, wäre es möglich, einen Workflow zu starten, ohne in der n8n-Oberfläche auf einen Button zu klicken. Stattdessen startet jeder Workflow von einem Webhook-Node. Wir registrieren den Webhook am aufgelösten Trigger-Pfad. Wenn ein Trigger-Ereignis eintritt, etwa eine Formulareinsendung oder ein veröffentlichtes CMS-Collection-Item, sendet der Webflow-Monolith eine POST-Anfrage an diesen Webhook. Geplante Workflows funktionieren genauso: Ein Cron-Job in Webflow prüft, welche fällig sind, und sendet den POST.

Die Architektur

Diagramm der n8n-Architektur

Ein paar zentrale Bausteine im Überblick:

  • Der Webflow-Monolith stellt die API für Entwürfe, Versionen, Läufe und Berechtigungen bereit.
  • Der Builder-Service verwandelt einen Prompt in n8n-Workflow-JSON.
  • Der LLM-Proxy übernimmt jeden Modellaufruf während der Ausführung. Wir nutzen ihn, um Tokens von den Budgets der Kund:innen abzuziehen.
  • n8n orchestriert die Workflows auf Shards, die wir selbst betreiben.

Der Builder-Service ist ein kleiner, zustandsloser HTTP-Service außerhalb des Monolithen. Er hat keine eigene Datenbank und läuft im selben Netzwerk wie die n8n-Shards. Er hat vier Routen: build, plan, import und health.

Vom Prompt zum Workflow

Das passiert, wenn der Builder einen Prompt erhält:

  1. Das Modell um TypeScript bitten, das gegen das n8n-Workflow-SDK geschrieben ist.
  2. Dieses TypeScript zu n8n-JSON kompilieren.
  3. Jeden Node gegen unsere Allowlist prüfen.
  4. Den auf ihrem SDK basierenden Validator von n8n ausführen.
  5. Unsere eigenen Struktur-Prüfungen ausführen.

Ein Fehler in einem beliebigen Schritt geht als schlichte Anweisung zurück an das Modell, das es erneut versucht, insgesamt bis zu vier Versuche.

Das Kompilieren führt den Code des Modells nicht aus. Das SDK durchläuft den TypeScript-Syntaxbaum mit einem Interpreter, der nur SDK-Aufrufe erlaubt und Globals wie eval, require, process und fetch blockiert.

Warum TypeScript statt JSON?

Wir haben zunächst das Modell um rohes JSON gebeten. Wenn man ein Modell um große Workflow-JSON-Blöcke bittet, bekommt man etwas subtil Falsches: einen erfundenen Parameter, der richtig aussieht, einen Node-Typ, den es nicht gibt, oder eine Verbindungsstruktur aus einer älteren n8n-Version. All das übersteht ein flüchtiges Lesen, doch der Workflow scheitert, wenn man ihn tatsächlich ausführt.

Gegen das SDK geschrieben, kann das Modell die Verbindungsstruktur nicht falsch machen, weil das SDK die Verbindungen baut. Ein Syntax- oder API-Fehler scheitert mit einem zeilennummerierten Fehler, den die Retry-Schleife zurückschickt, und nicht existierende Node-Typen fängt unsere Allowlist ab. LLMs sind gut darin, Code zu schreiben. Der Wechsel vom Generieren von JSON zum Generieren von Code gegen das SDK hat diese Fehler von der Laufzeit in die Build-Zeit verlagert, wo die Retry-Schleife sie beheben kann.

Ein Beispiel: Hier verkettet das Modell ein .then(), das das SDK nicht hat:

Der Build scheitert, bevor irgendetwas n8n erreicht, und dieser Fehler geht zurück an das Modell:

Die Allowlist

n8n liefert mehr als tausend Nodes mit. Wir unterstützen weniger als 20 davon, mit Absicht. Da wir uns für Integrationen vor n8n stellen, müssen wir sicherstellen, dass der Builder zum Beispiel keinen Slack-Node generiert, wenn wir Slack nicht unterstützen.

Deshalb führen wir eine Liste erlaubter Nodes. Jeder Eintrag fixiert eine Version und enthält ein bewährtes Parameterbeispiel, und wir nutzen die Liste als einen der Validierungsschritte.

Was schwieriger war als erwartet

Workflow-Status synchronisieren

Wir wollten eine Live-Ansicht eines Workflows zeigen, während er läuft. Dazu abonnieren wir die Log-Stream-Ereignisse von n8n und synchronisieren sie über einen Websocket zum Client.

Das funktionierte gut, bis wir auf lang laufende Workflows trafen. Manche gingen verloren: Wenn einem Worker der Speicher ausging oder er während eines Deployments neu startete, ließ die Queue von n8n den Job scheitern, ohne ein Log-Stream-Ereignis auszusenden, sodass unsere Oberfläche ihn für immer als laufend anzeigte. Die Lösung war, für solche Jobs Polling hinzuzufügen, zusammen mit Telemetrie zu ihrem Zustand.

Änderungen

Sobald der Agent einen Workflow generiert hat, muss der oder die Kund:in entscheiden, ob er korrekt ist. Wir werden niemanden bitten, im JSON zu zeigen, was falsch ist.

Stattdessen bauen Änderungen den gesamten Workflow neu. Wir übergeben das Feedback der Kund:innen zusammen mit dem aktuellen Workflow an den Builder-Service und bitten um das Ganze zurück. Das wiederholt sich, bis uns der oder die Kund:in sagt, dass es stimmt.

Das Neubauen hat seinen Preis: Das Modell kann einen Schritt weglassen oder ändern, den die Kund:in nie erwähnt hat. Deshalb geben wir dem Builder den vollständigen aktuellen Workflow, einschließlich deaktivierter Schritte und Einstellungen wie Timeouts, und unsere Edit-Evals schlagen fehl, wenn ein Schritt verschwindet, den die Anfrage nicht erwähnt hat.

Menschen lassen Dinge aus

Natürliche Sprache ist schwierig. „Schick mir eine Zusammenfassung“ ist ein klassisches Beispiel: eine Zusammenfassung wovon? Wohin gesendet? Wie oft?

Dafür führt der Builder zuerst einen Planungsschritt aus. Er entscheidet, ob er genug zum Bauen hat oder eine Frage stellen muss. Er stellt jeweils nur eine Frage, und sobald Trigger und Hauptaktion klar sind, baut er.

Evals

Anfangs entstand unser Qualitätsgefühl daraus, dass jemand einen Prompt ausprobierte und einen Eindruck gewann. Das skaliert nicht. Wenn man den Prompt, das Modell oder die Allowlist ändert, sagt einem nichts, was passiert ist.

Also haben wir 20 Evals auf Basis repräsentativer Kundenanfragen geschrieben, jeweils mit einem schriftlich festgehaltenen erwarteten Ergebnis, und sie in drei Stufen unterteilt:

  • Stufe 0: Wurde gebaut, und bei welchem Versuch?
  • Stufe 1: Läuft er tatsächlich gegen eine Sandbox-Website mit Fixture-Daten?
  • Stufe 2: Hat er getan, was verlangt wurde? Ein Modell liest den Prompt und bewertet den resultierenden Workflow-Graphen.

Unsere Messlatte sind 70 % korrekt beim ersten Versuch.

Lasttests

Webflow hostet Websites für rund 1 % des Internets, also wollten wir wissen, wie n8n standhält, bevor sich Kund:innen darauf verlassen.

Wir haben einen n8n-Main-Node und vier Worker in einer isolierten Staging-Umgebung aufgesetzt und mehrere Testrunden gefahren. Einer unserer Favoriten war ein Workflow, den wir „Fibonacci-Hammer“ nannten. Er führte eine CPU-intensive Fibonacci-Berechnung mit fast keinem I/O aus, um die Hardware so stark wie möglich zu belasten.

Wir haben von zwei Ausführungen pro Sekunde auf 550 hochgefahren und in rund einer Stunde etwa 300.000 Ausführungen gefahren. Das haben wir gesehen:

  • Der Main-Node war bis etwa 500 Ausführungen pro Sekunde stabil. Danach fiel er aus und erholte sich nach etwa einer Minute von selbst.
  • Jeder Worker lastete einen CPU-Kern aus, ohne dauerhaft am Limit zu bleiben.
  • Das Autoscaling führte den Worker-Pool bis zur Obergrenze von vier.
  • Redis und Postgres hielten durchgehend.

Wir haben außerdem festgestellt, dass uns einige Metriken fehlten, und deshalb CPU-Telemetrie und eine Redis-Queue-Tiefe-Metrik ergänzt. Die Kurzfassung: n8n im Queue-Modus bewältigte bis zu etwa 500 Ausführungen pro Sekunde. Wir haben einen CPU-gebundenen Test gewählt, weil er die Worker am stärksten belastet. Echte Workflows warten meist auf I/O und belasten einen Worker daher weniger.

CPU-Auslastung des Main-Nodes
CPU-Auslastung der Worker

Was wir gelernt haben

Ein paar Erkenntnisse, die wir allen weitergeben würden, die etwas Ähnliches bauen:

  • Behandeln Sie Workflow-JSON als Kompilierziel und geben Sie Ihrem Generator eine typisierte Oberfläche.
  • n8n-Projekte funktionieren gut für Multi-Tenancy.
  • Man kann n8n-Workern im Queue-Modus eine Menge zumuten.
  • Workflow-Status über mehrere Systeme hinweg zu synchronisieren ist schwierig. Planen Sie frühzeitig mit verpassten Ereignissen: Nutzen Sie Polling als Absicherung des Event-Streams und alarmieren Sie bei Läufen, die zu lange im Zustand „läuft“ bleiben.

Wir haben diese Arbeit erstmals auf n8ns Konferenz In the Loop in Berlin vorgestellt.

Vortrag auf der In the Loop in Berlin

Zuletzt aktualisiert
November 6, 2026
Kategorie

Related articles

APIs für Agenten gestalten
APIs für Agenten gestalten

APIs für Agenten gestalten

APIs für Agenten gestalten

Technik
By
Yan Xie
,
Virat Patel
,
Albert Chang
Read article
Ihre Tools funktionieren. Wird der Agent sie richtig einsetzen?
Ihre Tools funktionieren. Wird der Agent sie richtig einsetzen?

Ihre Tools funktionieren. Wird der Agent sie richtig einsetzen?

Ihre Tools funktionieren. Wird der Agent sie richtig einsetzen?

Technik
By
,
,
Read article
Zur Quelle
Zur Quelle

Zur Quelle

Zur Quelle

Technik
By
Ben Haefele
,
Utkarsh Sengar
,
Read article

verifone logomonday.com logospotify logoted logogreenhouse logoclear logocheckout.com logoreddit logothe new york times logoideo logoupwork logodiscord logo
verifone logomonday.com logospotify logoted logogreenhouse logoclear logocheckout.com logoreddit logothe new york times logoideo logoupwork logodiscord logo

Kostenlos starten

Testen Sie Webflow mit unserem kostenlosen Starter-Abonnement so lang, wie Sie möchten. Erwerben Sie ein kostenpflichtiges Site-Abo, um Ihre Website zu veröffentlichen und zu hosten sowie zusätzliche Funktionen zu erschließen.

Get started — it’s free
Get started — it’s free
Demo ansehen
Demo ansehen

Testen Sie Webflow mit unserem kostenlosen Starter-Abonnement so lang, wie Sie möchten. Erwerben Sie ein kostenpflichtiges Site-Abo, um Ihre Website zu veröffentlichen und zu hosten sowie zusätzliche Funktionen zu erschließen.