Zum Hauptinhalt springen

Zustandsnormalisierung durch SQL-Persistenz

Was du nach diesem Kapitel kannst: Du verstehst, warum bestimmte Agenten in 42°OS die Nachrichtenstruktur verändern und warum das zu Folgeproblemen führt. Du kennst das Prinzip der SQL-Persistenz als Normalisierungsmechanismus und weißt, an welchen Stellen im Workflow es sinnvoll ist, Zwischenergebnisse wegzuschreiben und wieder abzuholen.

1. Das Problem: Verschachtelung und strukturelle Unvorhersagbarkeit​

In einem einfachen linearen Workflow ist die Struktur der Nachricht nach jedem Schritt vorhersagbar. Sobald aber Generative AI Agents und Zusammenführungsoperationen ins Spiel kommen, verändert sich die Nachrichtenstruktur auf eine Weise, die nachgelagerte Agenten verwirren kann.

Der Generative AI Agent verschachtelt seine Ausgabe​

Die meisten Agenten in 42°OS fügen ihren Output auf derselben Ebene der JSON-Struktur hinzu — sie mergen ihre Ergebnisse direkt in die eingehende Nachricht. Der Generative AI Agent verhält sich anders: Er verpackt die eingehende Nachricht unter einem neuen Schlüssel last_message und fügt seinen eigenen Output unter dem Schlüssel generation hinzu.

// Eingehende Nachricht
{ "file_content": "...", "dokument_typ": "Rechnung" }

// Ausgehende Nachricht nach Generative AI Agent
{
  "generation": "{ \"dokument_typ\": \"Rechnung\", \"positionen\": [...] }",
  "last_message": {
    "file_content": "...",
    "dokument_typ": "Rechnung"
  }
}

Werden mehrere Generative AI Agents hintereinandergeschaltet, entsteht eine tiefe Verschachtelung: Jeder Agent legt eine weitere last_message-Ebene an. Nach drei Agents liegt die ursprüngliche Information drei Ebenen tief — und nachgelagerte Agenten, die einen bestimmten Schlüssel auf der obersten Ebene erwarten, finden ihn nicht.

Der JSON Merge Agent verändert die Struktur ebenfalls​

Auch der JSON Merge Agent — der nach einem JSON Split genutzt wird, um aufgeteilte Verarbeitungspfade wieder zusammenzuführen — gibt eine Ausgabenachricht zurück, die sich strukturell von der ursprünglichen Eingangsnachricht unterscheidet. Wer nach einem Merge direkt weiterarbeitet, ohne die Struktur zu prüfen, riskiert stille Fehler.

Bedingte Pfade machen die Struktur situationsabhängig​

In Workflows mit Fallunterscheidungen (Switch Agent) können verschiedene Verarbeitungspfade durchlaufen werden — je nach Dokument, Kategorie oder Inhalt. Manche Pfade enthalten einen Generative AI Agent, andere nicht. Am Ende eines solchen Verzweigungsbaums ist die Struktur der Nachricht davon abhängig, welcher Pfad durchlaufen wurde. Das macht es unmöglich, im nachgelagerten Schritt zuverlässig auf einen bestimmten Schlüssel zuzugreifen.

2. Die Lösung: SQL-Persistenz als Normalisierungsschicht​

Das Prinzip ist einfach: Anstatt die Nachricht mit all ihrer strukturellen Geschichte durch den gesamten Workflow zu schleifen, werden die relevanten Ergebnisse nach abgeschlossenen Verarbeitungsabschnitten in eine SQL-Datenbank geschrieben — und vor dem nächsten Verarbeitungsabschnitt aus der Datenbank geholt.

Was aus der Datenbank geholt wird, hat immer dieselbe, definierte Struktur — unabhängig davon, welcher Pfad zuvor durchlaufen wurde, wie viele Generative AI Agents verschachtelt haben oder was der JSON Merge Agent aus der Nachricht gemacht hat.

[Verarbeitungsabschnitt A]
    → GenAI Agent, Switch, Merge — Struktur unklar
          ↓
[Internal Storage Agent: WRITE]
    → relevante Felder gezielt in SQL-Tabelle schreiben
          ↓
         ...
[Internal Storage Agent: READ]
    → definierte Spalten aus Tabelle lesen → saubere, vorhersagbare Struktur
          ↓
[Verarbeitungsabschnitt B]
    → arbeitet immer auf derselben, bekannten Struktur

3. Der Internal Storage Agent​

42°OS stellt pro Nutzer einen eigenen Internal Storage bereit — eine SQLite-Datenbank, in der beliebige Tabellen angelegt werden können. Der Zugriff erfolgt ausschließlich über den Internal Storage Agent.

Konfiguration​

Im Internal Storage Agent wird direkt ein SQL-Statement eingegeben — sowohl für Schreiboperationen (INSERT, UPDATE) als auch für Leseoperationen (SELECT). Es gibt keinen gesonderten Read- und Write-Agenten; die Unterscheidung erfolgt allein durch das SQL-Statement.

Liquid Templating in SQL-Statements​

