Multi-Agent-System aufbauen mit Claude Code: Architektur, Kosten und die häufigsten Fehler

Was ist ein Multi-Agent-System?

Ein Multi-Agent-System besteht aus mehreren KI-Agents, die koordiniert an gemeinsamen Zielen arbeiten. Jeder Agent hat seinen eigenen Kontext, seine eigene Aufgabe und — in gut konzipierten Systemen — seine eigene Rolle in einer Hierarchie.

Das klingt nach Science-Fiction, ist aber konkrete Software-Architektur: Statt einem langen monolithischen Prompt orchestriert ein Orchestrator-Agent mehrere Subagents, die spezialisiert und parallel arbeiten. Die Koordination läuft über Dateisystem, Nachrichten oder geteilte Datenbanken.

Der entscheidende Unterschied zum einzelnen Agenten: Ein einzelner Agent arbeitet linear und sequenziell. Er hat ein Kontext-Fenster, eine Aufmerksamkeit, einen Arbeitsfluss. Ein Multi-Agent-System verteilt Aufgaben auf mehrere parallele Threads — ähnlich wie ein Entwicklerteam gegenüber einem Einzelentwickler.

Wann lohnt sich ein Multi-Agent-System?

Die ehrliche Antwort: Nicht immer. Ein zweiter Agent bedeutet mehr Overhead, mehr Koordinationsaufwand und mehr potenzielle Fehlerquellen. Erst wenn diese drei Bedingungen erfüllt sind, macht ein Multi-Agent-System Sinn:

1. Tasks können parallel laufen

Wenn Schritt B auf Schritt A warten muss, hilft ein zweiter Agent wenig. Aber wenn du gleichzeitig Recherche betreiben, Code schreiben und Tests ausführen kannst — dann ist Parallelisierung der stärkste Hebel. Unser Video-Pipeline-System zum Beispiel läuft so: Agent 1 transkribiert YouTube-Videos, Agent 2 extrahiert Insights, Agent 3 generiert Social Posts — alles gleichzeitig.

2. Verschiedene Expertise-Bereiche sind nötig

Ein Agent der gleichzeitig Senior Developer, SEO-Experte, Buchhalter und Social Media Manager sein soll, wird in allen Bereichen mittelmäßig. Spezialisierte Agents mit fokussierten Rollen — und entsprechend fokussierten CLAUDE.md-Anweisungen — liefern konsistent bessere Outputs.

3. Ein Agent hätte zu viel Kontext

Wenn die Aufgabe 200.000+ Tokens an Kontext erfordern würde — Codebasis lesen, Docs durchsuchen, externe APIs abfragen, Ergebnis formatieren — dann schlägt das Kontext-Fenster an. Mit mehreren Agents verteilt sich die Last: Jeder bekommt nur das, was er braucht.

Die 3 Haupt-Architekturen

a) Hierarchisch: CEO → Manager → Worker

Das Modell das wir selbst betreiben. Ein Orchestrator-Agent (CEO) gibt Aufgaben an Department-Heads weiter, die wiederum Worker-Agents koordinieren. Jede Ebene hat klare Verantwortlichkeiten — und die richtigen Modelle (dazu später mehr).

Wann einsetzen: Wenn du eine autonome Organisation bauen willst, die selbstständig Aufgaben priorisiert, delegiert und rapportiert. Die Hierarchie sorgt dafür, dass strategische Entscheidungen beim Orchestrator bleiben, während Worker sich auf Ausführung konzentrieren.

Unser echtes Beispiel: Der CEO-Agent bekommt morgens ein Briefing, plant den Tag, erstellt Tasks in Notion und delegiert sie an die Department Heads. ICT bekommt alle Code-Tasks, Strategy schreibt Blogs und Posts, Operations kümmert sich um Buchhaltung und E-Mail. Kein manuelles Eingreifen nötig.

b) Pipeline: Agent A → Agent B → Agent C

Jeder Agent verarbeitet den Output des vorherigen und gibt ihn weiter. Ideal für klar definierte Workflows mit sequenziellen Schritten.

Wann einsetzen: Für wiederholbare, strukturierte Prozesse — Content-Pipelines, Datenverarbeitung, Build-Automatisierung. Jeder Agent hat exakt eine Verantwortung. Fehler sind leicht zu lokalisieren: Wo bricht die Pipeline?

Vorteil gegenüber Hierarchie: Weniger Overhead. Kein Orchestrator-Agent nötig der Aufgaben plant — der Workflow ist fest kodiert.

c) Peer-to-Peer: Agents koordinieren direkt

Agents schreiben sich gegenseitig Nachrichten und koordinieren ohne zentralen Koordinator. In der Praxis selten optimal — aber für bestimmte Review- und Feedback-Loops nützlich.

Wann einsetzen: Peer-Reviews, parallele Drafts mit anschließendem Merge, oder wenn zwei spezialisierte Agents iterativ zusammenarbeiten sollen. Für große Systeme zu unstrukturiert — besser als Schicht in einer Hierarchie einbauen.

