Agents betreiben

Die Abläufe für einen Agent, der mit Caldera verbunden ist: installieren, aktualisieren, festhalten, zurückrollen, pausieren und fortsetzen mit und ohne Caldera, die Runtime aktualisieren, ein Token erneuern, löschen, einen bestehenden Agent auf die Runtime umstellen und eine Fehlertabelle vom Symptom zur Lösung.

Konventionen: <dir> ist das Verzeichnis des Agents auf seinem Rechner (zum Beispiel ~/caldera-agents/my-agent), <name> sein Name. Befehle auf dem Rechner lauten python3 caldera.pyz ...; der Download liegt dort, wo er geholt wurde, und die Runtime hält eine Kopie unter <dir>/.caldera/caldera.pyz.

Kurzübersicht

Einen Agent aus einem Blueprint installieren

Voraussetzungen: eine Admin-Rolle in einem freigeschalteten Workspace; eine veröffentlichte Version; ein Rechner mit Python 3 und (für den Service) systemd; ausgehendes HTTPS zu app.calderaapp.io.

1. In Caldera: Blueprints, der Blueprint (oder ein Katalog-Blueprint), "Installieren...". Die Version wählen, den Agent-Namen vergeben (Kleinbuchstaben, Ziffern, Bindestriche; nicht der Name eines bestehenden Agents), "Install-Code erstellen" drücken. Ist das Produkt einer Anbindung nicht freigeschaltet oder würde der Workspace zehn Bots überschreiten, sagt der Dialog es jetzt.
2. Beide Befehle jetzt kopieren. Der Code wird einmal angezeigt und läuft nach 15 Minuten ab.
3. Auf dem Rechner den ersten Befehl ausführen (laden und prüfen). Auf macOS die Variante mit shasum -a 256 -c - verwenden. Schlägt die Prüfung fehl, anhalten; siehe die Fehlertabelle.
4. Den zweiten Befehl ausführen: python3 caldera.pyz init <code> --url https://app.calderaapp.io. Mit --dir <dir> lässt sich das Verzeichnis wählen (Standard ~/caldera-agents/<name>). Er fragt nach den deklarierten Geheimnissen (verdeckte Eingabe); für unbeaufsichtigte Installationen stattdessen CALDERA_SECRET_<NAME> setzen.
5. Er installiert und startet caldera-<name>.service. Damit er weiterläuft, wenn niemand angemeldet ist: loginctl enable-linger <user>.
6. Prüfen: python3 caldera.pyz status --dir <dir> zeigt process running und last report ok, und der Agent erscheint binnen etwa einer Minute in der Übersicht.
7. Die Unabhängigkeitsprobe machen.

Scheitert init nach dem Verbrauchen des Codes, existiert der Agent in Caldera ohne Rechner. Ihn in Caldera löschen und einen neuen Code ausstellen.

Einen Agent mit eigenem Reporter anmelden

1. Übersicht, "Neuer Agent": ein Name und, falls ein anderes gewünscht ist, das Meldeintervall.
2. Das Token und die zwei Umgebungszeilen jetzt kopieren; sie werden einmal angezeigt.
3. Sie in die private Geheimnisdatei des Reporters legen; den Reporter starten; die Übersicht prüfen. Siehe Einen Agent verbinden.

Auf eine neue Version aktualisieren

1. Die version im Manifest auf eine Nummer erhöhen, die nie veröffentlicht wurde (veröffentlichte Versionen sind unveränderlich, und ein Entwurf darf nur ersetzt werden, bis er veröffentlicht ist), das Bundle neu bauen, als Version des Blueprints hochladen und veröffentlichen.
2. Auf der Seite des Agents, Panel Blueprint: die Version wählen, "Auf diese Version wechseln". Caldera speichert den Wunsch und sendet ihn in der Antwort auf die nächste Meldung des Agents.
3. Der Zeile unter dem Panel folgen. Sie geht: Warten auf die nächste Meldung des Agents, dann angewendet, vom Agent zurückgerollt oder fehlgeschlagen, mit der eigenen Nachricht des Agents.
4. Nach einem angewendeten Update beobachtet sich der Agent 30 Minuten lang. Wird sein Level in dieser Zeit schlechter, rollt er von selbst zurück, und das Panel zeigt dann das Ergebnis des Zurückrollens.

Was die Runtime tut, steht unter die Runtime. Kurz: holen, neben der laufenden Version bereitstellen, tauschen, neu starten, health ausführen, behalten oder zurückgehen. Alles in state-Pfaden bleibt unberührt.

Eine Version, von der der Agent zurückgerollt hat oder die er abgelehnt hat, wird nicht erneut angewendet, bis eine andere Version genannt wird. Um eine korrigierte Version zu versuchen, eine neue Versionsnummer veröffentlichen.

Festhalten

