ClawdDotNet/docs/Basisagenten-Konzept.md

Basisagenten — eine Standardgruppe je Instanz

Stand: 21. September 2026. Konzept, noch nicht gebaut.

Herkunft: Nutzervorschlag am 2026-09-21, aus dem Testbetrieb #572. Zwei Gedanken in einem: ein Agent, der das Taskboard beobachtet und den anderen Verbesserungen vorschlägt — und die Beobachtung, dass wir früher oder später ohnehin eine Gruppe Agenten brauchen, die in jeder Instanz dieselbe Grundarbeit übernimmt.

---

1 — Ausgangslage

Eine Instanz entsteht heute von Hand nach dem InstanceSetupGuide: Ordner anlegen, AgentSettings.json schreiben, Identity.md und Soul.md formulieren, Aufgaben erfinden. Was dabei entsteht, ist jedes Mal fachlich anders — und jedes Mal in denselben Teilen gleich.

Die Testinstanz „Alltag" führt das vor. Von ihren sieben Agenten sind fünf fachlich (Wetter, Nachrichten, Kurse, Datenbank, Webauswertung) und zwei sind es nicht: der hausmeister prüft alle drei Stunden, ob die regelmäßige Arbeit stattgefunden hat, und die redaktion fasst zusammen. Der Hausmeister enthält keine Zeile, die mit Wetter zu tun hat. Er ist ein Betriebsmittel, das in dieser Instanz zufällig von Hand entstanden ist — und in der nächsten Instanz wieder entstehen müsste.

Was heute fehlt, ist nicht die Fähigkeit, sondern die Vorlage. Agenten anlegen kann das Produkt (AgentEditor.create_agent, InstanceDirectoryManager.CreateAgent). Was es nicht kennt, ist ein Satz von Agenten, den es mitbringt.

---

2 — Die Gruppe

Vier Rollen, die in jeder Instanz dieselbe Arbeit tun. Alle sind abwählbar: eine Instanz mit einem einzigen fachlichen Agenten braucht keine Aufsicht über sich selbst.