Praktische Implementierung mit Claude Code

Agent() Tool: Subagents spawnen

Das Agent() Tool in Claude Code ist die Grundlage jeder Multi-Agent-Architektur. Ein Orchestrator-Agent startet damit Subagents:

# Orchestrator spawnt einen Worker-Subagent
Agent(
    subagent_type="general-purpose",  # oder "coder", "researcher"
    name="content-writer-1",
    prompt="""
Du bist ein Content-Writer für agentic-movers.com.

Aufgabe: Schreibe einen LinkedIn-Post über das Thema:
"Wie wir 20 KI-Agents koordinieren"

Anforderungen:
- 150-200 Wörter
- Persönlicher Ton, kein KI-Hype
- Endet mit einem Call-to-Action
- Speichere Output: /work/linkedin-post.md

Commit nach Fertigstellung mit: [content] linkedin-post: fertig
""",
    mode="bypassPermissions",  # Workers nie unterbrechen
    run_in_background=True    # Parallel ausführen
)

SendMessage: Kommunikation zwischen Agents

Für synchrone Kommunikation zwischen Agents auf gleicher Ebene — etwa wenn ein Department-Head einem anderen eine dringende Information weitergeben muss:

# Department-Head sendet Nachricht an Kollegen
SendMessage(
    recipient="strategy-lead",
    content="""[ICT → STRATEGY]
Blog-Post Deploy fertig: /blog/neuer-post-2026.html
HTTP 200 bestätigt. Bitte Social Posts triggern."""
)

In der Praxis nutzen wir SendMessage hauptsächlich für Bottom-Up Reporting: Worker melden Ergebnisse an ihren Lead, Lead meldet an den CEO.

Shared Filesystem: wie Agents Daten austauschen

Das einfachste und zuverlässigste Kommunikationsmedium: eine gemeinsame Verzeichnisstruktur. Agent A schreibt, Agent B liest — kein Protokoll nötig.

/work/
  inbox/         # Neue Tasks als JSON-Files
  processing/    # Agent hat Task übernommen
  output/        # Fertige Outputs
  errors/        # Fehlgeschlagene Tasks
  checkpoints/   # Crash-Recovery-Snapshots

Jeder Agent hat Lese-Zugriff auf /work/output/ der anderen. Kein Netzwerk, keine Message Queue nötig — ein simples Dateisystem reicht für 95% aller Use-Cases.

CLAUDE.md Hierarchie: Root → Department → Group → Worker

Die CLAUDE.md-Dateien sind das Rückgrat jeder Multi-Agent-Architektur. Claude Code lädt sie automatisch von der Root bis zum aktuellen Verzeichnis. Das ermöglicht vererbte Regeln:

/home/claude/clawd/CLAUDE.md        # Globale Unternehmensregeln
/home/claude/clawd/01_ICT/CLAUDE.md # ICT-spezifische Regeln
/home/claude/clawd/01_ICT/projects/myapp/CLAUDE.md # Projekt-Regeln

Ein Worker-Agent der in /01_ICT/projects/myapp/ arbeitet, kennt automatisch alle drei Ebenen. Globale Sicherheitsregeln, Department-Standards und Projekt-Spezifika — alles im Kontext, ohne explizit übergeben zu werden.

Kosten-Optimierung: Model-Mix Strategie

Das ist der Hebel den die meisten beim Aufbau eines Multi-Agent-Systems unterschätzen: Du kannst nicht alle Agents auf dem teuersten Modell laufen lassen. Aber du musst es auch nicht.

Die Model-Mix Strategie

Nicht jede Rolle braucht die gleiche Intelligenz. Ein Worker der JSON-Dateien umbenennt braucht kein strategisches Reasoning. Ein CEO-Agent der Unternehmensprioritäten setzt, schon:

Konkrete Beispiel-Rechnung: 8 Stunden Betrieb

Unser System betreibt täglich ca. 8 Stunden aktive Agenten-Arbeit. Hier der Kostenvergleich All-Opus vs. gemischtes System:

Der Faktor 10 kommt nicht nur vom günstigeren Modell — er kommt auch davon, dass Workers fokussierte, kurze Prompts bekommen. Kein unnötiger Kontext, kein langer Gedanken-Output nötig. Haiku für "Schreibe diese Datei um" ist vollkommen ausreichend.

Häufige Fehler beim Aufbau

Fehler 1: Zu viele Agents für zu kleine Tasks

Der Overhead eines Subagents ist real: Spawn-Zeit, Kontext-Aufbau, Kommunikation, Monitoring. Für einen Task der 30 Sekunden dauern würde, bringt ein Subagent keinen Nutzen.

# FALSCH: Subagent für trivialen Task
Agent(prompt="Erstelle einen Ordner /work/output")

# RICHTIG: Direkt ausführen
Bash(command="mkdir -p /work/output")

