n8n-Workflow mit menschlicher Freigabe, OpenAI-kompatibler API und JSON-Schema-Validierung

Die Entscheidung: Die Aktion freigeben, nicht nur die Extraktion

Bei Rechnungen, Support-Tickets, Formularen und eingehenden Anfragen liegt das Risiko häufig nicht in der Extraktion der Felder. Entscheidend ist, was danach geschieht: einen Kundendatensatz anlegen, einen Status ändern, eine externe Nachricht senden oder Daten löschen.

Ein robuster n8n-Entwurf verwendet daher drei Prüfungen:

1. Extraktion: Eine OpenAI-kompatible API gibt strukturierte Daten zurück.
2. Validierung: n8n prüft, ob die Daten einem JSON-Schema entsprechen.
3. Freigabe: Ein n8n AI Agent kann ein folgenschweres Tool erst aufrufen, nachdem eine Person dies freigegeben hat.

So verhindern Sie, dass fehlerhafte Daten die prüfende Person erreichen, und halten die freigegebene Ausführung von der Modellausgabe getrennt.

OneMux ermöglicht den Zugriff auf führende KI-Modelle über eine einzige OpenAI-kompatible API. Sie können OneMux als Zugriffsweg für das Modell verwenden, sofern der Endpunkt und das ausgewählte Modell laut Dokumentation das Anfrageformat und die Parameter unterstützen, die Ihre n8n-Konfiguration benötigt. Es wird hier nicht behauptet, dass die Integration von OneMux und n8n getestet wurde.

Voraussetzungen

Sie benötigen:

• Eine n8n-Instanz mit Zugriff auf die Nodes HTTP Request, Code und, sofern zutreffend, AI Agent.
• Einen von Ihrer n8n-Konfiguration unterstützten Freigabekanal, etwa n8n Chat, Slack, Telegram, E-Mail oder einen anderen dokumentierten Kanal.
• Zugriff auf eine OpenAI-kompatible API. Wenn Sie OneMux verwenden, beginnen Sie mit dem OneMux-Schnellstart und bestätigen Sie den aktuellen Endpunkt, die Authentifizierungsmethode, die Modellkennungen und die unterstützten Anfrageparameter in der OneMux-Dokumentation.
• Ein JSON-Schema, das das zu extrahierende Objekt beschreibt.
• Ein Ziel-Tool, beispielsweise eine CRM-Aktualisierung oder eine Aktion zum Senden von Nachrichten, das nicht ohne menschliche Prüfung ausgeführt werden soll.

Gehen Sie nicht davon aus, dass jeder OpenAI-kompatible Endpunkt alle Funktionen für strukturierte Ausgaben unterstützt. Prüfen Sie die Unterstützung für response_format, JSON Schema, Tool-Aufrufe und das von Ihnen ausgewählte Modell. Das OneMux-Modellverzeichnis kann Sie bei der Prüfung verfügbarer Modelloptionen unterstützen, belegt jedoch nicht automatisch die Unterstützung einer bestimmten n8n-Node-Konfiguration.

Empfohlener n8n-Workflow

Ein praktischer Workflow kann diese Nodes verwenden:

1. Webhook oder ein anderer Trigger empfängt den Quelltext.
2. HTTP Request sendet den Text an den kompatiblen Modell-Endpunkt.
3. Code parst und validiert das zurückgegebene Objekt.
4. IF leitet ungültige Ergebnisse an einen Fehler- oder manuellen Korrekturpfad weiter.
5. AI Agent erhält das validierte Objekt und Zugriff auf ein folgenschweres Tool.
6. Menschliche Prüfung hält den Workflow an, bevor dieses Tool ausgeführt wird.
7. Freigegebenes Tool schreibt den Datensatz oder sendet die Nachricht.

Die Extraktionsanfrage sollte nur die Felder anfordern, die Ihr Workflow benötigt. Ein kompaktes Beispielschema für eine Supportanfrage könnte so aussehen:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "required": ["category", "priority", "summary", "customer_email"],
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "account", "other"]
    },
    "priority": {
      "type": "string",
      "enum": ["low", "normal", "high", "urgent"]
    },
    "summary": {
      "type": "string",
      "minLength": 1
    },
    "customer_email": {
      "type": "string",
      "format": "email"
    }
  }
}

