Agenten verketten: Ablageziel, neue Dateien einzeln, JSON-Ergebnis

Admin

Ein Agent liest eine Quelle und arbeitet mit seinen Werkzeugen. Mehrere Agenten lassen sich zu einer Kette verbinden: Der erste legt Dateien ab, der nächste verarbeitet jede neue Datei in einem eigenen Lauf und liefert ein strukturiertes Ergebnis, ein dritter arbeitet damit weiter. Dafür gibt es auf der Agentenseite vier Einstellungen: das Ablageziel, den Lesestand „Nur neue Dateien“, den Lauf je Datei bzw. Lauf je Mail und das Ergebnis-Schema. Wie man einen Agenten grundsätzlich anlegt und testet: → Einen Agenten anlegen und im Trockenlauf testen

Ablageziel: wohin der Agent schreibt

Im Tab Geltungsbereich, Abschnitt Ablageziel, legen Sie fest, wohin der Agent schreiben darf. Das Ziel wird beim Lauf erzwungen; das Modell kann nicht daran vorbei schreiben.

Ziel	Einstellungen	Schreibt dorthin
Keins	—	wie ohne Ziel
Tresor	Tresor, Ordner im Tresor (leer = Tresorwurzel), Unterordner erlauben, Mail-Ablage	Wissenswerkzeuge (Artikel anlegen, ändern, verschieben, löschen; E-Mail in der Wissensdatenbank ablegen)
Arbeitsordner	Arbeitsordner (absoluter Pfad); Unterordner sind immer erlaubt	Arbeitsordner-Werkzeuge und Skript-Skills; nur in der Desktop-App

Werkzeuge der anderen Art entfallen: Unter einem Tresor-Ziel bietet der Lauf keine schreibenden Arbeitsordner-Werkzeuge an, unter einem Arbeitsordner-Ziel keine schreibenden Wissenswerkzeuge. Die Seite zeigt, welche der ausgewählten Werkzeuge entfallen: „Diese ausgewählten Werkzeuge werden bei diesem Ziel nicht angeboten: …“. Aktionen, die nur das Postfach oder eine Nachricht betreffen (Mail senden, archivieren, als verarbeitet markieren), bleiben bei jedem Ziel.
Dateien landen im Ziel: Office-Dokumente (Präsentation, Tabelle, ausgefüllte Word-Vorlage) und heruntergeladene Mail-Anhänge legt der Agent im Ziel ab. Beim Tresor-Ziel landen sie im Unterordner attachments/ des Zielordners — alle mit Leserecht auf den Tresor können sie sehen. Kann das Ziel eine Datei nicht aufnehmen (Ordner fehlt, Name nicht erlaubt), lehnt das Werkzeug mit Grund ab; einen Ausweichort gibt es nicht.
Skript-Skills werden mit Tresor-Ziel nicht angeboten. Mit Arbeitsordner-Ziel schreiben Skripte in den Zielordner. → Skript-Skills
E-Mail in der Wissensdatenbank ablegen: Mit Tresor-Ziel gibt das Ziel den Tresor vor; ein Ordner im Aufruf liegt unterhalb des Zielordners. → Werkzeuge: E-Mail
Mail-Ablage: Legt fest, in welcher Form das Werkzeug eine HTML-Mail als Artikel ablegt. Inhalt (Markdown, gut für die Suche) wandelt Newsletter-Layouts in lesbaren Text mit Links und Online-Bildern um, damit die Wissenssuche sie findet; Tracking-Pixel fallen weg. Darstellung (Layout wie im Original) behält das HTML-Layout wie bisher. Ein neu gewähltes Tresor-Ziel startet auf Inhalt; Agenten, deren Ziel schon vorher bestand, bleiben bei Darstellung, bis Sie umstellen. Die Einstellung gilt nur für den Mailtext, nicht für Anhänge, und nicht für die Importseite. Bereits abgelegte Mails werden nach einem Wechsel nicht neu abgelegt; wer das will, löscht den alten Artikel vorher.
Prüfung: Ein Arbeitsordner-Ziel muss existieren und darf nicht im Skills- oder Skript-Datenordner liegen. Geprüft wird beim Speichern und bei jedem Laufstart; schlägt die Prüfung beim Start an, endet der Lauf mit dem Grund, bevor ein Werkzeug läuft. Im Web-Modus ist „Arbeitsordner“ als Ziel nicht wählbar.