Faustregel: Ein Subagent lohnt sich ab etwa 5 Minuten eigenständiger Arbeit. Alles darunter direkt ausführen.

Fehler 2: Kein klares Reporting-Schema

Worker schreiben stundenlang Outputs — aber niemand weiß was fertig ist, was läuft, was gescheitert ist. Ergebnisse verschwinden im Nirvana.

# Jeder Worker muss am Ende melden:
SendMessage(recipient="department-lead", content="""
[WORKER → LEAD] ERGEBNIS: Was wurde gemacht
Details: Welche Datei, welcher Output, eventuelle Probleme
Status: OK / FAIL
Artefakt: /work/output/dateiname.ext
""")

Ohne Bottom-Up-Reporting hat der Orchestrator kein vollständiges Bild. Er kann nicht skalieren, nicht priorisieren, nicht eskalieren.

Fehler 3: Keine Crash-Sicherheit

Ein Subagent stirbt nach 45 Minuten Arbeit — ohne Checkpoints ist die gesamte Arbeit verloren. Die Regel: Commit nach jedem logischen Schritt.

# In der CLAUDE.md jedes Workers:
## Crash-Sicherheit (PFLICHT)
- Nach jeder abgeschlossenen Dateiänderung sofort committen
- Format: [worker] step-N: kurze Beschreibung
- Nie mehr als 3 Dateiänderungen ohne Commit
- Bei Fehler: Checkpoint in /work/checkpoints/ schreiben

Mit konsequentem Commit-Verhalten ist ein abgestürzter Agent nur ein kleines Ärgernis — nicht ein Datenverlust.

Fehler 4: Agents die sich gegenseitig blockieren (Deadlock)

Agent A wartet auf Output von Agent B — der wiederum auf Agent A wartet. Klassischer Deadlock. Oft entsteht er durch zirkuläre Abhängigkeiten die in der Planungsphase nicht auffielen.

# PROBLEM: Zirkuläre Abhängigkeit
# Agent A: "Ich warte auf den Report von Agent B"
# Agent B: "Ich warte auf die Daten von Agent A"

# LÖSUNG: Timeout + Eskalation in CLAUDE.md
## Deadlock-Schutz
- Wenn nach 10 Minuten kein benötigter Input vorhanden:
  1. Mit verfügbaren Daten fortfahren (Partial Output)
  2. Lead benachrichtigen: "Warte auf X, arbeite mit Y weiter"
  3. NIEMALS einfach blockiert bleiben

Wann aufhören zu skalieren (Diminishing Returns)

Mehr Agents bedeutet nicht automatisch mehr Output. Ab einem gewissen Punkt übersteigt der Koordinationsaufwand den Nutzen.

Signale dass du zu weit skaliert hast

• Der Orchestrator verbringt mehr Zeit mit Task-Management als mit strategischen Entscheidungen
• Agents warten häufiger als sie arbeiten (Bottleneck-Analyse nötig)
• Reporting-Volumen überfordert den Lead-Agent — er kann Ergebnisse nicht mehr verarbeiten
• Kosten steigen ohne proportionalen Output-Anstieg
• Fehlerquoten steigen — zu viele Agents, zu wenig Oversight

Die pragmatische Skalierungs-Regel

Füge einen neuen Agent nur hinzu wenn:

1. Ein bestehender Agent konsistent überlastet ist (>80% Auslastung)
2. Die Aufgabe klar abgrenzbar ist (eigene CLAUDE.md mit fokussierter Rolle möglich)
3. Der neue Agent unabhängig vom Hauptpfad laufen kann (run_in_background=True)

Unser eigenes System ist bei ~20 Agents stabil. Nicht weil 21 nicht möglich wäre — sondern weil 20 ausreichen um alles zu erledigen was wir erledigen wollen. Skalierung um der Skalierung willen ist Ressourcenverschwendung.

Zusammenfassung

Ein Multi-Agent-System lohnt sich wenn Tasks parallel laufen können, wenn verschiedene Expertise-Bereiche nötig sind, oder wenn ein einzelner Agent das Kontext-Limit sprengen würde. Für alles andere ist ein einzelner Agent oft die bessere Wahl.

Die wichtigsten Prinzipien für den Aufbau:

• Architektur wählen: Hierarchisch für autonome Organisationen, Pipeline für repetitive Workflows, Peer-to-Peer für Review-Loops
• Model-Mix: Opus für Strategie, Sonnet für Koordination, Haiku für Ausführung — spart 90% Kosten
• Shared Filesystem: Einfachstes und zuverlässigstes Kommunikationsmedium für Agent-Outputs
• CLAUDE.md Hierarchie: Vererbte Regeln von Root bis Worker — kein redundanter Kontext nötig
• Crash-Sicherheit: Commit nach jedem Schritt — ein abgestürzter Agent sollte höchstens 5 Minuten Arbeit kosten
• Kein Deadlock: Passives Warten ist verboten — immer eskalieren oder mit Partial Output weitermachen