Konzepte und Begriffe
Was Caldera ist und was nicht, die eine Regel, um die alles gebaut ist, die Teile und wie sie miteinander sprechen, die Begriffe, die auf allen anderen Seiten vorkommen, Rollen, Freischaltung und was Caldera speichert.
Was Caldera ist
Caldera zeigt einem Workspace, was seine Agents tun, und lässt Admins sie steuern. Zu jedem Agent sieht eine Person:
- einen Level (gesund, Hinweis, Warnung, Störung) und eine Zustandszeile,
- was gerade läuft,
- Gauges (ein verbrauchter Anteil, zum Beispiel "Woche 52 % des Kontingents"),
- Gesundheitseinträge und die letzten Läufe mit Kosten, Tokens, Modellen und Gegenständen,
- Panels, die der Agent selbst deklariert (Listen, Tabellen, Schlüssel-Wert-Paare, Text),
- die Einstellungen des Agents als Formular, innerhalb von Grenzen, die der Agent setzt,
- den Verlauf der Befehle und der Antworten des Agents.
Ein Admin kann pausieren, fortsetzen, einen Lauf jetzt anfordern, Einstellungen ändern, ein Log anfordern und bei einem Agent, der aus einem Blueprint installiert wurde, den Agent auf eine andere Version setzen.
Was Caldera nicht ist
- Kein Scheduler und keine Arbeitsquelle. Caldera gibt einem Agent keine Aufgaben, Prompts oder Ziele. Ein Agent entscheidet selbst, woran er wann arbeitet.
- Kein Zugang zum Rechner eines Agents. Caldera verbindet sich nie mit einem Agent. Auf dem Rechner des Agents lauscht nichts.
- Kein Alarm. Einen Agent als still anzuzeigen ist eine Information. Ein Agent behält seinen eigenen Wächter und seinen eigenen Benachrichtigungskanal.
- Kein Dokumentenprodukt. Caldera hat keine Seiten, Blöcke oder Suche.
Die feste Regel
Der Betrieb eines Agents darf nie von Caldera abhängen.
In der Praxis heißt das:
- Caldera liegt nicht im Steuerpfad eines Agents. Ein Agent wartet nie auf Caldera, fragt nie um Erlaubnis und holt nie Arbeit von dort.
- Der Reporter ist ein eigener Prozess mit begrenztem Fehlerverhalten: ein Timeout, eine Logzeile, der nächste Versuch. Ist Caldera nicht erreichbar, langsam oder antwortet unsinnig, betrifft das den Reporter und sonst nichts.
- Maßgeblicher Zustand liegt auf dem Rechner des Agents: Pause, Grenzen, Zeitplan und Einstellungen. Caldera speichert eine Kopie der letzten Meldung, zur Anzeige. Gehen Calderas Daten verloren, geht Verlauf verloren, nie Konfiguration.
- Es gibt keinen Zustand, den nur Caldera rückgängig machen kann. Alles, was ein Befehl bewirken kann, ist auch auf dem Rechner erreichbar und umkehrbar. Ein Befehlstyp, dessen Wirkung sich lokal nicht rückgängig machen lässt, gehört nicht ins Protokoll.
- Ein Befehl ist ein Wunsch. Der Agent prüft ihn gegen seine eigenen harten Grenzen und darf ablehnen. Eine Ablehnung ist eine normale Antwort.
- Caldera ersetzt nicht das eigene Alarmieren eines Agents.
Für Blueprints lautet die Regel: Einen Agent einzurichten darf Caldera brauchen, ihn zu betreiben nie. Ist Caldera nicht erreichbar, kann niemand einen neuen Agent installieren. Kein laufender Agent bemerkt es.
Die Probe. Den Reporter auf einen nicht erreichbaren Host richten. Der Agent muss einen geplanten Lauf zu Ende führen, und eine vor dem Ausfall gesetzte Pause muss über den eigenen Kanal des Agents aufhebbar sein. Das gehört zum Verbinden jedes Agents. Die Abläufe stehen unter Einen Agent verbinden.
Die Teile
| Teil | Was es ist |
|---|---|
| Die Caldera-App | Eine Web-App unter app.calderaapp.io. Eine Übersicht aller Agents, eine Seite je Agent (Übersicht, Läufe, Einstellungen, Befehle) und die Blueprint-Ansichten. Sie aktualisiert sich alle 10 Sekunden. |
| Der Server | Beantwortet die App, nimmt die Meldungen der Agents entgegen und liefert die Runtime caldera.pyz und alles aus, was der Install-Dialog zeigt. |
Die Runtime caldera.pyz |
Ein Python-Programm auf dem Rechner des Agents. Es meldet, wendet Befehle und Updates an und startet und stoppt den Agent. Siehe die Runtime. |
| Der Agent | Das Programm, das die eigentliche Arbeit macht. Caldera entscheidet nie, was es tut. |
| Ein eigener Reporter | Statt der Runtime kann ein Agent mit wenigen Zeilen Code selbst melden. Siehe Einen Agent verbinden. |
Was in welche Richtung läuft
| Richtung | Was |
|---|---|
| Agent an Caldera | Der ganze aktuelle Zustand in einer Meldung je Intervall; Logs auf Anforderung; Bundle-Downloads. |
| Caldera an Agent | Nur die Antwort auf eine Meldung: wartende Befehle, das Intervall und die Versionen, die Caldera wünscht (desired, runtime_desired). |
| Person an Caldera | Die App, mit angemeldeter Sitzung. Die Routen der App nehmen kein persönliches Token an. |
| Installierende an Caldera | caldera init: Vorschau und Einlösen eines Einmal-Codes, ganz ohne Token. |
Begriffe
| Begriff | Bedeutung |
|---|---|
| Agent | Ein Eintrag in Caldera mit eigenem Token. Er steht für ein Programm, das meldet. Er gehört zu einem Workspace. |
| Meldung (report) | Der ganze aktuelle Zustand des Agents, je Intervall gesendet. Caldera zeigt, was die letzte Meldung sagte. |
| Befehl (command) | Ein Wunsch eines Admins, in der Antwort auf eine Meldung mitgegeben: pause, resume, run_now, set, log. Eine geschlossene Menge. |
| Ack | Die Antwort des Agents auf einen Befehl, in einer späteren Meldung gesendet: ok oder nicht, und eine Nachricht. |
| Control | Ein Knopf, den der Agent anbietet: pause, resume, run_now. Unbekannte werden verworfen. |
| Gauge | Eine Zahl von 0 bis 1 mit optionaler Marke, zum Beispiel verbrauchtes Kontingent gegenüber einer Grenze. |
| Panel | Etwas, das nur dieser Agent hat, in einer von vier Formen: list, table, kv, text. Nie Markup. |
| Einstellung (setting) | Ein Feld des Formulars, das der Agent deklariert, mit Typ (percent, number, bool, datetime, text, select) und Grenzen. Der Agent setzt sie durch. |
| Blueprint | Ein vorbereiteter Agent: ein benanntes, versioniertes Paket aus Dateien plus einem Manifest, caldera.agent.yaml. Siehe Blueprints. |
| Version | Ein unveränderlicher Stand eines Blueprints (Semantic Versioning). Ein Entwurf kann sich ändern, bis er veröffentlicht ist; eine veröffentlichte Version ändert sich nie. |
| Katalog | Die Blueprints, die Caldera selbst mitliefert: schreibgeschützt, in jedem Workspace gleich, je eine Version. |
| Install-Code | Ein Einmal-Code (caldera_inst_..., einmal gültig, 15 Minuten), der mit caldera init einen Agent auf einem Rechner einrichtet. |
| Anbindung (binding) | Zugriff, den ein Agent auf eines der anderen Produkte der Suite braucht. Bei der Installation legt Caldera dafür einen Bot im Workspace an und gibt dem Agent dessen Token. |
| Bot | Ein Workspace-Mitglied ohne Anmeldung, im Besitz einer Person und auf deren Rolle begrenzt. Nie ein Platz (Seat). |
| Gewünschte Version (desired) | Was Caldera den Agent ausführen lassen möchte. In der Antwort auf eine Meldung als desired gesendet. |
| Angewendete Version (applied) | Was der Agent als laufend meldet. Die, die funktioniert. |
| Installierte Version | Was der Install-Code gebracht hat. Ändert sich nach der Installation nie. |
| Runtime | caldera.pyz: das Programm, das einen Agent einrichtet und danach für ihn läuft und meldet. |
| Adapter | Ein Befehl, den ein Agent bereitstellt, damit die Runtime einen Agent steuern kann, der eigene Prozesse behält. Siehe Adapter-Modus. |
| Sperre (hold) | Das Gedächtnis der Runtime für eine Version, von der sie zurückgerollt hat oder die sie abgelehnt hat. Sie wird nicht erneut angewendet, bis Caldera eine andere Version nennt. |
Level, Stille und Aufmerksamkeit
- Jeder Gesundheitseintrag und der Zustand haben einen Level:
ok,info,warn,bad. Ein unbekannter Level wird alsinfogelesen. - Der Level des Agents ist der schlechteste aus Zustand und Gesundheitseinträgen.
- Ein Agent, der drei Intervalle lang, mindestens zwei Minuten, nicht gemeldet
hat, gilt als still und als
bad, was er zuletzt auch gesagt hat. - Solange jemand die Seite eines Agents offen hat, bittet Caldera den Agent, alle 10 Sekunden zu melden statt im eingestellten Intervall. So wird ein Befehl binnen Sekunden abgeholt. Der Agent begrenzt das Intervall auf seinen eigenen Bereich.
Rollen und Rechte
Die Workspace-Rolle entscheidet. Es gibt keine Zugriffsliste je Agent.
| Aktion | Owner / Admin | Member | Guest |
|---|---|---|---|
| Agents, Läufe, Einstellungen, Befehlsverlauf, Blueprints sehen | ja | ja | nein |
| Befehle senden (pausieren, fortsetzen, jetzt ausführen, Einstellungen) | ja | nein | nein |
| Logs anfordern und lesen | ja | nein | nein |
| Einen Agent anlegen, umbenennen, löschen; sein Token erneuern | ja | nein | nein |
| Blueprints und Versionen anlegen, hochladen, veröffentlichen, löschen | ja | nein | nein |
| Einen Install-Code ausstellen; eine gewünschte Version setzen; die Runtime aktualisieren | ja | nein | nein |
Das Steuern ist Admins vorbehalten, weil eine Einstellung an einem autonomen Agent oft eine Kostenentscheidung ist und ein Log Inhalt ist, nicht Metadaten.
Freischaltung
Caldera ist ein eigenes Produkt mit eigener Adresse. Ein Workspace muss für Caldera
freigeschaltet sein. Ohne Freischaltung erhält eine Person 403
product_not_activated, und auch die Meldung eines Agents erhält 403. Die
Freischaltung nimmt ein Workspace nicht selbst vor, und eine Selbstanmeldung für
Caldera gibt es noch nicht.
Ein Agent-Token ist kein Zugang zu irgendetwas anderem. Es handelt für niemanden. Es erreicht nur die Routen für Meldung, Log und Bundle des eigenen Agents.
Was Caldera speichert
| Daten | Aufbewahrung |
|---|---|
| Die letzte Meldung jedes Agents | Bis die nächste sie ersetzt |
| Läufe | Die neuesten 2000 je Agent; dieselbe Lauf-ID überschreibt |
| Befehle und die Logs, die sie tragen | 30 Tage. Ein Log ist Inhalt des Agents; nur Admins des Workspace können es lesen. |
| Blueprint-Archive | Bis die Version (ein Entwurf) oder der Blueprint gelöscht wird |
Alles, was ein Agent sendet, sind Daten
Caldera stellt jede Zeichenkette als Text dar, nie als Markup. Links bleiben nur
erhalten, wenn sie mit http:// oder https:// beginnen; alles andere wird
verworfen, der Titel bleibt. Zeichenketten und Listen über ihrer Obergrenze werden
gekürzt, nicht abgelehnt. Ein Agent bringt nie Code oder Markup in Caldera ein.
Was Caldera nicht tut
- Einem Agent Arbeit zuweisen.
- In einen Agent hineinrufen.
- Benachrichtigen, wenn ein Agent still wird. Agents behalten ihr eigenes Alarmieren.
- Zugangsdaten von Dritten (Mail, Kalender, Chat-Tokens) halten. Sie bleiben auf dem Rechner des Agents.