OpenAI-kompatible Anfrage konfigurieren

Verwenden Sie im HTTP-Request-Node die Basis-URL und die Authentifizierungshinweise aus der Dokumentation des Anbieters. Hinterlegen Sie keine anbieterspezifische URL fest, bevor Sie sie nicht für Ihr Konto und Ihre Region überprüft haben.

Die folgende Anfrageform ist beispielhaft. Ob response_format und seine JSON-Schema-Struktur akzeptiert werden, hängt vom gewählten Endpunkt, Modell und der n8n-Konfiguration ab.

{
  "model": "YOUR_DOCUMENTED_MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "Extract the requested fields. Do not guess missing values. Return only an object matching the supplied schema."
    },
    {
      "role": "user",
      "content": "{{$json.source_text}}"
    }
  ],
  "temperature": 0,
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_request",
      "strict": true,
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["category", "priority", "summary", "customer_email"],
        "properties": {
          "category": {"type": "string"},
          "priority": {"type": "string"},
          "summary": {"type": "string"},
          "customer_email": {"type": "string"}
        }
      }
    }
  }
}

Das Beispiel verwendet bewusst eine Platzhalter-Modell-ID. Wählen Sie ein Modell, das laut Dokumentation mit Ihrem gewählten Endpunkt kompatibel ist. Falls eine strikte JSON-Schema-Ausgabe nicht verfügbar ist, verwenden Sie einen unterstützten JSON-Modus nur dann, wenn Ihr Validierungspfad nicht konforme Antworten sicher ablehnen kann. Der JSON-Modus allein ist nicht gleichbedeutend mit einer Schema-Validierung.

Antwort vor der Ausführung validieren

Anbieterantworten können den generierten Inhalt in unterschiedlichen Feldern ablegen. Prüfen Sie eine echte Antwort in n8n, bevor Sie den Parser schreiben. Der folgende Code-Node geht davon aus, dass das Modell einen JSON-String in message.content zurückgegeben hat. Passen Sie den Pfad an die tatsächlich empfangene Antwort an.

const raw = $json.choices?.[0]?.message?.content;

if (typeof raw !== 'string') {
  throw new Error('Model response did not contain message.content as a string');
}

let extracted;
try {
  extracted = JSON.parse(raw);
} catch (error) {
  throw new Error('Model returned invalid JSON');
}

const required = ['category', 'priority', 'summary', 'customer_email'];
const missing = required.filter((key) => extracted[key] === undefined || extracted[key] === '');

const validCategory = ['billing', 'technical', 'account', 'other'].includes(extracted.category);
const validPriority = ['low', 'normal', 'high', 'urgent'].includes(extracted.priority);
const validEmail = typeof extracted.customer_email === 'string' &&
  /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(extracted.customer_email);

if (missing.length || !validCategory || !validPriority || !validEmail) {
  throw new Error('Extracted object failed application validation');
}

return [{ json: { extracted } }];

Ersetzen Sie diese einfache Prüfung für den produktiven Einsatz durch einen gepflegten JSON-Schema-Validator, sofern Ihre n8n-Bereitstellung dies zulässt. Das Schema in der Anfrage und das bei der Validierung durchgesetzte Schema sollten gemeinsam versioniert werden. Fügen Sie der Ausgabe eine Schema-Version hinzu, wenn nachgelagerte Systeme zwischen Revisionen unterscheiden müssen.

Menschliche Freigabe für das AI-Agent-Tool hinzufügen

Verwenden Sie das validierte Objekt als Kontext für einen AI Agent. Geben Sie dem Agent ein eng begrenztes Tool wie CreateSupportTicket statt eines umfassenden Datenbankzugriffs. Konfigurieren Sie die menschliche Prüfung für dieses ausgewählte Tool im Tools Panel des AI Agent.

