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](InstanceSetupGuide.md): 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](Werkzeugproben-Konzept.md)) 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](Security-Konzept.md) Abschnitt 9, #658 |

### Die Bedingung, ohne die es nicht trägt

**Basisagenten reden nicht** — weder mit den fachlichen Agenten noch miteinander. Sie
lesen (Audit, Receipts, Taskboard, Prompt-History) und schreiben Aufgaben.

Das ist nicht Sparsamkeit, sondern die Rechnung: Jede Nachricht zwischen zwei Agenten
kostet auf beiden Seiten einen Lauf. Eine Aufsicht, die einmal täglich liest und eine
Aufgabe hinterlässt, kostet einen Lauf — nicht *n*. Eine Aufsicht, die nachfragt, kostet
so viele Läufe, wie sie Agenten hat.

Die Bedingung gehört deshalb in die Rechte, nicht in den Prompt: Basisagenten bekommen
`AgentComm.send_message` nicht. Im Aufbau aus dem
[Organisation-Konzept](Organisation-Konzept.md) sind sie eine eigene Einheit neben der
Fachorganisation, mit Lesesicht über alle Einheiten und ohne Adressbuch.

---

## 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) |