612 lines
24 KiB
Markdown
612 lines
24 KiB
Markdown
# ClawdDotNet – Instanz-Setup-Guide
|
||
|
||
Anleitung für die vollständige Planung, Erstellung und Konfiguration einer neuen ClawdDotNet-Instanz. Richtet sich an menschliche Nutzer und AI-Agenten gleichermaßen.
|
||
|
||
---
|
||
|
||
## 1. Planung: Was soll die Instanz leisten?
|
||
|
||
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? | 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 |
|
||
| 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 |
|
||
|
||
**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.
|
||
|
||
---
|
||
|
||
## 2. Verzeichnisstruktur einer Instanz
|
||
|
||
Eine Instanz hat folgende Struktur. `CreateInstance()` und `CreateAgent()` im InstanceDirectoryManager erzeugen diese automatisch.
|
||
|
||
```
|
||
Instance-{Name}/
|
||
├── InstanceSettings.json ← Instanz-Konfiguration + API-Key
|
||
├── TokenUsage.json ← Verbrauchsprotokoll (leer bei Start)
|
||
├── state.db ← SQLite StateStore (wird zur Laufzeit erzeugt)
|
||
└── Agents/
|
||
├── AgentList.json ← Agenten-Register (Name, Beschreibung, Ordner)
|
||
├── SharedWorkspace/ ← Geteilter Arbeitsbereich
|
||
│ └── coordination/ ← Status-Dateien für Inter-Agenten-Kommunikation
|
||
├── SharedWorkspaces/ ← Bereiche mit Mitgliederliste (#684), einer je Einheit
|
||
│ └── {bereich}/ ← in FileRW als workspace "unit" oder "{bereich}"
|
||
└── Agent-{Name}/
|
||
├── AgentSettings.json ← Agent-Konfiguration (Modell, Tools, Scheduler)
|
||
├── Identity.md ← WER ist der Agent (Rolle, Expertise)
|
||
├── Soul.md ← WIE arbeitet der Agent (Persönlichkeit, Methodik)
|
||
├── ChatContext.json ← Aktueller Konversationskontext
|
||
├── ChatHistory.json ← Vollständiger Chatverlauf
|
||
├── Logs/ ← Agent-spezifische Logs
|
||
└── Workspace/ ← Persönlicher Arbeitsbereich
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Schritt-für-Schritt: Instanz erstellen
|
||
|
||
### 3.1 Instanz anlegen
|
||
|
||
Über die UI: **Instanz-Manager → Neue Instanz erstellen**
|
||
|
||
Oder manuell die Ordnerstruktur erzeugen. Die `InstanceSettings.json` hat dieses Format:
|
||
|
||
```json
|
||
{
|
||
"instanceId": "<8-Zeichen-GUID>",
|
||
"instanceName": "MeinProjekt",
|
||
"openRouterApiKey": "",
|
||
"workingDirectory": "",
|
||
"logDirectory": "",
|
||
"backupDirectory": "",
|
||
"autoBackupEnabled": false,
|
||
"autoBackupTime": "03:00",
|
||
"backupKeepCount": 14,
|
||
"webServerPort": 7001,
|
||
"agents": [],
|
||
"services": []
|
||
}
|
||
```
|
||
|
||
**Wichtig:** Der `openRouterApiKey` muss gesetzt werden, bevor Agenten funktionieren.
|
||
|
||
### Protokoll und Sicherungen gehören der Instanz
|
||
|
||
`logDirectory` und `backupDirectory` leer zu lassen ist der Normalfall und nicht die
|
||
Ausnahme: Leer heißt `<Instanzverzeichnis>/Logs` beziehungsweise
|
||
`<Instanzverzeichnis>/Backups`.
|
||
|
||
Beides stand bis #528 (Stufe 1) in den anwendungsweiten Einstellungen und galt damit für
|
||
jede Instanz — in `Startup.log` standen abwechselnd Zeilen zweier Instanzen, ohne
|
||
Kennzeichnung, welche gerade spricht.
|
||
|
||
Ein eingetragener Wert geht vor und zählt, wenn er relativ ist, **gegen das
|
||
Instanzverzeichnis** — nicht gegen das Arbeitsverzeichnis des Prozesses. Ein
|
||
systemd-Dienst ohne `WorkingDirectory=` startet in `/`, und `"./Logs"` zeigte dort auf
|
||
`/Logs`.
|
||
|
||
Zwei Instanzen sollten sich kein Sicherungsverzeichnis teilen. Die Aufbewahrung
|
||
(`backupKeepCount`) räumt dort nach dem Präfix `backup_<Instanzname>_` auf, und ein
|
||
Präfix ist keine Grenze: Das Archiv der Instanz `Test_2` fängt mit `backup_Test_` an und
|
||
wird von `Test` mitgezählt.
|
||
|
||
Wer die fünf Schlüssel noch in seiner alten `Settings.json` stehen hat, findet beim
|
||
nächsten Start eine Warnung im Protokoll; übernommen werden sie **nicht** — ein Pfad für
|
||
alle Instanzen wäre genau der Zustand, den die Trennung beseitigt.
|
||
|
||
### 3.2 Agenten anlegen
|
||
|
||
Pro Agent wird ein Ordner `Agent-{Name}` unter `Agents/` erstellt.
|
||
|
||
**AgentList.json** — Register aller Agenten:
|
||
|
||
```json
|
||
{
|
||
"agents": [
|
||
{
|
||
"name": "Analyst",
|
||
"description": "Recherchiert und analysiert Daten aus externen Quellen",
|
||
"folderName": "Agent-Analyst"
|
||
},
|
||
{
|
||
"name": "Reporter",
|
||
"description": "Erstellt Berichte und versendet sie per E-Mail",
|
||
"folderName": "Agent-Reporter"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 3.3 AgentSettings.json
|
||
|
||
Jeder Agent bekommt eine `AgentSettings.json`:
|
||
|
||
```json
|
||
{
|
||
"agentId": "analyst",
|
||
"displayName": "Analyst",
|
||
"model": "google/gemini-2.5-flash",
|
||
"systemPrompt": "",
|
||
"tools": {
|
||
"WebFetch": {
|
||
"allowedDomains": ["example.com", "api.example.com"]
|
||
},
|
||
"FileRW": {
|
||
"sharedAccessLevel": "ReadWrite",
|
||
"personalAllowedExtensions": [".txt", ".json", ".md", ".csv"],
|
||
"sharedAllowedExtensions": [".txt", ".json", ".md"]
|
||
}
|
||
},
|
||
"scheduler": {
|
||
"cron": "0 8 * * 1-5",
|
||
"runOnStart": false,
|
||
"taskMessage": "Recherchiere die neuesten Daten und speichere sie im SharedWorkspace."
|
||
},
|
||
"toolJobs": [],
|
||
"loopGuard": {
|
||
"maxSteps": 15,
|
||
"maxTokens": 50000,
|
||
"timeoutSeconds": 300,
|
||
"maxContextTokens": 100000,
|
||
"compactionThreshold": 0.8
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.4 Identity.md schreiben
|
||
|
||
Definiert **WER** der Agent ist. Kurz, prägnant, rollenspezifisch.
|
||
|
||
```markdown
|
||
# Analyst
|
||
|
||
Du bist ein Datenanalyst im ClawdDotNet-Team "MeinProjekt".
|
||
|
||
## Rolle
|
||
- Recherche und Aufbereitung externer Daten
|
||
- Ergebnisse im SharedWorkspace als JSON ablegen
|
||
|
||
## Expertise
|
||
- Web-Recherche, Datenextraktion, strukturierte Zusammenfassungen
|
||
|
||
## Kontext
|
||
- Deine Ergebnisse werden vom Reporter-Agenten weiterverarbeitet
|
||
- Lege Dateien im SharedWorkspace unter coordination/ ab
|
||
```
|
||
|
||
### 3.5 Soul.md schreiben
|
||
|
||
Definiert **WIE** der Agent arbeitet.
|
||
|
||
```markdown
|
||
# Arbeitsweise
|
||
|
||
## Persönlichkeit
|
||
- Gründlich und faktenbasiert
|
||
- Komprimiert Informationen auf das Wesentliche
|
||
|
||
## Methodik
|
||
1. Quellen prüfen und Daten abrufen
|
||
2. Relevante Informationen extrahieren
|
||
3. Strukturiertes JSON erstellen
|
||
4. Im SharedWorkspace ablegen
|
||
|
||
## Ausgabeformat
|
||
- Ergebnisse immer als JSON mit Timestamp
|
||
- Keine Prosa, nur strukturierte Daten
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Modellwahl: Kosten vs. Leistung
|
||
|
||
Die Modellwahl hat den größten Einfluss auf die laufenden Kosten. Nicht jeder Agent braucht das teuerste Modell.
|
||
|
||
### Modell-Empfehlungen nach Aufgabentyp
|
||
|
||
| Aufgabentyp | Empfohlenes Modell | Kosten (ca.) | Begründung |
|
||
|-------------|-------------------|-------------|------------|
|
||
| **Einfache Routineaufgaben** (Dateien verschieben, Status prüfen, weiterleiten) | `google/gemini-2.5-flash` | ~$0.15/M input | Schnell, günstig, zuverlässiger Tool-Use |
|
||
| **Textverarbeitung** (Zusammenfassungen, Berichte, E-Mails) | `google/gemini-2.5-flash` oder `anthropic/claude-haiku-4-5` | $0.15–0.80/M input | Gutes Preis/Leistungs-Verhältnis |
|
||
| **Analyse & Reasoning** (Datenanalyse, Entscheidungen, komplexe Logik) | `anthropic/claude-sonnet-4-5` | ~$3/M input | Starkes Reasoning bei akzeptablen Kosten |
|
||
| **Koordinator-Agent** (orchestriert andere, trifft Entscheidungen) | `anthropic/claude-sonnet-4-5` | ~$3/M input | Braucht gutes Verständnis der Gesamtsituation |
|
||
| **Maximale Qualität** (kritische Entscheidungen, kreative Aufgaben) | `anthropic/claude-opus-4` | ~$15/M input | Nur wenn Qualität wichtiger als Kosten |
|
||
| **Budget-Minimum** | `google/gemini-2.5-flash-lite` | ~$0.02/M input | Für einfachste Aufgaben, schlechterer Tool-Use |
|
||
|
||
### Kostenberechnung
|
||
|
||
```
|
||
Kosten pro Run ≈ (Input-Tokens × Inputpreis) + (Output-Tokens × Outputpreis)
|
||
|
||
Beispiel: Gemini 2.5 Flash, typischer Run (5000 in, 1000 out):
|
||
= 5000 × $0.00000015 + 1000 × $0.0000006
|
||
= $0.00075 + $0.0006
|
||
= $0.00135 pro Run
|
||
|
||
Beispiel: Claude Sonnet, typischer Run (5000 in, 1000 out):
|
||
= 5000 × $0.000003 + 1000 × $0.000015
|
||
= $0.015 + $0.015
|
||
= $0.03 pro Run
|
||
```
|
||
|
||
**Cron alle 5 Minuten mit Gemini Flash:** ~288 Runs/Tag × $0.00135 = **~$0.39/Tag**
|
||
**Cron alle 5 Minuten mit Claude Sonnet:** ~288 Runs/Tag × $0.03 = **~$8.64/Tag**
|
||
|
||
### LoopGuard für Kostenkontrolle anpassen
|
||
|
||
| Szenario | maxSteps | maxTokens | timeoutSeconds |
|
||
|----------|----------|-----------|----------------|
|
||
| Einfache Routine | 5–10 | 20.000 | 120 |
|
||
| Standard-Aufgabe | 10–20 | 50.000 | 300 |
|
||
| Komplexe Analyse | 20–30 | 80.000 | 600 |
|
||
| Budget-kritisch | 3–5 | 10.000 | 60 |
|
||
|
||
---
|
||
|
||
## 5. Tool-Zuweisung
|
||
|
||
### Verfügbare Tools
|
||
|
||
| Tool | Zweck | Benötigte Config | Background Jobs |
|
||
|------|-------|-----------------|-----------------|
|
||
| **FileRW** | Dateien lesen/schreiben im Workspace | (optional) sharedAccessLevel, allowedExtensions | Nein |
|
||
| **Database** | SQL/NoSQL-Zugriff | type, connectionString | Nein |
|
||
| **Mail** | E-Mails senden/empfangen | smtpHost, imapHost, username, password | Ja: `mail_check_unread` |
|
||
| **Telegram** | Telegram-Nachrichten | botToken | Ja: `telegram_poll` |
|
||
| **WebFetch** | Webseiten/RSS abrufen | allowedDomains | Nein |
|
||
| **WebMonitor** | Webseiten auf Änderungen prüfen | monitors (mit url, parser, idPattern) | Nein |
|
||
| **FTP** | Datei-Upload/Download | host | Nein |
|
||
| **DirectAPI** | Finanzdaten (Aktien, Crypto, Forex) | providers (mit apiKey pro Provider) | Nein |
|
||
| **SocialMediaManager** | X, Reddit, YouTube-Transkripte | (je nach Aktion) xApiKey, openRouterApiKey | Ja: `sm_yt_monitor`, `sm_transcript_notifier` |
|
||
| **AgentComm** | Nachrichten an andere Agenten senden | (keine) | Nein |
|
||
| **AgentSpawn** | Andere Agenten starten und beauftragen | (keine) | Nein |
|
||
|
||
### Zuweisungsregeln
|
||
|
||
1. **Minimalprinzip:** Nur Tools zuweisen, die der Agent tatsächlich braucht
|
||
2. **Tool = Berechtigung:** Ein Tool in `tools` aufzunehmen gewährt sofort Zugriff (PermissionGate prüft nur Existenz im Dictionary)
|
||
3. **Config = Sicherheitsgrenze:** `allowedDomains`, `allowedTables`, `allowedRecipients` etc. sind die echten Einschränkungen
|
||
4. **AgentComm/AgentSpawn:** Nur dem Koordinator-Agenten zuweisen, nicht jedem
|
||
5. **Tool Jobs prüfen:** Ein ToolJob funktioniert nur wenn der Agent das Tool auch zugewiesen hat — die Laufzeitprüfung deaktiviert den Job sonst automatisch
|
||
|
||
### Typische Tool-Kombinationen
|
||
|
||
| Agenten-Rolle | Tools |
|
||
|--------------|-------|
|
||
| Koordinator | FileRW, AgentComm, AgentSpawn |
|
||
| Recherche-Agent | FileRW, WebFetch, WebMonitor |
|
||
| Kommunikations-Agent | FileRW, Mail, Telegram |
|
||
| Datenbank-Agent | FileRW, Database |
|
||
| Social-Media-Agent | FileRW, SocialMediaManager, WebFetch |
|
||
| Finanz-Agent | FileRW, DirectAPI, Database |
|
||
|
||
---
|
||
|
||
## 5a. Fremde Laufzeit: ein Agent in Claude Code (#712)
|
||
|
||
Ein Agent kann statt in unserer Engine in **Claude Code** arbeiten (gedacht für die
|
||
Entwicklungsabteilung) oder in einem **Befehl**. Er läuft dann in der Sandbox auf einer
|
||
Kopie seines Arbeitsbereichs. Was er ändert, liegt danach als Vorschlag unter
|
||
`Agents/Agent-<id>/proposals/<lauf>/` und wird **nicht** übernommen. Taskboard und Kollegen
|
||
erreicht er nur über den MCP-Server der Instanz. Hintergrund: Organisation-Konzept,
|
||
Abschnitt 7a.
|
||
|
||
**Voraussetzungen (nur Linux):**
|
||
|
||
1. `bubblewrap` ist installiert (`apt install bubblewrap`). Die Karte „Laufzeit“ in der
|
||
Agentenansicht meldet „Die Sandbox ist bereit“. Ohne Sandbox laufen fremde Laufzeiten
|
||
gar nicht, sie fallen auch nicht auf die native Engine zurück.
|
||
2. Claude Code ist für den Benutzer installiert, unter dem die Instanz läuft. Mit dem
|
||
nativen Installer liegt es unter `~/.local/bin/claude` und wird dort gefunden. Bei einer
|
||
npm-Installation kommen das Programm und Node in `claudeCode.executable` bzw.
|
||
`claudeCode.readOnlyPaths` der `instance.json`.
|
||
3. Das Konto (Karte „Laufzeit“ → „Bearbeiten“, gilt für die ganze Instanz):
|
||
- **API-Schlüssel (Voreinstellung):** am besten ein eigener Schlüssel in einem
|
||
Anthropic-Workspace mit Ausgabengrenze. Der Schlüssel ist im Lauf für Claude Code
|
||
lesbar, denn es muss ihn benutzen.
|
||
- **Abo:** ein Token aus `claude setup-token`, erzeugt auf einem Rechner, an dem du
|
||
angemeldet bist. Das Abo teilt sein Kontingent mit deiner eigenen Nutzung, und ob es
|
||
ein Agentensystem betreiben darf, regeln seine Bedingungen.
|
||
|
||
**Der Agent** (Karte „Laufzeit“ oder `AgentSettings.json`):
|
||
|
||
```json
|
||
"runtime": {
|
||
"kind": "claude-code",
|
||
"allowedTools": ["Read", "Edit", "Write", "Glob", "Grep", "mcp__clawd"],
|
||
"maxTurns": 30,
|
||
"timeoutMinutes": 30,
|
||
"egress": ["pypi.org", "files.pythonhosted.org"]
|
||
}
|
||
```
|
||
|
||
- `allowedTools` leer lassen heißt: die obige Voreinstellung. `Bash` erlaubt die Shell
|
||
**in der Sandbox**. WebFetch und WebSearch sind immer verboten.
|
||
- `egress` nennt Hosts, die der Lauf zusätzlich zur API erreichen darf. Es gilt nur HTTPS
|
||
und nur an öffentliche Adressen.
|
||
- `model` des Agenten wird an Claude Code weitergegeben (`anthropic/claude-sonnet-5` wird
|
||
zu `claude-sonnet-5`). Ein Modell eines anderen Anbieters wird ignoriert; dann gilt die
|
||
Voreinstellung von Claude Code.
|
||
|
||
Beim Befehl (`"kind": "command"`, dazu `command` und `arguments`) kommt die Nachricht über
|
||
stdin, und was der Befehl ausgibt, ist das Ergebnis. Den MCP-Server erreicht er mit
|
||
`$CLAWD_HELPER --mcp-bridge --socket $CLAWD_MCP_SOCKET`; das Token liegt in
|
||
`$CLAWD_MCP_TOKEN_FILE`.
|
||
|
||
**Verbrauch:** Jeder Lauf steht in `RunUsage` mit Laufzeit und Token. Auf dem Abo kostet
|
||
er 0 $ und ist als Abo-Lauf markiert, verbraucht aber Kontingent.
|
||
|
||
---
|
||
|
||
## 6. Kritische Analyse: Ist die Idee umsetzbar?
|
||
|
||
Vor dem Aufbau einer Instanz systematisch prüfen:
|
||
|
||
### Checkliste: Machbarkeit
|
||
|
||
| Prüfpunkt | Frage | Risiko wenn nein |
|
||
|-----------|-------|-----------------|
|
||
| **Tool-Abdeckung** | Gibt es für jeden externen Zugang ein passendes Tool? | Hoch — ohne Tool kein Zugriff |
|
||
| **API-Verfügbarkeit** | Haben alle externen APIs die nötigen Endpunkte? | Hoch — Tool ist nutzlos ohne funktionierende API |
|
||
| **Datenformat** | Kann das Tool die Daten in einem Format liefern, das das LLM verarbeiten kann? | Mittel — große/binäre Daten überfordern den Context |
|
||
| **Autonomie-Level** | Kann die Aufgabe ohne menschliche Zwischenschritte laufen? | Mittel — wenn nicht, braucht es manuelle Trigger statt Cron |
|
||
| **Budget** | Reicht das Token-Budget für die geplante Frequenz? | Hoch — unterschätzter Verbrauch ist der häufigste Fehler |
|
||
| **Koordination** | Brauchen Agenten wirklich Echtzeit-Kommunikation oder reicht SharedWorkspace? | Mittel — AgentComm kostet Token auf beiden Seiten |
|
||
|
||
### Häufige Fallstricke und Lösungen
|
||
|
||
#### Fallstrick 1: Token-Explosion durch Polling
|
||
|
||
**Problem:** Agent wird per Cron alle 2 Minuten geweckt → 720 LLM-Runs/Tag, auch wenn nichts passiert ist.
|
||
|
||
**Lösung:** Tool Jobs (`IToolJobProvider`) statt Agent-Wakeup verwenden. Das Tool prüft selbst (kein LLM) und weckt den Agenten nur bei Bedarf. Kostet ~0 Token pro Leer-Check.
|
||
|
||
```json
|
||
"scheduler": null,
|
||
"toolJobs": [
|
||
{
|
||
"toolName": "Telegram",
|
||
"jobTypeId": "telegram_poll",
|
||
"cron": "*/1 * * * *",
|
||
"enabled": true
|
||
}
|
||
]
|
||
```
|
||
|
||
#### Fallstrick 2: Context-Overflow bei großen Daten
|
||
|
||
**Problem:** WebFetch liefert 50 KB HTML, Database-Query liefert 200 Zeilen → Context voll, Compaction verliert wichtige Infos.
|
||
|
||
**Lösung:**
|
||
- `maxResponseKb` in WebFetch begrenzen (Standard: 512 KB — oft zu viel)
|
||
- Database-Queries mit LIMIT versehen (in SystemPrompt anweisen)
|
||
- LoopGuard `maxContextTokens` angemessen setzen
|
||
- Agent in der Identity anweisen, Ergebnisse sofort zu verarbeiten und zusammenzufassen
|
||
|
||
#### Fallstrick 3: Agenten reden aneinander vorbei
|
||
|
||
**Problem:** AgentComm-Nachrichten ohne klare Struktur → Missverständnisse, Endlosschleifen.
|
||
|
||
**Lösung:**
|
||
- In Soul.md ein festes Nachrichtenformat definieren (JSON mit `type`, `content`, `expectedAction`)
|
||
- SharedWorkspace für asynchronen Datenaustausch bevorzugen (Dateien statt Nachrichten)
|
||
- Koordinator-Agent als einzigen mit AgentSpawn/AgentComm ausstatten
|
||
|
||
#### Fallstrick 4: Scheduler ohne sichtbares Ergebnis
|
||
|
||
**Problem:** Agent wird per Cron geweckt, arbeitet im Hintergrund, aber niemand sieht ob es funktioniert.
|
||
|
||
**Lösung:**
|
||
- Agent soll Ergebnisse in den SharedWorkspace schreiben (prüfbar per FileRW)
|
||
- Wichtige Ergebnisse per Mail oder Telegram melden lassen
|
||
- TokenUsage.json regelmäßig prüfen (Kosten vs. erwarteter Output)
|
||
|
||
#### Fallstrick 5: Tool-Config Fehler erst zur Laufzeit sichtbar
|
||
|
||
**Problem:** Falscher `botToken`, fehlender `connectionString` → Agent startet, Tool schlägt beim ersten Aufruf fehl.
|
||
|
||
**Lösung:**
|
||
- Vor dem Scheduler-Start einen manuellen Test-Run durchführen
|
||
- Agent manuell starten mit einer Test-Aufgabe: "Sende eine Test-Nachricht über Telegram"
|
||
- Logs unter `Agent-{Name}/Logs/` prüfen
|
||
|
||
#### Fallstrick 6: Kosten unterschätzt bei Multi-Agent-Setup
|
||
|
||
**Problem:** 3 Agenten × Cron alle 10 Min × Claude Sonnet = ~$130/Tag.
|
||
|
||
**Lösung:**
|
||
- Billige Modelle für Routinearbeit (Gemini Flash, Haiku)
|
||
- Teure Modelle nur für Koordinator oder komplexe Analyse
|
||
- LoopGuard `maxTokens` aggressiv begrenzen für Routine-Agenten
|
||
- Tool Jobs statt Agent-Wakeup wo möglich
|
||
|
||
#### Fallstrick 7: YouTube-Transkription braucht externes Tool
|
||
|
||
**Problem:** `SocialMediaManager` mit `sm_yt_monitor` Job braucht `yt-dlp` als externes CLI-Tool auf dem System installiert.
|
||
|
||
**Lösung:**
|
||
- Vor Instanz-Setup prüfen ob `yt-dlp` installiert und im PATH ist
|
||
- Ohne `yt-dlp` funktionieren `x_search` und `reddit_search` trotzdem
|
||
|
||
---
|
||
|
||
## 7. Beispiel-Instanz: "TelegramBot"
|
||
|
||
Einfache Instanz mit einem Agenten, der über Telegram kommuniziert.
|
||
|
||
### Planung
|
||
|
||
- **Aufgabe:** Auf Telegram-Nachrichten antworten, einfache Fragen beantworten, Dateien im Workspace verwalten
|
||
- **Agenten:** 1 (kein Koordinationsbedarf)
|
||
- **Budget:** ~$0.50/Tag
|
||
- **Modell:** `google/gemini-2.5-flash` (günstig, ausreichend für Chat)
|
||
|
||
### Verzeichnisstruktur
|
||
|
||
```
|
||
Instance-TelegramBot/
|
||
├── InstanceSettings.json
|
||
├── TokenUsage.json
|
||
└── Agents/
|
||
├── AgentList.json
|
||
├── SharedWorkspace/
|
||
└── Agent-Assistent/
|
||
├── AgentSettings.json
|
||
├── Identity.md
|
||
├── Soul.md
|
||
├── Logs/
|
||
└── Workspace/
|
||
```
|
||
|
||
### AgentList.json
|
||
|
||
```json
|
||
{
|
||
"agents": [
|
||
{
|
||
"name": "Assistent",
|
||
"description": "Beantwortet Telegram-Nachrichten und verwaltet Notizen",
|
||
"folderName": "Agent-Assistent"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### AgentSettings.json
|
||
|
||
```json
|
||
{
|
||
"agentId": "assistent",
|
||
"displayName": "Assistent",
|
||
"model": "google/gemini-2.5-flash",
|
||
"systemPrompt": "",
|
||
"tools": {
|
||
"Telegram": {
|
||
"botToken": "123456:ABC-DEF...",
|
||
"defaultChatId": "987654321",
|
||
"allowedChatIds": ["987654321"]
|
||
},
|
||
"FileRW": {
|
||
"sharedAccessLevel": "Denied",
|
||
"personalAllowedExtensions": [".txt", ".json", ".md"]
|
||
}
|
||
},
|
||
"scheduler": null,
|
||
"toolJobs": [
|
||
{
|
||
"jobId": "tgpoll01",
|
||
"toolName": "Telegram",
|
||
"jobTypeId": "telegram_poll",
|
||
"cron": "*/1 * * * *",
|
||
"enabled": true,
|
||
"runOnStart": true
|
||
}
|
||
],
|
||
"loopGuard": {
|
||
"maxSteps": 10,
|
||
"maxTokens": 30000,
|
||
"timeoutSeconds": 120,
|
||
"maxContextTokens": 100000,
|
||
"compactionThreshold": 0.8
|
||
}
|
||
}
|
||
```
|
||
|
||
### Kostenabschätzung
|
||
|
||
- Telegram-Polling: 1440 Ticks/Tag, ~0 Token (Tool Job, kein LLM)
|
||
- Agent-Wakeups: geschätzt 20 Nachrichten/Tag × ~$0.00135/Run = **~$0.03/Tag**
|
||
- Deutlich unter dem $0.50 Budget
|
||
|
||
---
|
||
|
||
## 8. Beispiel-Instanz: "Recherche-Team"
|
||
|
||
Multi-Agent-Setup für automatisierte Web-Recherche mit Berichterstattung.
|
||
|
||
### Planung
|
||
|
||
- **Aufgabe:** Täglich Webseiten/RSS-Feeds prüfen, relevante Infos sammeln, Bericht per E-Mail senden
|
||
- **Agenten:** 3 (Recherche, Analyse, Bericht)
|
||
- **Budget:** ~$5/Tag
|
||
|
||
### Agenten-Design
|
||
|
||
| Agent | Modell | Tools | Scheduler | Zweck |
|
||
|-------|--------|-------|-----------|-------|
|
||
| Crawler | `google/gemini-2.5-flash` | FileRW, WebFetch, WebMonitor | Cron `0 7 * * *` | Daten sammeln, in SharedWorkspace ablegen |
|
||
| Analyst | `anthropic/claude-sonnet-4-5` | FileRW | Cron `0 8 * * *` | Daten analysieren, Zusammenfassung erstellen |
|
||
| Reporter | `google/gemini-2.5-flash` | FileRW, Mail | Cron `0 9 * * *` | Zusammenfassung als E-Mail versenden |
|
||
|
||
### Warum dieses Setup?
|
||
|
||
- **Crawler** braucht kein teures Modell — holt nur Daten ab und speichert sie
|
||
- **Analyst** bekommt Sonnet weil Analyse-Qualität hier den Unterschied macht
|
||
- **Reporter** braucht kein teures Modell — formatiert nur und sendet
|
||
- **Zeitversatz** (7:00 → 8:00 → 9:00) statt AgentComm — günstiger und zuverlässiger
|
||
- **SharedWorkspace** statt Echtzeit-Kommunikation — keine doppelten Token-Kosten
|
||
|
||
### Kostenabschätzung
|
||
|
||
- Crawler: 1 Run/Tag × ~$0.002 = $0.002
|
||
- Analyst: 1 Run/Tag × ~$0.03 = $0.03
|
||
- Reporter: 1 Run/Tag × ~$0.002 = $0.002
|
||
- **~$0.034/Tag** — weit unter Budget
|
||
|
||
---
|
||
|
||
## 9. Checkliste: Neue Instanz aufsetzen
|
||
|
||
- [ ] Aufgabe und Agenten-Aufteilung definiert
|
||
- [ ] Kostenabschätzung durchgeführt (Modell × Frequenz × Agenten)
|
||
- [ ] Prüfung: Alle nötigen Tools vorhanden?
|
||
- [ ] Prüfung: Alle externen APIs/Zugangsdaten verfügbar?
|
||
- [ ] Prüfung: Externe Abhängigkeiten installiert? (z.B. yt-dlp)
|
||
- [ ] Instanz-Ordner erstellt (manuell oder über UI)
|
||
- [ ] `InstanceSettings.json` mit API-Key konfiguriert
|
||
- [ ] `AgentList.json` mit allen Agenten erstellt
|
||
- [ ] Pro Agent: `AgentSettings.json` mit Modell, Tools, LoopGuard
|
||
- [ ] Pro Agent: `Identity.md` (Rolle, Expertise, Kontext)
|
||
- [ ] Pro Agent: `Soul.md` (Persönlichkeit, Methodik, Ausgabeformat)
|
||
- [ ] Pro Agent: Tool-Configs mit echten Zugangsdaten befüllt
|
||
- [ ] Tool Jobs konfiguriert (statt Agent-Wakeup wo sinnvoll)
|
||
- [ ] Manueller Test-Run pro Agent durchgeführt
|
||
- [ ] Logs geprüft — keine Tool-Fehler?
|
||
- [ ] Scheduler aktiviert
|
||
- [ ] Nach 24h: TokenUsage.json prüfen, Kosten validieren
|