Tresor-Quelle: nur neue Dateien, je Datei ein Lauf

Quell-Adapter Tresor im Tab Geltungsbereich — neben Vault, Ordnerpfad und Datei-Glob gibt es zwei Häkchen:

Nur neue Dateien: Jede Datei wird genau einmal verarbeitet. Beim ersten Lauf merkt sich der Agent alle Dateien, die schon im Ordner liegen, als gelesen und verarbeitet nichts (Basislinie). Erst danach hinzukommende Dateien gelten als neu. Schalten Sie die Option deshalb ein und lassen Sie den Agenten einmal laufen, bevor der Ordner befüllt wird — sonst landen die ersten Dateien in der Basislinie. Höchstens 25 neue Dateien je Lauf; der Rest folgt beim nächsten Lauf. Die Basislinie gilt je Ordner: Nach einem Ordnerwechsel setzt der nächste Lauf eine neue.
Lauf je Datei: Jede Datei bekommt einen eigenen Lauf mit frischem Kontext, nacheinander, höchstens 25 je Start. Ist ein Lauf nicht sauber (fehlgeschlagen, Ablage- oder Skriptfehler), hält die Kette an; die übrigen Dateien folgen beim nächsten Start. Ein Probelauf verarbeitet nur die erste Datei. Hat ein manueller Start nichts zu tun, meldet die Seite „Der Agent ’…’ hat keine neuen Elemente zu verarbeiten.“
Fehlversuche: Scheitert ein Lauf an einer Datei — auch durch ein fehlgeschlagenes Skript —, zählt das als Versuch. Nach dem dritten Versuch gilt die Datei als verarbeitet und wird nicht wieder angefasst; der Lauf nennt sie: „Nach 3 Fehlversuchen übersprungen und nicht erneut verarbeitet: …“. Fehler, bevor das Modell startet (kein Modell, Budget-Grenze, PII-Schutz), zählen nicht. Dateien im Tresor werden nie verschoben.
Kreislauf-Schutz: Liest der Agent nur neue Dateien aus dem Ordner, in den er selbst ablegt (Tresor-Ziel im Quellordner oder darunter), lehnt die Seite das Speichern ab: „Der Agent liest nur neue Dateien aus dem Ordner, in den er selbst ablegt – jede eigene Ablage würde den nächsten Lauf auslösen. …“

Wer den Lesestand fortschreibt: nur geplante Läufe und Starts von der Agentenseite. Probelauf, Workflow-Schritt und Chat-Delegation lesen mit dem Lesestand, markieren aber nichts als verarbeitet.

Postfach-Quelle: je Mail ein Lauf

Quell-Adapter E-Mail — Mail-Konto, Ordner, Absenderfilter, Nur ungelesene (Standard an; POP3 kennt keinen Gelesen-Status und ignoriert das Häkchen) und Max. Elemente pro Lauf.

Lesestand am Zeitplan: Ein Postfach-Agent merkt sich am Zeitplan-Auslöser, bis zu welcher Mail er gelesen hat; jeder geplante Lauf holt die ältesten Mails nach diesem Stand. Der erste Lauf und jeder manuelle Start ohne Auslöser nehmen die neuesten Mails und merken sich nichts. Wechseln Konto oder Ordner, beginnt der Stand neu.
Lauf je Mail: Jede neue Mail bekommt einen eigenen Lauf, älteste zuerst, höchstens „Max. Elemente pro Lauf“ je Start. Ein Probelauf verarbeitet nur die erste Mail. Wie beim Lauf je Datei hält die Kette beim ersten nicht sauberen Lauf an.
Fehlversuche: Eine Mail hat drei Versuche — gezählt werden ein gescheitertes Ablegen in die Wissensdatenbank und, im Lauf je Mail, ein Skriptfehler. Sie kommt auch dann wieder dran, wenn der gescheiterte Lauf sie schon als gelesen markiert hat; nach dem dritten Versuch wird sie übersprungen. Ablehnungen wegen der Konfiguration (Konto, Tresor, schreibgeschützt) zählen nicht. Den Warnblock dazu beschreibt → Werkzeuge: E-Mail

