Managed Flows¶

Managed Flows erlauben es dem AI-Engineering-Team, einen Flow einmal auf der internen prod-Agentlab-Instanz zu bauen und ihn kontrolliert auf andere Instanzen auszurollen: global und Kundeninstanzen. Vor jedem Rollout läuft ein Probelauf gegen das Ziel, bevor irgendetwas geschrieben wird. Jeder Rollout lässt sich zurückrollen und hinterlässt einen Audit-Trail.

Diese Seite richtet sich an die Personen, die diesen Prozess betreiben: Flows kennzeichnen, Revisionen erfassen und promoten, und hinterher aufräumen.

Die eine Regel

Ein Managed Flow wird ausschließlich auf der Quellinstanz (prod) bearbeitet. Seine Kopien auf den Zielinstanzen sind gesperrt, und es gibt keine Entsperrung. global hat keine menschlichen Nutzer, und jeder Schreibvorgang dorthin kommt aus dieser Pipeline. Muss sich eine Zielkopie ändern, ändere die Quelle und promote sie.

Wie das Ganze zusammenhängt¶

flowchart LR
    subgraph Source["prod (Quelle)"]
        Flow["Flow"]
    end
    subgraph Studio["Karli Studio · Managed Flows"]
        MF["Managed Flow"]
        Rev["Revisionen
(unveränderliche Snapshots)"]
        B1["Bindung → global"]
        B2["Bindung → Kundeninstanz"]
        MF --> Rev
        MF --> B1
        MF --> B2
    end
    Flow -- "kennzeichnen" --> MF
    B1 -- "Rollout" --> G["global"]
    B2 -- "Rollout" --> C["Kundeninstanz"]

Managed Flow — ein Flow auf prod, der für die Promotion gekennzeichnet wurde.
Revision — ein unveränderlicher Snapshot des Quell-Flows. Promotet werden ausschließlich Revisionen, nie der laufende Quell-Flow direkt.
Zielinstanz — eine Agentlab-Instanz, auf die ein Managed Flow promotet wird.
Bindung — die Verknüpfung zwischen einem Managed Flow und einem Flow auf einer Zielinstanz. Pro Managed Flow und Instanz gibt es höchstens eine Bindung.
Rollout — ein Versuch, eine Revision über eine Bindung anzuwenden. Auch Zurückrollen, Deaktivierungen und Löschungen werden als Rollouts erfasst, sodass alles im selben Verlauf erscheint.

Zugriff¶

Managed Flows findest du im Einstellungsmenü am Fuß der Navigationsleiste von Karli Studio. Du brauchst eine von zwei Keycloak-Realm-Rollen:

Rolle	Darf
Managed Flow Admin	Alles, was ein Developer darf, und zusätzlich: Ziele hinzufügen, Bindungen konfigurieren (Zielprojekt, Flow-Name, Variablen-Umbenennung), Übernahmen bestätigen, Bindungen deaktivieren, reaktivieren und löschen. Nur Admins sehen den Managed-Flow-Schalter in Agentlab.
Managed Flow Developer	Revisionen erfassen, Diffs ansehen, Probeläufe und Rollouts erstellen, zurückrollen, alles einsehen.

Diese Rollen sind unabhängig von den üblichen Admin-Rechten in Karli: Ein Karli-Super-Admin hat keinen Zugriff auf Managed Flows, solange ihm nicht zusätzlich eine dieser Rollen zugewiesen wurde. Ohne Rolle zeigt die Seite Kein Zugriff auf Managed Flows.

Freigaben für Zielinstanzen¶

Ein Admin kann Ziele nur auf Instanzen hinzufügen, die ihm ein Super-Admin freigegeben hat. Bis dahin meldet der Dialog zum Hinzufügen von Zielen, dass noch keine Zielinstanzen freigegeben wurden. Das ist erwartetes Verhalten, kein Fehler. Das gilt auch für Super-Admins, die selbst Managed-Flow-Admins sind.

Für Freigaben gibt es noch keine Oberfläche in Studio; ein Super-Admin setzt sie über die API (PUT /api/v1/admin/users/{userId}/target-instances).

Der Entzug einer Freigabe verhindert nur neue Ziele. Bestehende Bindungen bleiben aktiv und erhalten weiterhin Rollouts. Um ein Ziel außer Betrieb zu nehmen, deaktiviere oder lösche seine Bindung.

Die Managed-Flows-Seite¶

Die Seite hat zwei Ansichten, die oben umgeschaltet werden. Studio merkt sich, welche du zuletzt verwendet hast.

Nach Flow — ein Eintrag pro Managed Flow, mit Tabs für seine Ziele, Revisionen, Konfiguration und den Verlauf.
Alle Agenten — jede Bindung über alle Flows hinweg in einer Tabelle, nach Status filterbar. Das ist der schnellste Weg zur Frage „Ist dieser Flow auf jener Instanz verwaltet?“

Kann Studio die Middleware nicht erreichen, zeigt die Seite Die Middleware ist nicht erreichbar. mit einer Schaltfläche Neu verbinden. Rollouts sind deaktiviert, bis die Verbindung wiederhergestellt ist.

Einen Flow kennzeichnen¶

Die Kennzeichnung erfolgt in Agentlab, auf prod:

Öffne den Publish-Dialog des Flows.
Aktiviere Managed flow und veröffentliche.

Der Schalter erscheint nur für Managed Flow Admins und nur auf der Quellinstanz. Auf einer Zielinstanz erscheint er nie, unabhängig von deiner Rolle.

Die Kennzeichnung kopiert nichts. Der Flow taucht auf der Managed-Flows-Seite auf, und alles Weitere (Ziele, Projekt, Variablen) wird dort konfiguriert. In Agentlab erhält er das Badge Verwaltete Quelle und bleibt vollständig bearbeitbar — das Badge hält lediglich fest, dass Promotions hier ihren Ursprung haben.

Zum Aufheben der Kennzeichnung schaltest du den Schalter wieder aus. Damit wird der Managed Flow archiviert und alle seine Bindungen werden deaktiviert. Kennzeichnest du denselben Flow später erneut, wird er mit seinen alten Revisionen und Bindungen wiederbelebt. Wurde die Zielkopie zwischenzeitlich bearbeitet, blockiert die Abweichung den nächsten Rollout auf global.

Ein Flow auf prod lässt sich nicht löschen?

Ein gekennzeichneter Flow kann bearbeitet, aber nicht gelöscht werden. Agentlab zeigt nur die generische Meldung Fehler beim Löschen von Elementen / Wiederholen Sie die Operation. Ein erneuter Versuch hilft nicht: Hebe zuerst die Kennzeichnung auf.

Eine Revision erfassen¶

Ist der Quell-Flow fertig, wähle Revision erfassen und ergänze eine Notiz, was sich geändert hat. Die Notiz erscheint im Verlauf und im Rollout-Dialog. Hat sich die Quelle seit der letzten Revision nicht geändert, gibt es nichts zu erfassen und die Schaltfläche bleibt deaktiviert.

Der Tab Revisionen listet alle Revisionen und zeigt, wo jede gerade läuft (Aktiv auf).

Den Diff lesen¶

Es gibt zwei Diffs, und bei keinem lässt sich das Paar frei wählen:

Diff in einer Revisionszeile vergleicht sie mit der Revision davor.
Diff in einer Zielzeile vergleicht die neueste Revision mit dem, was aktuell auf diesem Ziel liegt. Der Dialogtitel lautet trotzdem „Revisionen vergleichen“.

Nodes mit umgebungsgebunden wirkenden Werten werden als umgebungsgebunden vermutet markiert. Klicke den Node an, um den Wert und seine Art zu sehen: URL, IP oder ABSOLUTE_PATH. Werte innerhalb von Custom-Component-Code werden mit erfasst. Hostnamen und Collection-Namen werden nicht erkannt. Der Diff markiert diese Werte, blockiert aber nichts. Behandle jede Markierung als Fehler im Flow (siehe Variablen).

Ein Ziel hinzufügen¶

Ziel hinzufügen legt eine Bindung an. Wähle die Zielinstanz; die Liste zeigt nur Instanzen, die dir freigegeben und noch nicht gebunden sind. Wähle dann die Art der Bindung. Es gibt zwei, und die Wahl ist wichtig.

Neu anlegen ist für einen Flow, den es auf dem Ziel noch nicht gibt. Der erste Rollout legt bei Bedarf das Zielprojekt an, erstellt den Flow, prüft, ob er baut, und veröffentlicht ihn. Anschließend wird automatisch ein Karli-Agent dafür erstellt. Dieser Agent wird zentral betrieben: kein Self-Service, nicht öffentlich, und mit denselben Admins wie der Quell-Flow.

Bestehenden Flow übernehmen ist für einen Flow, den es auf dem Ziel bereits gibt — etwa einen, der vor dieser Funktion von Hand kopiert wurde. Die Übernahme behält die ID dieses Flows und damit seinen Chat-Verlauf. Neu anlegen würde für einen solchen Flow eine zweite Kopie neben die bestehende stellen.

Bei der Übernahme:

Wähle den Flow aus dem Projektmenü. Flows, die bereits verwaltet werden, sind ausgegraut: Ein Flow kann nur zu einer aktiven Bindung gehören.
Die Bindung tut nichts, bis ein Admin sie bestätigt (Bestätigen, dann Übernahme bestätigen). Der Dialog nennt, welcher von zwei Fällen vorliegt:
- Bestehender Karli-Agent — wird übernommen. Ab jetzt überschreiben Rollouts den Flow hinter diesem Agenten. Chat-Sitzungen bleiben erhalten.
- Noch kein Karli-Agent — einer wird erstellt beim ersten Rollout.
Bestätige durch Eingabe des Instanz-Slugs. Hat sich die Agent-Situation des Flows geändert, nachdem du den Dialog geöffnet hast, wird die Bestätigung verweigert; schließe den Dialog und öffne ihn erneut.

Zielprojekt und Flow-Name¶

Beide werden im Dialog zum Hinzufügen des Ziels gesetzt. Das Zielprojekt kann ein bestehendes Projekt oder ein neuer Name sein; es wird beim ersten Rollout per Name aufgelöst oder angelegt.

Eine Bindung vom Typ Neu anlegen scheitert beim ersten Rollout, wenn im Zielprojekt bereits ein Flow desselben Namens existiert. Sie übernimmt diesen Flow nicht und legt auch kein Duplikat an. Übernimm entweder den bestehenden Flow, oder setze einen Ziel-Flow-Namen. Beide Felder lassen sich unter Bearbeiten ändern, bis der erste Rollout gelaufen ist. Danach verschwinden sie kommentarlos aus dem Dialog. Name, Untertitel und Symbol des Agenten werden am Agenten selbst bearbeitet und überstehen Rollouts.

Rollout angewendet, aber kein Agent?

Die Erstellung des Agenten setzt voraus, dass die Zielinstanz zu einer Firma in Karli gehört. Ist das nicht der Fall, wird der Flow trotzdem ausgerollt und der Rollout zeigt Angewendet, aber es existiert kein Agent. Der einzige Hinweis ist eine Zeile AGENT_MATERIALIZE_FAILED, wenn du diesen Rollout im Verlauf aufklappst. Sobald die Instanz einer Firma zugeordnet ist, erstellt der nächste Rollout den Agenten.

Variablen¶

Alles, was sich zwischen Umgebungen unterscheidet (API-Schlüssel, Endpunkte, Collection-Namen), muss eine globale Variable in Agentlab sein — niemals ein in eine Komponente getippter Wert und niemals ein Literal in Custom-Component-Code. Es gibt bewusst keine Möglichkeit, Komponentenwerte pro Ziel zu überschreiben; ein fest verdrahteter Wert ist also überall fest verdrahtet. Ein Flow, der gegen diese Regel verstößt, besteht jede Prüfung und fällt dann auf einer Instanz aus, die niemand beobachtet.

Heißt eine Variable auf dem Ziel anders als auf prod, ordne sie unter Bearbeiten → Variablen-Umbenennung zu. Die Felder schlagen die auf der jeweiligen Instanz vorhandenen Variablen vor, du kannst aber jeden Namen eintippen. Das Bearbeiten der Zuordnung wird als Zuordnungsänderung erfasst, nicht als Abweichung.

Promoten¶

Rollout erstellen, dann Revision, Ziele und Auslösung wählen:

Jetzt — wird sofort angewendet. Studio wartet, bis der Rollout durchgelaufen ist, was bei großen Flows einen Moment dauern kann.
Ab Version — der Rollout wartet, bis das Ziel auf mindestens diese Agentlab-Version aktualisiert wird, und wird während des Upgrades angewendet. Schlägt er dabei fehl, bricht das Upgrade ab. Nutze das, wenn eine Revision erst auf einem neueren Agentlab läuft als dem, das auf dem Ziel aktuell installiert ist. Das Versionsfeld wird nicht validiert, tippe also sorgfältig (z. B. 1.3.2).

Wartende Rollouts lassen sich nicht abbrechen

Sobald der Dialog geschlossen ist, taucht ein wartender Rollout nirgends in Studio auf, bis er gelaufen ist, und Studio kann ihn nicht abbrechen (die API kann es: POST /api/v1/rollouts/{id}/cancel). Plane versionsgebundene Rollouts nur, wenn du dir sicher bist.

Ein Probelauf ist verpflichtend: Ausrollen bleibt deaktiviert, bis für jedes ausgewählte Ziel ein Probelauf bestanden wurde. Jede Änderung im Dialog setzt den Probelauf zurück. Der Probelauf zeigt jede Prüfung mit ihrem Ergebnis und schreibt nichts. Das Ergebnis BLOCKED_GATE bedeutet „wartet auf die Version“, nicht Fehlschlag.

Die Prüfungen, die Probelauf und Rollout gegen das Ziel ausführen:

Das Ziel ist erreichbar, als Promotionsziel eingerichtet und meldet seine Agentlab-Version. Eine Instanz, die keine Version melden kann, passiert nie eine Versionsprüfung.
Die Bindung ist verwendbar. Eine unbestätigte Übernahme scheitert hier.
Abweichung — niemand hat die Zielkopie seit dem letzten Rollout verändert. Für welche Instanzen das schützt, siehe unten.
Variablen — jede referenzierte globale Variable existiert auf dem Ziel (direkt oder über die Zuordnung) mit dem richtigen Typ (Credential vs. Generic), und die benötigten Modell-Provider sind aktiviert.
Build — die Revision baut auf dem Ziel, Komponente für Komponente. Das fängt die Komponenten- und Template-Unterschiede ab, die Flows nach einem Upgrade zerlegen.

Nur wenn alles besteht, wird der Flow geschrieben. Ein bestehender Ziel-Flow wird an Ort und Stelle aktualisiert, sodass seine ID und sein Chat-Verlauf erhalten bleiben.

Die Abweichungsprüfung schützt nur global

Auf global blockiert eine von Hand bearbeitete Zielkopie den Rollout. Auf jeder anderen Instanz vermerkt der Probelauf die Abweichung, und der Rollout überschreibt die Änderungen. Das ist so gewollt, weil Kundenänderungen an Managed Flows überschrieben werden sollen — wisse es aber, bevor du auf eine Kundeninstanz promotest.

Wenn eine neuere Revision einen wartenden Rollout überholt¶

Diese Einstellung erscheint nur bei Ab Version-Rollouts, als Falls überholt. Angenommen, Revision 4 wartet darauf, dass global aktualisiert wird, und in der Zwischenzeit erscheint Revision 5:

Neueste übernehmen (Standard) — stattdessen wird Revision 5 angewendet.
Nicht ausrollen — der Rollout schlägt fehl und ein Mensch entscheidet.
Trotzdem — Revision 4 wird wie festgesetzt angewendet. Bewusst einsetzen.

Ein so zurückgezogener Rollout wird als Überholt markiert, nicht als Abgebrochen. Der Verlauf zeigt weiterhin die angeforderte Revision, nicht die tatsächlich angewendete. Prüfe die Revision des Ziels im Tab Ziele.

Das Feld Gruppenbezeichnung im Rollout-Dialog hat derzeit keine Wirkung.

Zurückrollen¶

Das Zurückrollen startet im Tab Revisionen: Zurückrollen bei der Revision, zu der du zurückkehren willst.

Zurückrollen betrifft jedes Ziel

Das Zurückrollen betrifft alle Ziele, die nicht bereits auf dieser Revision sind, nicht nur eines. Der Dialog listet vor der Bestätigung auf, was überschrieben wird. Einen Probelauf gibt es dabei nicht.

Ein Zurückrollen ist ein gewöhnlicher Rollout der älteren Revision, der die Überhol-Regel ignoriert. Sitzungen und die Ziel-Flow-ID bleiben erhalten.

Status und Verlauf¶

Badge	Bedeutung
Live	Läuft auf der neuesten Revision
Veraltet	Aktiv, aber es existiert eine neuere Revision
Anlage ausstehend	Bindung vom Typ Neu anlegen, der erste Rollout hat noch nicht stattgefunden
Bestätigung erforderlich	Übernommene Bindung, noch nicht bestätigt
Deaktiviert	Deaktiviert: an die lokale Verantwortung zurückgegeben

Der Tab Verlauf listet jeden Rollout, den neuesten zuerst, mit der Person, die ihn gestartet hat. Filtere nach Status, Ziel und Zeitraum. Klappst du einen Rollout auf, siehst du seine einzelnen Ereignisse und bei Fehlschlägen die Fehlerklasse samt Detailtext.

Servergenerierter Text (Prüfdetails, Fehlermeldungen, Ereignisnamen) ist immer englisch, auch in der deutschen Oberfläche.

Wenn ein Rollout abgelehnt wird¶

Die Fehlerklassen erscheinen wörtlich im aufgeklappten Verlaufseintrag:

Klasse	Was sie bedeutet	Was zu tun ist
`DRIFT`	Die Zielkopie auf `global` wurde außerhalb der Pipeline geändert.	Finde heraus, wer sie geändert hat und warum. Soll die Änderung bleiben, übertrage sie auf die Quelle, erfasse eine Revision und promote.
`PRECONDITION`	Die Einrichtung stimmt nicht: eine fehlende oder falsch typisierte Variable, ein deaktivierter Modell-Provider, eine unbestätigte Übernahme, eine Namenskollision bei einer Neu anlegen-Bindung, oder eine Instanz, die nicht als Promotionsziel eingerichtet ist.	Der Detailtext benennt den Punkt. Fehlende Variablen und Provider auf `global` sind ein Ops-Ticket, und der Detailtext ist präzise genug, um es zu schreiben.
`VALIDATION`	Eine Komponente baut auf dem Ziel nicht.	Auf der Quelle beheben, oder Ab Version mit einem neueren Agentlab nutzen.
`INFRASTRUCTURE`	Das Ziel hat nicht geantwortet, oder Unsinn geantwortet.	Es wurde nichts geschrieben. Wiederhole, sobald das Ziel gesund ist.
`DATA`	Der Schreibvorgang lief durch, aber der zurückgelesene Flow entspricht nicht dem Gesendeten.	Selten. Vergleiche die neueste Revision per Diff mit dem Ziel und sieh dir den Flow auf der Instanz an, bevor du es erneut versuchst.

Bei PRECONDITION und VALIDATION wird nichts geschrieben.

Ein Fehler, der MANAGED_FLOWS_MODE erwähnt, bedeutet, dass die Zielinstanz für die falsche Rolle konfiguriert ist (Quelle statt Ziel). Das ist ein Ops-Problem, kein Problem des Flows.

Bindungen deaktivieren und löschen¶

Auf einer Zielzeile gibt es zwei Aktionen. Keine davon löscht den Ziel-Flow. In beiden Fällen läuft der Flow weiter, behält seinen Chat-Verlauf und wird auf der Zielinstanz wieder bearbeitbar. Genau darum geht es: den Flow an die lokale Verantwortung zurückzugeben.

Deaktivieren lässt die Bindung ausgegraut stehen, der Agent bleibt. Es erreichen keine Rollouts mehr den Flow. Reaktivieren macht das rückgängig.

Bindung löschen entfernt die Bindung aus der Ansicht. Der Dialog fragt, was mit dem Agenten passiert:

Agent behalten — er funktioniert weiter; nur seine Verknüpfung mit dem Managed Flow wird entfernt. Um den Flow später wieder zu verwalten, füge das Ziel hinzu und übernimm ihn.
Agent entfernen — wird nur angeboten, wenn die Pipeline den Agenten erstellt hat. Ein Agent, der schon vor der Übernahme seines Flows existierte, wird nie entfernt. Das ist unwiderruflich: Konfiguration, Nutzer- und Gruppenzuweisungen, Berechtigungen, Feedback und Dateien des Agenten werden gelöscht. Chat-Nachrichten bleiben in der Datenbank, sind über die Oberfläche aber nicht mehr erreichbar. Fügst du das Ziel später erneut hinzu, entsteht ein neuer, leerer Agent. Du bestätigst per Checkbox und durch Eingabe des Instanz-Slugs.

Änderungen an der Zielkopie während einer Deaktivierung oder zwischen Löschen und erneuter Übernahme zählen auf global weiterhin als Abweichung. Die Prüfung lässt sich so nicht umgehen.

Verbleibende Sperre¶

Deaktivieren und Löschen gelingen in Studio immer, auch wenn das Ziel nicht erreichbar ist. Konnte dem Ziel nicht mitgeteilt werden, den Flow freizugeben, ist der Flow dort möglicherweise noch gesperrt. Nach dem Löschen sagt der Dialog das direkt und bietet Erneut probieren an. Bei einer verbleibenden Bindung erscheint ein Warnsymbol neben dem Badge, und Admins können Entmarkierung wiederholen verwenden.

Managed Flows in Agentlab¶

Beide Rollen tragen in Agentlab ein Badge — in der Flow-Liste und in der Kopfzeile über der Canvas.

Badge	Bedeutung
Verwaltete Quelle	Wird von dieser Instanz auf ihre Ziele übertragen. Rein informativ — der Flow bleibt vollständig bearbeitbar und verhält sich ansonsten normal.
Verwaltet (Schloss-Symbol)	Wird über die Promotion-Pipeline gepflegt. Der Flow ist hier gesperrt; Änderungen erfolgen auf der Quellinstanz.

Ein Tooltip auf dem jeweiligen Badge liefert eine kurze Erläuterung.

Auf einer Zielinstanz ist ein verwalteter Flow gesperrt: Er lässt sich von Hand weder bearbeiten noch umbenennen, verschieben oder löschen, und es gibt keine Entsperrung. Agentlab erklärt die einzelne Ablehnung nicht — das Badge ist daher der entscheidende Hinweis:

Die Canvas reagiert nicht, und der Sperrschalter fehlt in den Flow-Einstellungen.
Umbenennen und Verschieben tun nichts, ohne Meldung.
Löschen zeigt Fehler beim Löschen von Elementen / Wiederholen Sie die Operation.

Änderungen laufen über die Quellinstanz. Ein Flow mit diesem Badge kann auch eine verbleibende Sperre statt einer aktiven Bindung sein — die Ansicht Alle Agenten in Studio zeigt, was zutrifft.