Besonders nützlich: In den SQL-Statements kann Liquid Templating genutzt werden, um Werte aus der eingehenden Nachricht direkt in die Abfrage einzusetzen.

INSERT INTO verarbeitete_dokumente
  (dokument_id, dokument_typ, lieferant, verarbeitungsstatus)
VALUES
  ('{{ dokument_id }}', '{{ dokument_typ }}', '{{ lieferant_name }}', 'extrahiert');

Das ermöglicht es, ohne vorgelagerten Transformationsschritt direkt aus der Nachricht in die Datenbank zu schreiben. Beim Lesen funktioniert es ebenso:

SELECT dokument_id, dokument_typ, lieferant, positionen
FROM verarbeitete_dokumente
WHERE dokument_id = '{{ dokument_id }}';

4. Wann schreibt man in die Datenbank?​

Eine pauschale Antwort gibt es nicht. Die sinnvollen Wegschreib-Punkte ergeben sich aus der Workflow-Logik. Als Orientierung:

Nach einem Generative AI Agent, wenn dessen Output in nachgelagerten Schritten genutzt wird und die Verschachtelung zu einem Problem werden könnte — insbesondere wenn danach weitere Agenten folgen, die eine flache Nachrichtenstruktur erwarten.

Nach einem JSON Merge Agent, weil die zusammengeführte Nachricht eine andere Struktur hat als die ursprünglichen Einzelnachrichten. Das Wegschreiben erzwingt eine bewusste Entscheidung darüber, welche Felder danach relevant sind.

An Übergabepunkten zwischen logischen Abschnitten — zum Beispiel zwischen Extraktion und Weiterleitung, zwischen Prüfung und Buchung. Das macht den Workflow wartbarer, weil jeder Abschnitt klar definierte Ein- und Ausgaben hat.

In State-Machine-Architekturen, wenn ein komplexer Workflow in modulare Abschnitte aufgeteilt ist, die in unterschiedlicher Reihenfolge, mehrfach oder gar nicht durchlaufen werden können. Die SQL-Datenbank fungiert hier als gemeinsamer Zustandsspeicher — jeder Abschnitt liest seinen Startzustand aus der Datenbank und schreibt seinen Endzustand zurück. Dadurch ist es irrelevant, welcher Abschnitt zuvor gelaufen ist.

💡 Faustregel: Sobald du dich dabei ertappst, dass du in einem nachgelagerten Agenten über last_message.last_message.generation navigierst — ist es Zeit, einen Normalisierungsschritt einzubauen.

5. Ein konkretes Beispiel​

Ein Workflow verarbeitet eingehende Dokumente aus einem E-Mail-Postfach. Pro E-Mail können mehrere Anhänge eingehen, die zunächst per Generative AI Agent kategorisiert und anschließend — wenn es sich um Rechnungen handelt — erneut per Generative AI Agent auf Feldebene extrahiert werden.

Ohne SQL-Persistenz ergibt sich am Ende folgendes Bild:

{
  "generation": "{ \"positionen\": [...] }",
  "last_message": {
    "generation": "Rechnung",
    "last_message": {
      "file_content": "...",
      "filename": "rechnung_042.pdf"
    }
  }
}

Der nachgelagerte Schritt — etwa das Schreiben ins ERP — müsste wissen, dass generation aus dem zweiten Generative AI Agent kommt und filename zwei Ebenen tiefer liegt. Ändert sich der Workflow, bricht diese Navigation.

Mit SQL-Persistenz nach jedem Generative AI Agent sieht die Nachricht vor dem ERP-Schritt immer so aus:

{
  "dokument_id": "2026-042",
  "dokument_typ": "Rechnung",
  "lieferant_name": "Muster GmbH",
  "dokument_datum": "2026-03-06",
  "positionen": [...]
}

Flach, vorhersagbar, wartbar — unabhängig davon, welche Verarbeitungshistorie dahinterliegt.

6. Zusammenfassung​

SituationEmpfehlung
Nach einem Generative AI Agent mit nachgelagerter VerarbeitungIn Datenbank schreiben, aus Datenbank lesen
Nach einem JSON Merge AgentStruktur normalisieren via SQL
Bedingte Pfade mit unterschiedlichen VerarbeitungstiefenSQL als gemeinsame Ausgangsbasis vor dem nächsten Abschnitt
Modulare State-Machine-WorkflowsSQL als zentraler Zustandsspeicher zwischen Abschnitten
Einfacher linearer Workflow ohne GenAI/MergeSQL-Persistenz optional, nur wenn Wartbarkeit es erfordert

📹 Video zu diesem Kapitel: [Platzhalter — Screencast: Internal Storage Agent konfigurieren — INSERT und SELECT mit Liquid Templating] 📸 Screenshots: [Platzhalter — Internal Storage Agent SQL-Statement, verschachtelte Nachrichtenstruktur vor/nach Normalisierung]

Vorheriges Kapitel: [[Daten aus Dokumenten extrahieren und strukturieren]] Nächstes Kapitel: [[Lernfähigen Assistenten erstellen]]