Arbeitsordner-Quelle (Desktop)

Quell-Adapter Arbeitsordner — Eingangsordner (absoluter Pfad), Datei-Glob, Max. Elemente pro Lauf (höchstens 25) und Lauf je Datei.

Was gelesen wird: Textdateien (z. B. .txt, .md, .csv, .json, .xml) direkt im Eingangsordner, älteste zuerst — keine Unterordner, keine Dateien mit Punkt am Anfang. Eine Datei kommt erst dran, wenn sie mindestens 10 Sekunden alt ist, damit keine halb geschriebene gelesen wird. Je Datei bis 32 000 Zeichen (der Rest wird mit Vermerk gekürzt), je Lauf 120 000; was nicht mehr passt, wartet auf den nächsten Lauf. Andere Dateiarten bleiben liegen.
Dateien wandern: Während eines Laufs liegt die Datei im verborgenen Ordner .in-arbeit, nach Erfolg in erledigt, nach drei Fehlversuchen in fehler (der Lauf nennt sie). Gelöscht wird nichts; eine gleichnamige Datei bekommt (2) angehängt. Konnte eine verarbeitete Datei nicht verschoben werden, meldet der Lauf „Verarbeitet, aber nicht nach „erledigt/“ verschoben …“ und verarbeitet sie beim nächsten Mal erneut.
Nur verbrauchende Läufe verschieben: geplante Läufe und Starts von der Agentenseite. Probelauf, Workflow-Schritt und Chat-Delegation lesen die Dateien an Ort und Stelle.
Kreislauf-Schutz: Das Ablageziel darf nicht der Eingangsordner oder einer seiner Ordner erledigt, fehler, .in-arbeit sein; ein anderer Unterordner geht.
Nur Desktop: Im Web-Modus fehlt die Quelle. Startet ein Agent mit dieser Quelle dort trotzdem (etwa über einen Workflow), scheitert er mit „Die Quelle „Arbeitsordner“ gibt es nur in der Desktop-App. …“. Auf Netz- und Cloud-Laufwerken ohne atomares Umbenennen kann eine Datei doppelt gegriffen werden.

Ergebnis-Schema: JSON statt Fließtext

Im Tab Reasoning, Feld Ergebnis-Schema (JSON, optional), hinterlegen Sie ein JSON-Schema-Objekt, zum Beispiel:

{
  "type": "object",
  "properties": {
    "titel":  { "type": "string" },
    "themen": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["titel"]
}

Ablauf: Nach der Werkzeugschleife wandelt der Lauf seine Abschlussantwort in dieses JSON um. Geprüft werden nur gültiges JSON und die Pflichtfelder (required) der obersten Ebene; weitere Regeln gehen nur als Hinweis an das Modell. Die Umwandlung sieht nur die Abschlussantwort — formulieren Sie die Anweisung so, dass diese alle verlangten Angaben enthält.
Wo das Ergebnis steht: in der Laufansicht unter Ergebnis (JSON), mit echten Werten, auch wenn der Lauf mit pseudonymisierten Daten gearbeitet hat. Mit Arbeitsordner-Ziel zusätzlich als Datei im Zielordner: <Dateiname>.json nach der gelesenen Tresor-Datei (ein zweiter Lauf derselben Datei überschreibt sie), sonst run-<Laufnummer>.json. Die Datei wird erst unter einem Namen mit Punkt am Anfang geschrieben und dann umbenannt, sodass eine nachfolgende Arbeitsordner-Quelle nie eine halbe Datei sieht. Mit Tresor-Ziel landet kein JSON in der Wissensdatenbank — das Ergebnis steht nur am Lauf.
Probelauf: Das Ergebnis steht am Lauf, eine Datei wird nicht geschrieben.
Wenn es scheitert: Passt die Antwort nicht zum Schema, endet der Lauf mit „Das Ergebnis passt nicht zum Ergebnis-Schema des Agenten (…). …“; die Quelle wird beim nächsten Lauf erneut verarbeitet. Lässt sich die Datei nicht schreiben, meldet der Lauf „Die Ergebnisdatei ’…’ konnte nicht in den Zielordner geschrieben werden. …“.
Im Workflow bindet ein Folgeschritt einzelne Felder mit {{steps.<id>.output.result.<feld>}}. → Workflows anlegen und ausführen

Drei Agenten, jeder mit eigenem Zeitplan:

„Newsletter ablegen“ — Quelle E-Mail mit Absenderfilter, Ablageziel Tresor default, Ordner Newsletter, Mail-Ablage Inhalt, Werkzeug E-Mail in der Wissensdatenbank ablegen, Ausführen als Benutzer gesetzt. Prompt wie in Rezept 1 unter → Werkzeuge: E-Mail
„Newsletter auswerten“ — Quelle Tresor, Ordnerpfad Newsletter (der Standard-Glob **/*.md liest auch Unterordner wie Newsletter/A), Nur neue Dateien und Lauf je Datei; Ablageziel Arbeitsordner z. B. /Users/name/Newsletter-JSON; Ergebnis-Schema wie oben. Jeder neue Newsletter ergibt genau eine JSON-Datei.
„Themen sammeln“ — Quelle Arbeitsordner, Eingangsordner /Users/name/Newsletter-JSON; Ablageziel z. B. Tresor default, Ordner Newsletter-Übersichten — nicht unter Newsletter, sonst liest Agent 2 die Übersichten als neue Newsletter mit. Verarbeitete JSON-Dateien wandern nach erledigt.

Reihenfolge beim Einrichten — von hinten nach vorn:

Agent 2 anlegen, solange der Ordner Newsletter leer ist (oder nur Altes enthält, das nicht ausgewertet werden soll), und einmal Ausführen — das setzt die Basislinie und verarbeitet nichts.
Agent 3 anlegen. Die Arbeitsordner-Quelle kennt keine Basislinie: Alles, was dann im Eingangsordner liegt, wird verarbeitet.
Erst jetzt Agent 1 einschalten.

Takt: Die Zeitpläne der hinteren Stufen liegen nach der vorderen (z. B. stündlich zur Minute 0, 10 und 20). Jede Stufe einzeln testen: Ein Probelauf von Agent 2 verarbeitet die erste neue Datei und zeigt das Ergebnis, schreibt aber keine Datei.

Statt Dateien: ein Workflow. Sollen die Stufen in einem Zug laufen, verbindet ein Workflow sie mit agent.run-Schritten und reicht Werte über {{steps.<id>.output.result.<feld>}} weiter — nicht über Dateien: Ein Workflow-Schritt schreibt keinen Lesestand fort, und eine gerade geschriebene Datei ist für einen direkt folgenden Schritt noch keine 10 Sekunden alt und damit unsichtbar. → Workflows anlegen und ausführen

Grenzen

Arbeitsordner als Ziel und als Quelle gibt es nur in der Desktop-App; geplante Agenten laufen dort nur, solange die App geöffnet ist. → Web vs. Desktop
Workflow-Schritt und Chat-Delegation starten genau einen Lauf, teilen nicht auf und schreiben keinen Lesestand fort.
Export/Import: Ablageziel, Ergebnis-Schema und Lesestand gehen nicht in den Export. Ein Import mit Überschreiben setzt den Lesestand zurück: Der nächste Lauf setzt nur eine neue Basislinie, nichts wird erneut verarbeitet. Ohne Überschreiben bleibt der vorhandene Agent unverändert.

Verwandt

Das Agenten-Modell
Agenten (Referenz)
Werkzeuge: Viele Dateien oder Mails einzeln verarbeiten — einzeln verarbeiten innerhalb eines Laufs