Festhalten bittet den Agent, auf der Version zu bleiben, die er ausführt: Auf der Seite des Agents "Festhalten" drücken. Technisch setzt es die gewünschte Version auf die laufende, was der Agent als nichts zu tun sieht. Es verhindert auch, dass ein veralteter Wunsch nach einer neueren Version angewendet wird. "Festhalten" ist abgeschaltet, solange der Wunsch schon der laufenden Version entspricht.

Zurückrollen

• Aus Caldera: "Zurückrollen" nennt die vorherige veröffentlichte Version. Das ist richtig, wenn der Agent gesund ist, aber das alte Verhalten gewünscht ist.
• Auf dem Rechner, ohne Caldera: python3 caldera.pyz rollback --dir <dir>. Es wechselt auf die vorherige Version und startet neu, ohne Netz. Es werden nur zwei Versionen aufbewahrt, ein zweites rollback geht also wieder vor.
• Nach einem lokalen Rollback ist die Version, die es verlassen hat, gesperrt: Die nächste Meldung macht es nicht rückgängig, auch wenn Caldera diese Version weiter wünscht. status zeigt held <version> is not applied until Caldera names another version. Dann festhalten (die Version nennen, die läuft) oder eine andere Version nennen, damit die Seite von Caldera übereinstimmt.
• Ein Katalog-Agent kann nur die eine mitgelieferte Version holen, für ihn ist das lokale Rollback also der Weg zurück.

Die Sperre löst sich, wenn eine andere Version erfolgreich angewendet wird.

Eine Einstellung ändern, jetzt ausführen, ein Log anfordern

• Einstellungen (Admins): Tab Einstellungen, ändern, "Anwenden". Der Agent prüft jede Änderung gegen seine eigenen Grenzen und antwortet in eigenen Worten; "A change is waiting for the next report of the agent" bleibt stehen, bis er es tut. Eine Ablehnung lautet "Nothing changed: : ." und ändert nichts (ganz oder gar nicht). Caldera wiederholt die Grenzprüfung nur, um es einer Person sofort zu sagen.
• Jetzt ausführen: Der Agent muss run_now in controls anbieten; wird abgelehnt, solange pausiert ist.
• Log: nur Admins. Caldera fragt den Agent nach einem der Log-Namen, die er gemeldet hat; der Agent sendet die letzten 512 KB. Der Text wird mit dem Befehl 30 Tage aufbewahrt.

Ein Befehl wird höchstens einmal zugestellt. Geht die Antwort auf eine Meldung verloren, geht der Befehl verloren und schlägt nach zehn Minuten fehl (wenn der Agent das nächste Mal meldet). Dann erneut senden.

Pausieren und Fortsetzen, mit und ohne Caldera

Alles, was Caldera tut, geht auch ohne Caldera. Den Weg ohne Caldera für jeden Agent kennen, bevor er gebraucht wird.

• Eine in Caldera gesetzte Pause ist dieselbe Pause: dieselbe Datei und derselbe Stopp.
• Bei einem Runtime-Agent stoppt die Pause den Prozess des Agents; die Runtime meldet weiter, und der Zustand zeigt "Paused" (warn).
• Caldera schaltet die Controls für einen stillen Agent ab ("The agent is not reachable, so it cannot take a command now").
• Eine Runtime auf einem entfernten Rechner wird pausiert, indem man sich dort anmeldet und den Befehl ausführt. Den genauen Befehl neben der Dokumentation des Agents festhalten.

Die Runtime selbst aktualisieren

Die Runtime aktualisiert sich auf Knopfdruck, signiert (wie es funktioniert, steht unter die Runtime):

1. Auf der Seite des Agents zeigt das Panel Runtime die Version, die der Agent ausführt, die, die dieses Caldera ausliefert, ein Festhalten und die davor aufbewahrte Datei. "Runtime aktualisieren" (nur Admins; Members lesen) setzt einen Wunsch. Die nächste Antwort auf eine Meldung trägt ihn. Das Panel folgt ihm: Warten auf die Meldung des Agents, "muss sich erst bewähren", während die neue Runtime ihre fünf Minuten läuft, dann die eigenen Worte der Runtime für übernommen, zurückgegangen oder nicht übernommen. Eine Version, die zurückgegangen oder fehlgeschlagen ist, wird nicht erneut angeboten, bis Caldera eine andere ausliefert, und der Knopf fehlt bis dahin. Eine Runtime, die keine Version meldet (älter als diese Funktion, oder gar kein caldera.pyz), bekommt statt des Knopfs einen Hinweis: Sie wird einmal von Hand ersetzt, siehe unten.
2. Die Runtime lädt /cli/caldera.pyz und seine Signatur, prüft die Prüfsumme und die Signatur gegen den öffentlichen Schlüssel, der in ihr eingebaut ist, und lässt die neue Datei ihre Version nennen. Eine falsche oder fehlende Signatur oder ein Rechner ohne ssh-keygen: Nichts ändert sich, und die Seite des Agents zeigt das Ergebnis failed mit dem Grund.
3. Sie bewahrt die alte Datei als <dir>/.caldera/caldera.pyz.previous auf, tauscht die Datei, die die Unit nennt, und startet an Ort und Stelle neu: derselbe Prozess, die eigenen Prozesse des Agents halten nie an.
4. Die erste erfolgreiche Meldung binnen fünf Minuten macht sie gut. Eine neue Runtime, die abstürzt oder nicht rechtzeitig meldet, geht von selbst zurück; diese Version wird dann gesperrt, bis eine neuere angeboten wird.