Die n8n-Dokumentation besagt, dass ein Workflow pausiert, wenn ein Agent ein prüfpflichtiges Tool aufruft. Eine prüfende Person kann den Aufruf freigeben, sodass das Tool mit der vorgeschlagenen Eingabe ausgeführt wird, oder ihn ablehnen, wodurch die Aktion abgebrochen wird. n8n unterstützt mehrere Freigabekanäle, darunter die integrierte Chat-Oberfläche sowie Integrationen wie Slack, Telegram, Discord, Teams, E-Mail, WhatsApp, Google Chat und Outlook-E-Mail. Die aktuellen Einrichtungsschritte und Kanaldetails finden Sie in der offiziellen n8n-Dokumentation zu Human-in-the-Loop.

Eine hilfreiche Freigabenachricht sollte die geplante Aktion und ihre Parameter sichtbar machen:

The AI wants to use {{ $tool.name }} with the following parameters:
{{ JSON.stringify($tool.parameters, null, 2) }}

Die Quelldokumentation nennt $tool.name und $tool.parameters für diesen Prüfungskontext. Halten Sie die Nachricht verständlich und fügen Sie die ursprüngliche Anfrage oder eine Ticketreferenz hinzu, wenn Prüfende zusätzlichen Kontext benötigen.

Auch Ihr System-Prompt für den Agent sollte das Verhalten bei der Prüfung erläutern:

The CreateSupportTicket tool requires human approval. If approval is denied, do not retry automatically. Tell the user that the action was not completed and explain what information or correction is needed.

Einschränkungen und Fehlerbehebung

Das Modell gibt Markdown oder zusätzlichen Text zurück

Prüfen Sie, ob der Endpunkt die von Ihnen gesendeten Parameter für strukturierte Ausgaben unterstützt. Falls nicht, entfernen Sie nicht unterstützte Parameter, formulieren Sie die Anweisung präziser und behalten Sie die Validierung im Code-Node als verbindliche Schranke bei. Senden Sie niemals ein nicht validiertes Objekt an das Schreib-Tool.

n8n findet das erwartete Antwortfeld nicht

Prüfen Sie die Ausgabe des HTTP-Request-Nodes und aktualisieren Sie den Parser. OpenAI-kompatible APIs können gemeinsame Konventionen für Anfragen verwenden, sich aber bei Antwortdetails und unterstützten Parametern unterscheiden.

Die Freigabeanfrage ist zu vage

Verwenden Sie ein eng begrenztes Tool und nehmen Sie $tool.name sowie $tool.parameters in die Freigabenachricht auf. Bitten Sie eine prüfende Person nicht, eine undurchsichtige Anweisung wie „Diese Anfrage bearbeiten“ freizugeben.

Ein abgelehnter Tool-Aufruf führt zu einer Schleife

Fügen Sie dem System-Prompt des Agent ein ausdrückliches Verhalten für Ablehnungen hinzu und konfigurieren Sie den Workflow so, dass eine Ablehnung den Aktionspfad beendet oder zur Klärung weiterleitet. Die n8n-Dokumentation empfiehlt, zu erläutern, welche Tools eine Freigabe benötigen und wie der Agent auf eine Ablehnung reagieren soll.

Prüfende Personen geben fehlerhafte Daten frei

Die Gültigkeit nach einem Schema beweist nicht die semantische Richtigkeit. Zeigen Sie den Quellausschnitt, die extrahierten Felder und die geplante Aktion gemeinsam an. Bei Workflows mit hohen Auswirkungen sollten Sie verlangen, dass eine prüfende Person sensible Felder unabhängig bestätigt.

Fazit

Das sicherste n8n-Muster für strukturierte Extraktion lautet nicht: „Das Modell direkt schreiben lassen.“ Extrahieren Sie stattdessen in ein beschränktes Objekt, validieren Sie es und setzen Sie anschließend eine menschliche Freigabe vor das Tool, das die Außenwelt verändert. Eine OpenAI-kompatible API kann den Modellzugriff vereinfachen, während n8n Orchestrierung und Freigabesteuerung bereitstellt. Verwenden Sie OneMux mit dem dokumentierten kompatiblen Endpunkt und den dokumentierten Modellparametern, überprüfen Sie die Konfiguration in Ihrer eigenen Umgebung und behandeln Sie nicht unterstützte Funktionen für strukturierte Ausgaben als Anlass, den Vorgang zu stoppen oder auf einen separat validierten Antwortpfad auszuweichen.