Rolle	Was sie tut	Stand
Betriebskontrolle	Prüft, ob die regelmäßige Arbeit wirklich stattgefunden hat. Vorbild ist der hausmeister der Testinstanz.	Vorlage aus dem Testbetrieb, muss verallgemeinert werden
Aufsicht (Taskmanager)	Beobachtet Taskboard und Läufe, findet wiederkehrende Fehlschläge, schlägt Verbesserungen vor.	Abschnitt 3, neu
Personalmanager	Legt Agenten an, konfiguriert sie, führt Probelauf (#649) und Werkzeugproben (Werkzeugproben-Konzept) durch.	#649 beschreibt das Werkzeug, die Rolle fehlt
Security-Agent	Bewertet Befunde, schlägt Quarantäne vor.	Bereits festgelegt als Profil des AgentInspector, Security-Konzept Abschnitt 9, #658

Der Einwand, der zuerst beantwortet gehört

Der InstanceSetupGuide warnt ausdrücklich: mehr als fünf Agenten sind kritisch zu hinterfragen, weil der Koordinationsaufwand quadratisch steigt. Vier Basisagenten obendrauf scheinen dieser Regel ins Gesicht zu schlagen.

Sie tun es nicht, aber nur unter einer Bedingung: Basisagenten reden nicht mit den fachlichen Agenten und nicht miteinander. Sie lesen (Audit, Receipts, Taskboard, Prompt-History) und schreiben Aufgaben. Die Warnung im Guide gilt dem Nachrichtenverkehr — jede Nachricht kostet auf beiden Seiten einen Lauf. Eine Aufsicht, die einmal täglich liest und eine Aufgabe hinterlässt, kostet einen Lauf, nicht n.

Wird diese Bedingung aufgeweicht, kippt die Rechnung sofort. Sie gehört deshalb nicht in den Prompt, sondern in die Rechte: Basisagenten bekommen AgentComm.send_message nicht.

---

3 — Die Aufsicht im Einzelnen

Sie ist ein drittes Profil des AgentInspector (#204), kein eigenes System. Dieselbe Entscheidung wie beim Security-Agenten: gleiche Datenbasis, gleicher Bauplan, im Code begrenzte Rechte, anderer Blickwinkel.

Datenbasis

Alles davon ist von der Engine gestempelt und vom beaufsichtigten Agenten nicht fälschbar — das ist der Grund, warum die Aufsicht überhaupt etwas wert ist:

• Tasks — was fällig war, was lief, was liegenblieb
• RunReceipts — Schritte, Tokens, Kosten, Ausgang je Lauf
• AuditLog — welches Werkzeug mit welchen Argumenten, mit welchem Ausgang
• RunTranscripts (#660) — was das Modell wirklich gelesen und geantwortet hat
• StagedCalls — was zur Freigabe vorgelegt und wie entschieden wurde

Wonach sie sucht

Die Liste ist keine Erfindung: jeder Punkt ist ein Befund aus den letzten vier Tagen Testbetrieb, den ein Mensch zufällig gefunden hat.

Muster	Befund im Testbetrieb
Aufgabe endet regelmäßig an der Schrittgrenze	Tagesabschluss las 24 Dateien einzeln (#663)
Derselbe Werkzeugfehler wiederholt sich über Läufe	„Unknown column 'zeitpunkt'" (#676), „nicht gefunden im personal Workspace" (#662)
Ein Agent legt denselben Befund mehrfach an	Sechs Kursmeldungen (#674)
Aufgabe meldet Fehler, die keine sind	Betriebslücke bei vorhandenen Dateien (#673)
Läufe werden teurer oder länger, ohne dass die Aufgabe wuchs	—
Eine Aufgabe an @human wartet seit Tagen	26 solcher Aufgaben lagen offen

Was sie hervorbringt

Vorschläge, keine Änderungen. Eine Aufgabe je Befund, mit Beleg (RunId, Auszug aus dem Audit) und einem konkreten Vorschlag: „Aufgabe t-da70bd endet in vier von fünf Läufen an der Schrittgrenze; der Text verlangt 24 Einzelaufrufe. Vorschlag: read_many."

Adressat ist der Mensch — oder, wenn wir das später wollen, der Personalmanager mit Freigabepflicht. Die Aufsicht ändert nie selbst Aufgabentexte, Modelle, Budgets, Identity.md oder Soul.md. Das bliebe auch dann verboten, wenn es technisch ginge: ein Aufseher, der die Beaufsichtigten umschreibt, prüft am Ende seine eigene Arbeit. Die Linie ist dieselbe wie bei #205 und #641.

Was Code macht und was das Modell macht

Das Erkennen ist Code, nicht Modell. Ob eine Aufgabe dreimal an der Schrittgrenze endete, beantwortet eine SQL-Abfrage — verlässlich, in Millisekunden, kostenlos. Genau das ist #646 („Taskboard fasst nach"), und es gehört dorthin.

Das Modell wird erst für den Schritt danach gebraucht: aus „drei Abbrüche, alle bei FileRW read" und dem Aufgabentext den Grund zu erraten und einen Vorschlag zu formulieren. Das ist Deutung, und dafür lohnt ein Lauf.

Wer diese Grenze verwischt, bezahlt ein Sprachmodell dafür, Zeilen zu zählen — und bekommt die Antwort dann auch noch unzuverlässig.

Kosten und Takt

Einmal täglich, günstiges Modell, eigenes Tagesbudget mit hartem Deckel. Bei erreichtem Deckel bleibt die Deutung aus; die Erkennung aus #646 läuft unverändert weiter. Dieselbe Regel wie beim Security-Agenten.

---

4 — Wie eine Basisgruppe technisch entsteht

Drei Stufen, jede für sich nützlich:

1. Vorlagen im Produkt. Je Rolle ein Satz Dateien (Identity.md, Soul.md, AgentSettings.json mit Werkzeugrechten nach #641, Aufgaben-Markdown) im Installationsverzeichnis. Der InstanceSetupGuide verweist darauf, statt sie zu beschreiben. Kostet nichts als das Schreiben der Vorlagen.
2. Beim Anlegen der Instanz anbieten. Eine Auswahl im Einrichtungsablauf: welche Basisagenten sollen mit? Die Dateien werden kopiert, Modell und Budget aus den Instanzvorgaben gefüllt.
3. Nachziehbar halten. Eine neue Fassung bringt bessere Vorlagen mit. Ein Agent, den der Betreiber angepasst hat, darf dabei nicht überschrieben werden — also: Vorlagen versioniert, Abweichungen sichtbar, Übernahme freiwillig und einzeln. Dieselbe Schwierigkeit wie bei jeder Konfigurationsvorlage; sie gehört gelöst, bevor Stufe 2 ausgeliefert wird, sonst verliert der erste Betreiber seine Anpassungen.

---

5 — Offene Entscheidungen

• Darf die Aufsicht fremde Workspaces lesen? Der Bauplan zu #204 sieht es vor. Für die Taskbeobachtung reicht die Datenbank. Für „hat der Agent wirklich geschrieben, was er behauptet?" nicht. Vorschlag: ja, aber lesend und je Agent abschaltbar — ein Agent, der besondere Geheimnisse verwaltet, bleibt außen vor. Dieselbe Ausnahmelogik wie bei der Prompt-History (#660).
• Ein Profil oder vier Agenten? Security- und Aufsichtsprofil teilen die Datenbasis. Ob das zwei Agenten mit verschiedenen Rechten sind oder ein Agent mit zwei Aufträgen, ist eine Frage der Budgets und der Trennschärfe. Vorschlag: getrennt, weil ein gemeinsames Budget bedeutet, dass eine geschwätzige Aufsicht die Sicherheitsprüfung verhungern lässt.
• Gehört die Betriebskontrolle überhaupt in ein Modell? „Gibt es für jede der letzten drei Stunden eine Datei?" ist eine Abfrage, kein Denkvorgang. Denkbar wäre, die Betriebskontrolle ganz als Regelwerk zu bauen (erwartete Artefakte je Aufgabe, im Frontmatter deklariert) und nur die Deutung einem Agenten zu geben. Das wäre billiger und zuverlässiger — und würde die Rolle aus der Basisgruppe wieder herausnehmen.

---

6 — Items

Item	Vorhaben
#204	AgentInspector — der gemeinsame Unterbau
#646	Taskboard fasst nach — die mechanische Erkennung
#649	Probelauf für neue Agenten
#679	Basisagenten: Vorlagen und Auswahl beim Anlegen einer Instanz
#680	Aufsichtsprofil des AgentInspector (Taskmanager)