diff --git a/docs/Basisagenten-Konzept.md b/docs/Basisagenten-Konzept.md index f32c8e7..ac5f14c 100644 --- a/docs/Basisagenten-Konzept.md +++ b/docs/Basisagenten-Konzept.md @@ -41,20 +41,20 @@ Instanz mit einem einzigen fachlichen Agenten braucht keine Aufsicht über sich | **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 | -### Der Einwand, der zuerst beantwortet gehört +### Die Bedingung, ohne die es nicht trägt -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. +**Basisagenten reden nicht** — weder mit den fachlichen Agenten noch miteinander. Sie +lesen (Audit, Receipts, Taskboard, Prompt-History) und schreiben Aufgaben. -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*. +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. -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. +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. --- diff --git a/docs/InstanceSetupGuide.md b/docs/InstanceSetupGuide.md index 440d000..1ebd265 100644 --- a/docs/InstanceSetupGuide.md +++ b/docs/InstanceSetupGuide.md @@ -11,21 +11,43 @@ Bevor eine Instanz erstellt wird, muss klar definiert werden: | Frage | Beispiel | |-------|---------| | Welche Aufgabe(n) soll die Instanz als Ganzes erledigen? | "Social-Media-Monitoring mit automatischer Zusammenfassung" | -| Wie viele Agenten werden benötigt? | 1–5 (mehr = höhere Koordinationskosten) | +| Wie viele Agenten werden benötigt? | So viele, wie es Zuständigkeiten gibt — die Kosten stecken in den Verbindungen, nicht in der Zahl | | Welche externen Systeme sind beteiligt? | Telegram, E-Mail, Datenbank, APIs | | Wie hoch ist das Token-Budget pro Tag? | z.B. $1/Tag, $10/Tag | | Soll die Instanz autonom arbeiten oder manuell getriggert werden? | Cron-Jobs vs. manueller Start | ### Agentenanzahl richtig wählen +> **Geändert am 2026-09-21.** Hier stand: „Mehr als 5 Agenten — kritisch hinterfragen, +> Koordinationsoverhead steigt quadratisch." Die Beobachtung stimmt, die Folgerung war +> falsch. Quadratisch steigen die **Verbindungen**, nicht die Agenten. Eine Instanz, die +> einen Onlinehandel betreibt, braucht Einkauf, Buchhaltung, Marketing und Logistik mit je +> mehreren Agenten — fünf reichen dafür nicht annähernd. Das Ziel von ClawdDotNet sind +> 50 bis 100 Agenten, die geordnet zusammenarbeiten. Die Begründung und was dafür fehlt: +> [Organisation-Konzept](Organisation-Konzept.md). + | Szenario | Empfehlung | |----------|-----------| | Eine klar abgegrenzte Aufgabe | 1 Agent | | Aufgabe mit getrennten Zuständigkeiten (z.B. Recherche + Bericht) | 2–3 Agenten | -| Komplexes System mit Koordination | 3–5 Agenten, davon 1 Koordinator | -| Mehr als 5 Agenten | Kritisch hinterfragen — Koordinationsoverhead steigt quadratisch | +| Ein Fachgebiet mit mehreren Teilaufgaben | So viele Agenten wie Teilaufgaben, plus eine Leitung | +| Mehrere Fachgebiete | Je Gebiet eine Einheit mit eigener Leitung; die Leitungen reden miteinander, die Mitglieder nicht | -**Faustregel:** Jeder Agent, der mit einem anderen kommuniziert, kostet Token auf beiden Seiten. Zwei Agenten, die jeweils 3 Nachrichten austauschen = 6 LLM-Runs. +**Die Faustregel gilt weiter, aber sie zielt auf etwas anderes:** Jede Nachricht zwischen +zwei Agenten kostet auf beiden Seiten einen Lauf. Zwei Agenten, die drei Nachrichten +tauschen, sind sechs Läufe. Teuer wird also nicht der elfte Agent, sondern der elfte +Agent, der **jeden** anderen ansprechen darf. + +Deshalb ist die eigentliche Entwurfsfrage nicht „wie viele Agenten?", sondern **„wer muss +mit wem reden?"** Ein Agent, der drei Nachbarn und eine Leitung kennt, kostet gleich viel, +ob die Instanz zehn oder hundert Agenten hat. Ein Agent, der eine Liste aller hundert +bekommt, kostet bei jedem Blick in diese Liste. + +Bis die Strukturen aus dem [Organisation-Konzept](Organisation-Konzept.md) gebaut sind, +ist das Adressbuch flach: `list_agents` zeigt jedem Agenten alle anderen. Bei mehr als +etwa zehn Agenten heißt das, `AgentComm` nur den Agenten zu geben, die es wirklich +brauchen — und den übrigen die Zusammenarbeit über das Taskboard zu geben, das keine +Gegenseite wachhält. --- diff --git a/docs/Organisation-Konzept.md b/docs/Organisation-Konzept.md new file mode 100644 index 0000000..457b29f --- /dev/null +++ b/docs/Organisation-Konzept.md @@ -0,0 +1,230 @@ +# Organisation — 50 bis 100 Agenten geordnet zusammenarbeiten lassen + +*Stand: 21. September 2026. Konzept, noch nicht gebaut.* + +> Herkunft: Richtungsentscheidung des Nutzers am 2026-09-21. Die bisherige Regel im +> [InstanceSetupGuide](InstanceSetupGuide.md) („mehr als 5 Agenten kritisch +> hinterfragen") ist damit zurückgezogen. +> +> **Das Ziel:** ClawdDotNet ist der Harness — das Büro, der Konferenzraum, die Groupware +> der Agenten. Eine Instanz betreibt einen Onlinehandel mit Einkauf, Buchhaltung, +> Marketing und Logistik; jede Abteilung hat mehrere Agenten, dazu Leitungen und +> beliebig viele weitere Ebenen. 50 bis 100 Agenten arbeiten parallel an einem großen +> Vorhaben, nie alle gleichzeitig, aber alle an derselben Sache. + +--- + +## 1 — Was an der alten Regel richtig war und was falsch + +Richtig: Der Aufwand steigt quadratisch. Falsch: dass er an der Zahl der Agenten hängt. + +Er hängt an der Zahl der **Verbindungen**. Zehn Agenten, von denen jeder jeden ansprechen +darf, sind 45 mögliche Kanäle. Hundert Agenten in Teams von sieben, die nur ihre +Nachbarn und ihre Leitung kennen, sind rund 700 — bei zehnmal so vielen Agenten nur +fünfzehnmal so viele Kanäle statt hundertmal. + +**Die Entwurfsfrage lautet also nicht „wie viele Agenten?", sondern „wer muss mit wem +reden?"** Ein Agent, der drei Nachbarn und eine Leitung kennt, kostet gleich viel, ob die +Instanz zehn oder hundert Agenten hat. + +Der Logistiker spricht nie mit dem Amazon-Anzeigen-Agenten. Muss es doch einmal sein, +trägt seine Abteilungsleitung es in die Leitungsrunde, und von dort geht es an die +Leitung der Gegenseite. Das ist keine Bürokratie, sondern der Grund, warum echte +Organisationen mit tausend Menschen funktionieren und eine Gruppenchat-Gruppe mit +fünfzig nicht. + +--- + +## 2 — Was heute bei 50 Agenten bricht + +Nicht Meinung, sondern Code-Stand 0.1.15. Das ist die eigentliche Antwort auf die Frage, +was fehlt: **zwischen „Instanz" und „Agent" gibt es keine Ebene.** Alles, was heute nicht +am einzelnen Agenten hängt, ist instanzweit — und damit ein gemeinsamer Engpass. + +| Stelle | Heute | Bei 50 Agenten | +|---|---|---| +| `AgentComm.list_agents` | liefert **alle** anderen Agenten, flach, mit Name, Rolle, Modell, Zustand | 49 Einträge im Prompt jedes Fragenden. Der Logistiker erfährt, dass es einen Amazon-Anzeigen-Agenten gibt — genau das, was er nicht wissen soll | +| `AgentComm.send_message` | **wartet auf die Antwort** des Zielagenten | Eine Leitung, die vier Teams fragt, blockiert durch vier Läufe hindurch. Eine Besprechung ist kein Funktionsaufruf | +| `MaxDelegationDepth = 3` | drei Weitergaben | Vorstand → Abteilung → Team → Agent ist bereits erschöpft | +| Scanner: `Task.WhenAll(claimed…)` | **unbegrenzt parallel** | 50 fällige Aufgaben um Punkt 9 Uhr sind 50 gleichzeitige Modellaufrufe. Ratengrenzen, Kostenspitze — und die Budgetprüfung je Lauf lässt sie alle gleichzeitig passieren | +| Scanner: `TaskQuery { Limit = 500 }` | stille Obergrenze | 100 Agenten mit je fünf Terminaufgaben liegen darüber. Aufgaben fallen lautlos aus dem Takt | +| Arbeitsbereiche | genau zwei: `personal` und `shared` | Buchhaltung und Einkauf teilen sich einen Dorfplatz. Eine Abteilungsablage gibt es nicht | +| `sharedAccessLevel` | eine Stufe für den ganzen gemeinsamen Bereich | „Buchhaltung darf ihre Ablage schreiben, die von Marketing nur lesen" ist nicht ausdrückbar | +| Taskboard | ein Brett für alles; `task_list` kappt bei 8.000 Zeichen | Auf der Testinstanz mit 7 Agenten stehen 159 Aufgaben. Mit 50 Agenten ist die Liste als Übersicht wertlos | +| Budget | zwei Ebenen: Agent und Instanz | „Marketing darf 20 $/Tag" ist nicht ausdrückbar | +| Freigaben | eine Warteschlange, ein Mensch | Der Mensch wird zum Flaschenhals der gesamten Organisation | + +Zwei dieser Punkte sind schon heute Fehler, unabhängig von der Größe: die unbegrenzte +Parallelität und die stille Kappung bei 500. Sie gehören sofort behoben (#682). + +--- + +## 3 — Die fehlende Ebene: Einheiten + +Eine **Einheit** (Abteilung, Team, Gruppe) ist ein Knoten in einem Baum. Sie hat einen +Namen, eine Leitung, Mitglieder und Untereinheiten. Alles, was heute instanzweit ist, +bekommt sie als Ebene dazwischen: + +``` +Instanz „Onlinehandel" +├── Einkauf ──────────── Leitung: einkauf-leitung +│ ├── Produktsuche ──── produktscout-1, produktscout-2, trendbeobachter +│ ├── Lieferanten ───── lieferantensuche, konditionen, nachverhandlung +│ └── Qualität ──────── musterpruefung +├── Buchhaltung ───────── Leitung: buchhaltung-leitung +│ ├── Kreditoren ────── rechnungspruefung, zahlungslauf +│ ├── Überwachung ───── zahlungsverkehr, mahnwesen +│ └── Auswertung ────── monatsabschluss, kennzahlen +├── Marketing ─────────── Leitung: marketing-leitung +│ ├── Webshop ───────── shop-texte, shop-preise, shop-bilder +│ ├── Marktplätze ───── amazon-listing, amazon-anzeigen, ebay-listing, … +│ └── Inhalte ───────── social, newsletter +├── Logistik ──────────── Leitung: logistik-leitung +│ ├── Sendungen ─────── sendungsverfolgung, problemfaelle +│ └── Retouren ──────── retourenbearbeitung +└── Betrieb ───────────── (Basisagenten, siehe Basisagenten-Konzept) +``` + +### Was die Einheit trägt + +| Was | Heute | Mit Einheiten | +|---|---|---| +| **Adressbuch** | alle | die eigene Einheit, die eigene Leitung. Eine Leitung sieht zusätzlich die Leitungen der Geschwistereinheiten | +| **Arbeitsbereich** | `personal`, `shared` | `personal`, `einheit`, `shared`. Die Abteilungsablage ist der Normalfall, `shared` die Ausnahme | +| **Rechte** | je Agent | vererbt von der Einheit, je Agent verschärfbar. Was die Einheit nicht darf, kann ein Mitglied nicht bekommen | +| **Taskboard** | ein Brett | ein Brett je Einheit; `task_list` zeigt die eigene Einheit, die Leitung sieht die Untereinheiten | +| **Budget** | Agent, Instanz | Agent, Einheit, Instanz — jede Ebene deckelt die darunter | +| **Freigaben** | ein Mensch | die Leitung innerhalb ihrer Grenzen, der Mensch für alles darüber (Geld, Außenwirkung) | +| **Parallelität** | unbegrenzt | je Einheit und je Instanz eine Zahl gleichzeitiger Läufe, der Rest wartet | + +### Die eine Regel, die alles zusammenhält + +**Ein Agent kennt nur seine Einheit und seine Leitung.** Alles andere geht über die +Leitung. Das ist keine Höflichkeitsform, sondern das, was die Kosten deckelt: Der +Zuschnitt des Adressbuchs *ist* die Organisationsstruktur. + +Und weil das Adressbuch aus der Struktur kommt statt aus einer Einstellung, kann man es +nicht versehentlich aufweichen. Wer einem Agenten mehr Reichweite geben will, verschiebt +ihn im Baum — sichtbar und begründbar. + +--- + +## 4 — Die Besprechung als eigenes Mittel + +Der Vorschlag nennt den Konferenzraum, und das ist mehr als ein Bild. Heute gibt es zwei +Arten, wie Agenten sich austauschen: `send_message` (synchron, wartet, ein Gegenüber) und +das Taskboard (asynchron, ein Auftrag, ein Bearbeiter). Für „die Teamleitungen stimmen +sich ab" taugt beides nicht. + +Eine **Besprechung** ist: + +- **ein Termin**, kein Aufruf — sie steht im Taskboard wie jede andere wiederkehrende Sache +- **eine Tagesordnung**, die vorher feststeht, und eine Teilnehmerliste, die vorher feststeht +- **eine Leitung**, die eröffnet, die Runde macht und das Ergebnis schreibt +- **eine Runde je Teilnehmer**, nicht *n* Nachrichten: jeder Teilnehmer wird einmal + aufgerufen, bekommt die Tagesordnung und die bisherigen Beiträge, antwortet einmal +- **ein Protokoll** als Ergebnis — ein Dokument in der Ablage der Einheit, plus Aufgaben + für das, was beschlossen wurde + +Damit kostet eine Leitungsrunde mit sechs Teilnehmern sieben Läufe, nicht sechs mal +sechs. Und sie hinterlässt etwas Nachlesbares statt einer Kette von Nachrichten, die +niemand rekonstruieren kann. + +Das ist auch der Weg des Beispiels aus dem Vorschlag: Der Logistiker meldet ein Problem +mit Amazon-Sendungen an seine Leitung. Die bringt es in die Leitungsrunde. Die +Marketing-Leitung nimmt es mit und legt in ihrem Brett eine Aufgabe für den +Amazon-Anzeigen-Agenten an. Vier Läufe, kein direkter Kanal, ein Protokoll. + +--- + +## 5 — Was eine Organisation braucht und ein Agentenhaufen nicht + +Der Punkt, der beim Bauen am leichtesten übersehen wird: **Eine Organisation lebt von +gemeinsamem, dauerhaftem Wissen, das in keinem Kopf steckt.** + +Im Beispiel: der Lieferantenstamm, der Artikelstamm, die offenen Bestellungen, die +Retourengründe. Wenn drei Einkaufsagenten je ihre eigene Vorstellung der Lieferantenliste +im Gedächtnis tragen, hat die Instanz drei Wahrheiten und keine davon stimmt. Das ist +kein Modellproblem und kein Prompt-Problem — es ist die Frage, was Datenbank ist und was +Kontext. + +Daraus drei Festlegungen: + +1. **Stammdaten gehören in die Datenbank**, nicht in das Gedächtnis von Agenten. Das + Gedächtnis ist für Erfahrungen („dieser Lieferant antwortet nie vor Dienstag"), nicht + für Fakten („Lieferant X, Mindestbestellmenge 50"). +2. **Dokumente gehören in die Ablage der Einheit**, mit einem Eigentümer. Ein Bericht, + den zwei Agenten gleichzeitig schreiben, ist ein verlorener Bericht. +3. **Was mehrere Einheiten brauchen, ist eine bewusste Entscheidung** — ein + ausdrücklich geteilter Bereich mit benanntem Eigentümer, nicht das Standardverhalten. + +--- + +## 6 — Was sich am Menschen ändert + +Bei fünf Agenten ist der Mensch der Koordinator. Bei fünfzig kann er es nicht sein, und +der Versuch macht ihn zum Flaschenhals. + +- **Freigaben wandern in die Struktur.** Die Abteilungsleitung gibt frei, was innerhalb + ihrer Grenzen liegt. Der Mensch gibt frei, was Geld bewegt, nach außen wirkt oder die + Struktur selbst ändert. Das ist die natürliche Fortsetzung von #641 (Rechte in der + Werkzeugkonfiguration) — nur mit der Einheit als zusätzlicher Ebene. +- **Berichtet wird verdichtet.** Nicht fünfzig Laufergebnisse, sondern vier + Abteilungsberichte und eine Lage. +- **Die Aufsicht (#680) wird von einer Annehmlichkeit zur Notwendigkeit.** Bei fünf + Agenten kann ein Mensch die Läufe lesen. Bei fünfzig muss etwas anderes ihm sagen, wo + er hinsehen soll. + +--- + +## 7 — Reihenfolge + +Nichts davon muss auf einmal entstehen. Die Reihenfolge ist so gewählt, dass jede Stufe +für sich schon nützt und keine die nächste blockiert. + +| Stufe | Inhalt | Nutzen für sich | +|---|---|---| +| **0** | Parallelität deckeln, stille Kappung bei 500 beseitigen (#682) | Fehler, unabhängig von der Größe | +| **1** | Einheiten als Struktur: Baum, Zugehörigkeit, vererbte Rechte, Adressbuch nach Einheit | Der Schnitt, der alles Weitere trägt | +| **2** | Ablage und Brett je Einheit | Buchhaltung und Einkauf treten sich nicht mehr auf die Füße | +| **3** | Budget und Parallelität je Einheit | Eine ausufernde Abteilung legt nicht die Instanz lahm | +| **4** | Besprechung als Mittel, mit Protokoll | Leitungen können sich abstimmen, ohne *n²* Nachrichten | +| **5** | Freigabe durch die Leitung innerhalb von Grenzen | Der Mensch hört auf, Flaschenhals zu sein | +| **6** | Oberfläche: Organigramm statt Agentenliste, Lage je Abteilung | Bei fünfzig Agenten ist eine flache Liste keine Übersicht | + +Stufe 1 ist die einzige, die wirklich weh tut, weil sie Konfiguration, Werkzeuge, +Arbeitsbereiche und Oberfläche gleichzeitig berührt. Sie zuerst zu bauen ist trotzdem +richtig: jede spätere Stufe hängt daran, und jede Woche, die eine Instanz ohne Einheiten +wächst, wird der Umzug teurer. + +--- + +## 8 — Offene Entscheidungen + +- **Ist eine Einheit ein Agent?** Eine Leitung könnte ein gewöhnlicher Agent mit + besonderen Rechten sein — oder die Einheit hat eine Leitungsrolle, die auch unbesetzt + bleiben kann (dann übernimmt die übergeordnete Leitung). Vorschlag: das zweite. Eine + Einheit ohne Leitung muss möglich sein, sonst kostet jede Gliederung sofort einen Agenten. +- **Wie tief?** `MaxDelegationDepth = 3` muss steigen, aber nicht auf unendlich — eine + Kette ohne Grenze ist wieder ein Zyklus in Zeitlupe. Vorschlag: Tiefe des Baums plus + eins, aus der Struktur berechnet statt als Zahl eingestellt. +- **Gehören Einheiten in die Instanzkonfiguration oder in die Datenbank?** Die + Zugehörigkeit ändert sich selten, aber sie ändert Rechte — also gehört sie dorthin, wo + Änderungen im Audit stehen. Vorschlag: Datenbank, mit Abbild in der Konfiguration. +- **Darf ein Agent in zwei Einheiten sein?** In echten Organisationen ja (Matrix). Das + macht das Adressbuch und die Rechtevererbung deutlich schwieriger. Vorschlag: zunächst + nein, und beobachten, ob es fehlt. + +--- + +## 9 — Items + +| Item | Vorhaben | +|---|---| +| #682 | Läufe deckeln: Parallelität begrenzen, Kappung bei 500 beseitigen | +| #683 | Einheiten: Baum, Zugehörigkeit, vererbte Rechte, Adressbuch nach Einheit | +| #684 | Ablage und Taskboard je Einheit | +| #685 | Budget und Parallelität je Einheit | +| #686 | Besprechung: Termin, Tagesordnung, Runde, Protokoll | +| #687 | Freigabe durch die Leitung innerhalb von Grenzen | +| #688 | Organigramm in Oberfläche und WebUI |