Auf dem Rechner, ganz ohne Verbindung:

python3 <dir>/.caldera/caldera.pyz rollback-runtime --dir <dir>   # zurück auf die vorherige Datei
python3 <dir>/.caldera/caldera.pyz pin-runtime 0.32.0 --dir <dir>  # nie auf eine andere Version aktualisieren
python3 <dir>/.caldera/caldera.pyz pin-runtime off --dir <dir>     # das Festhalten lösen

Eine einmalige Hürde: Eine Runtime, die installiert wurde, bevor es das gab, kann sich nicht selbst aktualisieren. <dir>/.caldera/caldera.pyz einmal von Hand ersetzen (Modus 700, Prüfsumme verifiziert) und systemctl --user restart caldera-<name>.service ausführen; die Unit hat KillMode=process, der Agent läuft also weiter. Danach sind Updates ein Knopfdruck. Eine Runtime, die von woanders als <dir>/.caldera/caldera.pyz (dem Pfad der Unit) gestartet wurde, kann sich nicht ersetzen und sagt das.

Unter welchem Claude-Konto ein Agent läuft

Das Panel Runtime auf der Seite des Agents sagt, bei welchem Claude-Konto der Rechner angemeldet ist. Siehe Der Hinweis auf das Claude-Konto.

Das Token eines Agents erneuern

Das tun, wenn ein Token geleakt sein könnte oder verloren ging.

1. Caldera: Menü des Agents, "Rotate token...". Das alte Token funktioniert sofort nicht mehr. Das neue wird einmal angezeigt, mit den zwei Umgebungszeilen.
2. Der Agent ist in Caldera nun still, bis der Rechner das neue Token hat.
3. Runtime-Agent: <dir>/.caldera/agent.env bearbeiten, den Wert von CALDERA_TOKEN ersetzen (den Dateimodus 600 behalten), dann systemctl --user restart caldera-<name>.service. Der Agent läuft weiter: Er hielt das Token nie, und eine neu gestartete Runtime übernimmt ihn.
4. Eigener Reporter: seine Geheimnisdatei aktualisieren und den Reporter-Service neu starten.
5. Prüfen, dass der Agent wieder meldet.

Die Runtime hat keinen Befehl, der das neue Token holt; Caldera schreibt nie auf den Rechner.

Token der Anbindungen (Zugriff auf andere Produkte) werden hier nicht erneuert. Sie sind die Token der Bots und werden in den eigenen Bot-Einstellungen des Produkts behandelt; siehe die Tabelle unten ("Anbindung ist defekt").

Einen Agent löschen

Caldera: Menü des Agents, "Delete...". Die Bestätigung nennt, was bleibt.

• Caldera löscht den Agent, seine Läufe und seine Befehle. Sein Token funktioniert sofort nicht mehr.
• Auf dem Rechner ändert sich nichts. Die Runtime führt den Agent weiter aus und loggt in jedem Intervall eine abgelehnte Meldung (HTTP 401).
• Die Bots werden nicht widerrufen. Nur das Produkt, dem ein Bot gehört, kann ihn widerrufen. Die Bestätigung listet sie mit Namen auf ("These bots stay: ..."). Sie in den Bot-Einstellungen dieses Produkts widerrufen, sonst bleiben die Token gültig, bis sie ablaufen.
• Um den Agent vom Rechner zu entfernen, in dieser Reihenfolge:
  1. python3 caldera.pyz pause --dir <dir> (das stoppt den Prozess des Agents; die Unit zuerst abzuschalten ließe ihn weiterlaufen),
  2. systemctl --user disable --now caldera-<name>.service,
  3. ~/.config/systemd/user/caldera-<name>.service entfernen und systemctl --user daemon-reload,
  4. <dir> entfernen (es enthält den Zustand des Agents; behalten, wenn er gebraucht wird).

Ein Blueprint lässt sich nur löschen, wenn kein Agent aus ihm installiert ist.

Einen bestehenden Agent auf die Runtime umstellen

Es funktioniert, wenn der Agent als ein Prozess laufen kann, den die Runtime starten und stoppen darf. (Ein Agent mit eigenen Timern und einer Pause, die andere setzen, nutzt den Adapter-Modus oder bleibt bei seinem eigenen Reporter.)

Vorher: Der Agent hat einen eigenen Reporter und eigene Timer. Nichts ändert sich, bis die Schritte beginnen.

1. Das Bundle bauen und als erste Version eines Blueprints hochladen (siehe Blueprints); veröffentlichen.
2. Den alten Agent in Caldera umbenennen (zum Beispiel <name>-old): Die Installation braucht den freien Namen.
3. Einen Install-Code für den Blueprint ausstellen, mit dem Namen des Agents.
4. Auf dem Rechner zuerst den alten Modus stoppen, damit nichts doppelt läuft: die alten Timer und den alten Reporter-Service abschalten.
5. Die zwei Install-Befehle ausführen; init schreibt das Verzeichnis und die Unit.
6. Prüfen: status, das Journal der Unit (journalctl --user -u caldera-<name>.service -n 20), der Agent in Caldera, einmal "Jetzt ausführen" und die Unabhängigkeitsprobe.
7. Läuft er, den alten Agent in Caldera löschen. Die alten Unit-Dateien an ihrem Platz lassen: Der Weg zurück braucht sie.

Der Weg zurück: Die neue Unit abschalten und den alten Modus wieder starten.

systemctl --user disable --now caldera-<name>.service
systemctl --user enable --now <die alten Timer und der alte Reporter-Service>

In Caldera den alten Agent zurückbenennen und den neuen löschen. Der alte und der neue Modus dürfen nie gleichzeitig laufen.

Das Kontingent-Gauge sieht falsch aus

Symptom. Das Kontingent-Gauge eines Agents in Caldera stimmt nicht mit der Nutzungsseite des Anbieters überein. Zum Beispiel zeigt Caldera 79 % für die Woche, während der Anbieter 90 % zeigt.

Ursache. Das ist eine Eigenschaft davon, wie der Agent misst, nicht von Caldera. Ein Gauge, das ein Agent aus dem Kontingentbericht seines eigenen letzten Modellaufrufs baut, ist nur so frisch wie dieser Aufruf. Zwei Dinge machen es veraltet:

1. Andere Sitzungen verbrauchen dasselbe Kontingent. Das Abonnement wird mit interaktiven Sitzungen auf demselben Konto geteilt, der echte Wert kann also höher sein als der letzte, den der Agent sah.
2. Der Agent hält Läufe über seiner Schwelle an. Über seinen eigenen Grenzen startet der Agent keinen Lauf, und ohne Lauf gibt es keine neue Beobachtung. Das Gauge bleibt dann, wo es war.

Ein Fenster, dessen Rücksetzzeit vorbei ist, zählt als leer (0), ein veraltetes Gauge kann also auch bei einer Rücksetzung auf 0 fallen, nach der der Agent noch keinen Aufruf gesehen hat.

Was hilft. Ein Agent, der ein Gauge aus seiner eigenen letzten Beobachtung baut, sollte

• sagen, wann er beobachtet hat: Die ersten Worte des detail des Gauges sind die Zeit der letzten Messung (zum Beispiel "Stand 06.10. 14:05"), damit ein veralteter Wert als veraltet erkennbar ist;
• die Beobachtung von selbst auffrischen, höchstens einmal pro Stunde, auch wenn er pausiert oder gesperrt ist, mit einer Anfrage, die nach nichts als dem Kontingent fragt (kein Kontext, keine Werkzeuge, das kleinste Modell); und in seinem Log sagen, wenn das fehlschlägt und dass der letzte Wert bleibt.

Es gibt in Caldera kein zentrales Kontingent-Gate, und eines ist nicht geplant: Jeder Agent hält seine eigenen Grenzen.

Prüfen. Die Zeit in der Detailzeile des Gauges lesen. Ist sie älter als etwa eine Stunde, schlägt die Messung fehl: Im eigenen Log des Agents nachsehen und prüfen, dass das Programm, das die Messung macht, gefunden wird. Den Wert mit der Nutzungsseite des Anbieters vergleichen.

Beheben. Caldera zeigt, was der Agent gemeldet hat; in Caldera ist nichts zu ändern. Ein Gauge ohne Messzeit nicht als aktuell behandeln.

Fehlerbehebung

Mit der Seite des Agents anfangen (Level, letzte Meldung, die Gesundheitseinträge "Process" und "Binding") und auf dem Rechner mit python3 caldera.pyz status --dir <dir>.

Ablehnungsgründe

Calderas Ablehnungen tragen einen reason (und params für den Satz); die App schreibt den Satz in der Sprache der lesenden Person. Die eigene message des Servers ist englische Prosa für Logs.