Multi Agent Workflows mit Claude erklärt

1. Was ein Multi Agent Workflow ist und warum ein Agent allein an Grenzen stößt

Ein Multi Agent Workflow beschreibt eine Softwarearchitektur, bei der mehrere KI-Agenten mit unterschiedlichen Rollen an einer gemeinsamen Aufgabe arbeiten, statt dass ein einziger Agent alle Schritte nacheinander abarbeitet. Bei Claude Code zeigt sich das konkret als Zusammenspiel aus einem koordinierenden Hauptprozess und mehreren Subagents, die jeweils einen abgegrenzten Teilauftrag erhalten. Der Unterschied zu einem klassischen Einzelagenten liegt nicht in der Modellqualität, sondern in der Aufgabenverteilung und im Umgang mit Kontext.

In der Praxis zeigt sich der Bedarf für einen Multi Agent Workflow immer dann, wenn eine Aufgabe mehrere fachlich unterschiedliche Teilschritte enthält, die jeweils eigenen Kontext benötigen. Ein Agent, der gleichzeitig Anforderungen analysiert, Code schreibt, Tests entwirft und die Dokumentation pflegt, sammelt in seinem Kontextfenster zunehmend Informationen an, die für die aktuelle Teilaufgabe irrelevant sind. Das führt zu längeren Antwortzeiten, höheren Kosten und in manchen Fällen zu einer schlechteren Qualität, weil relevante Details im wachsenden Kontext verwässern.

Ein gut entworfener Multi Agent Workflow löst dieses Problem, indem jeder Agent nur den Kontext bekommt, den er für seinen Teilauftrag wirklich braucht. Das reduziert nicht nur die Tokenmenge pro Anfrage, sondern verbessert auch die Nachvollziehbarkeit: Ein Reviewer-Agent, der nur den Diff und die Projektkonventionen sieht, liefert fokussiertere Rückmeldungen als ein Agent, der gleichzeitig noch mit der ursprünglichen Anforderungsdiskussion beschäftigt ist.

2. Architektur-Grundmuster: Orchestrator, Worker und Reviewer

Die meisten produktiven Umsetzungen eines Multi Agent Workflow folgen einem von drei wiederkehrenden Grundmustern. Im Orchestrator-Worker-Muster übernimmt ein zentraler Agent die Zerlegung der Gesamtaufgabe in Teilaufträge, verteilt diese an spezialisierte Worker-Agenten und führt die Ergebnisse anschließend zusammen. Dieses Muster eignet sich besonders gut, wenn die Teilaufgaben klar voneinander abgegrenzt und wenig voneinander abhängig sind, etwa das parallele Analysieren mehrerer Module einer Codebasis.

Im Pipeline-Muster arbeiten Agenten sequenziell, wobei das Ergebnis eines Agenten die Eingabe des nächsten bildet. Ein Multi Agent Workflow dieser Art eignet sich für Aufgaben mit klarer Reihenfolge, etwa Anforderung analysieren, Implementierung entwerfen, Code schreiben, Tests generieren. Das dritte Muster, das Reviewer-Muster, ergänzt einen bestehenden Workflow um eine unabhängige Prüfinstanz: Ein separater Agent bewertet das Ergebnis eines anderen Agenten, ohne dessen Denkprozess zu kennen, und liefert dadurch eine unvoreingenommenere Einschätzung.

In der Praxis kombinieren viele Teams alle drei Muster innerhalb eines einzigen Multi Agent Workflow: Ein Orchestrator verteilt Teilaufgaben an Worker, die Ergebnisse durchlaufen anschließend eine Pipeline-Stufe zur Konsolidierung, und ein abschließender Reviewer-Agent prüft das Gesamtergebnis, bevor es an den Menschen zurückgeht. Diese Kombination erhöht die Zuverlässigkeit deutlich, weil Fehler an mehreren Stellen abgefangen werden können.

{
  "workflow": "feature-release-multi-agent",
  "orchestrator": {
    "role": "coordinator",
    "receives": ["feature_spec", "repo_context"],
    "delegates_to": ["analysis_agent", "implementation_agent", "test_agent", "review_agent"]
  },
  "agents": [
    {
      "id": "analysis_agent",
      "role": "worker",
      "tools": ["read_file", "grep", "list_directory"],
      "context_scope": "affected_modules_only"
    },
    {
      "id": "implementation_agent",
      "role": "worker",
      "tools": ["read_file", "write_file", "run_linter"],
      "context_scope": "analysis_agent.output"
    },
    {
      "id": "test_agent",
      "role": "worker",
      "tools": ["read_file", "write_file", "run_tests"],
      "context_scope": "implementation_agent.output"
    },
    {
      "id": "review_agent",
      "role": "reviewer",
      "tools": ["read_file", "run_static_analysis"],
      "context_scope": "diff_only"
    }
  ]
}

3. Rollenverteilung: Wie Aufgaben sauber getrennt werden

Eine saubere Rollenverteilung ist die wichtigste Entwurfsentscheidung in jedem Multi Agent Workflow. Eine gute Faustregel: Ein Agent sollte genau eine fachliche Verantwortung tragen und diese vollständig, statt mehrere Verantwortungen gleichzeitig teilweise. Ein Analyse-Agent liest und versteht Code, ein Implementierungs-Agent schreibt Code, ein Test-Agent schreibt und prüft Tests, ein Review-Agent bewertet das Ergebnis. Diese Trennung verhindert, dass ein Agent gleichzeitig Autor und Prüfer seiner eigenen Arbeit ist, was die Qualität von Rückmeldungen systematisch verschlechtert.

Ein häufiger Entwurfsfehler in einem Multi Agent Workflow ist die Überlappung von Verantwortlichkeiten, etwa wenn sowohl der Implementierungs-Agent als auch der Test-Agent eigenständig Annahmen über die Anforderung treffen dürfen. Das führt zu widersprüchlichen Interpretationen, die erst spät auffallen. Die Lösung liegt darin, Annahmen und Entscheidungen zentral im Orchestrator oder in einem dedizierten Anforderungsartefakt festzuhalten, auf das alle nachgelagerten Agenten verbindlich zugreifen.

4. Kontext und Zustand zwischen Agenten teilen

Die Weitergabe von Kontext ist der technisch anspruchsvollste Teil eines Multi Agent Workflow. Der naheliegende, aber ineffiziente Ansatz besteht darin, jedem nachgelagerten Agenten den vollständigen Verlauf aller vorherigen Agenten zu übergeben. Das führt schnell zu übervollen Kontextfenstern und hohen Kosten. Der bessere Ansatz besteht darin, dass jeder Agent ein klar strukturiertes Ergebnisartefakt produziert, etwa ein JSON-Objekt mit den relevanten Erkenntnissen, das der nächste Agent gezielt konsumiert.

Für länger laufende Multi Agent Workflows hat sich ein gemeinsamer Zustandsspeicher bewährt, etwa eine Datei im Repository oder ein einfacher Schlüssel-Wert-Speicher, in dem Zwischenergebnisse abgelegt werden. Jeder Agent liest nur die für ihn relevanten Einträge und schreibt seine eigenen Ergebnisse zurück. Dieses Vorgehen entkoppelt die Agenten zeitlich, weil nicht jeder Agent synchron auf die Antwort des vorherigen warten muss, und macht den Zustand jederzeit inspizierbar, was bei der Fehlersuche entscheidend hilft.

# Simplified orchestrator for a multi agent workflow
# Each agent receives only its scoped context, not the full history

import json
from pathlib import Path

STATE_FILE = Path(".claude/workflow-state.json")

def load_state() -> dict:
    if STATE_FILE.exists():
        return json.loads(STATE_FILE.read_text())
    return {}

def save_state(state: dict) -> None:
    STATE_FILE.write_text(json.dumps(state, indent=2))

def run_agent(agent_id: str, scoped_context: dict) -> dict:
    """Placeholder: invokes the Claude API with a narrow, agent-specific context."""
    # In practice this calls client.messages.create(...) with a system
    # prompt tailored to agent_id and only scoped_context as input.
    raise NotImplementedError

def orchestrate(feature_spec: str) -> dict:
    state = load_state()
    state["analysis"] = run_agent("analysis_agent", {"spec": feature_spec})
    save_state(state)

    state["implementation"] = run_agent(
        "implementation_agent", {"analysis": state["analysis"]}
    )
    save_state(state)

    state["tests"] = run_agent(
        "test_agent", {"implementation": state["implementation"]}
    )
    save_state(state)

    state["review"] = run_agent(
        "review_agent", {"diff": state["implementation"]["diff"]}
    )
    save_state(state)
    return state

5. Werkzeuge und Berechtigungen pro Agent begrenzen

Ein Multi Agent Workflow gewinnt zusätzliche Sicherheit, wenn jeder Agent nur Zugriff auf die Werkzeuge erhält, die für seine Rolle notwendig sind. Ein Analyse-Agent braucht lesenden Dateizugriff und Suchwerkzeuge, aber keinen Schreibzugriff. Ein Implementierungs-Agent braucht Schreibzugriff, aber keinen Zugriff auf Produktionssysteme. Diese Begrenzung folgt dem Prinzip der geringsten Berechtigung und reduziert den möglichen Schaden, falls ein Agent eine unerwartete oder fehlerhafte Aktion ausführt.

In Claude Code lässt sich diese Begrenzung über die Permission-Konfiguration pro Subagent umsetzen, sodass ein Test-Agent zwar Testkommandos ausführen, aber keine Deploy-Skripte anstoßen darf. Für einen produktiven Multi Agent Workflow empfiehlt sich außerdem, kritische Werkzeuge wie das Löschen von Dateien oder das Ausführen von Shell-Befehlen mit destruktivem Potenzial grundsätzlich an eine menschliche Freigabe zu binden, unabhängig davon, welcher Agent sie anfordert.

{
  "permission_profile": {
    "analysis_agent": { "allowed": ["read_file", "grep"], "requires_approval": [] },
    "implementation_agent": { "allowed": ["read_file", "write_file"], "requires_approval": ["delete_file"] },
    "test_agent": { "allowed": ["read_file", "run_tests"], "requires_approval": [] },
    "review_agent": { "allowed": ["read_file"], "requires_approval": [] }
  },
  "always_require_human_approval": ["delete_file", "run_shell_destructive", "deploy"]
}

6. Praxisbeispiel: Ein Multi Agent Workflow für ein Feature-Release

Ein konkretes Beispiel verdeutlicht das Zusammenspiel: Für die Einführung eines neuen Filters im Produktkatalog eines Magento-Shops übernimmt der Orchestrator zunächst die Zerlegung der Anforderung. Ein Analyse-Agent liest die betroffenen Module, identifiziert relevante Klassen und Konfigurationsdateien und liefert eine strukturierte Zusammenfassung. Ein Implementierungs-Agent erhält ausschließlich diese Zusammenfassung, nicht den vollständigen Repository-Kontext, und setzt die Änderung um.

Anschließend generiert ein Test-Agent PHPUnit-Tests auf Basis des erzeugten Diffs, ohne die ursprüngliche Anforderungsdiskussion zu kennen, was ihn zwingt, sich ausschließlich am tatsächlichen Code zu orientieren. Ein abschließender Review-Agent bewertet Diff und Tests gemeinsam und markiert Abweichungen von den Projektkonventionen aus der CLAUDE.md. Dieser Multi Agent Workflow reduziert die Zeit vom Ticket bis zum reviewfertigen Pull Request spürbar, weil die Teilschritte parallel vorbereitet werden können, während der Mensch nur noch das Gesamtergebnis prüft.

#!/usr/bin/env bash
# Kick off a multi agent workflow run for a given ticket
set -euo pipefail

TICKET_ID="${1:?Usage: run-workflow.sh TICKET-123}"
WORKFLOW_DIR=".claude/workflows/feature-release"

echo "[orchestrator] Loading feature spec for ${TICKET_ID}"
claude --agent-config "${WORKFLOW_DIR}/analysis.json" \
  --input "tickets/${TICKET_ID}.md" \
  --output "state/analysis-${TICKET_ID}.json"

echo "[orchestrator] Dispatching implementation agent"
claude --agent-config "${WORKFLOW_DIR}/implementation.json" \
  --input "state/analysis-${TICKET_ID}.json" \
  --output "state/implementation-${TICKET_ID}.json"

echo "[orchestrator] Dispatching test agent"
claude --agent-config "${WORKFLOW_DIR}/test.json" \
  --input "state/implementation-${TICKET_ID}.json" \
  --output "state/tests-${TICKET_ID}.json"

echo "[orchestrator] Dispatching review agent"
claude --agent-config "${WORKFLOW_DIR}/review.json" \
  --input "state/implementation-${TICKET_ID}.json" \
  --output "state/review-${TICKET_ID}.json"

echo "[orchestrator] Multi agent workflow complete for ${TICKET_ID}"

7. Fehlerbehandlung und Wiederholungen im Multi Agent Workflow

Fehler in einem Multi Agent Workflow unterscheiden sich von Fehlern in einem einzelnen Agentenaufruf dadurch, dass sie sich über mehrere Stufen fortpflanzen können. Liefert der Analyse-Agent eine unvollständige Zusammenfassung, baut der Implementierungs-Agent darauf eine fehlerhafte Lösung auf, die wiederum vom Test-Agent mit passenden, aber irrelevanten Tests abgesichert wird. Ohne Gegenmaßnahmen bestätigen sich Fehler in einem solchen Workflow gegenseitig, statt aufzufallen.

Eine wirksame Gegenmaßnahme ist die Einführung von Validierungspunkten zwischen den Stufen: Nach der Analyse prüft eine einfache Regel oder ein zweiter, unabhängiger Agent, ob die Zusammenfassung plausibel und vollständig ist, bevor sie weitergegeben wird. Für Wiederholungen empfiehlt sich eine begrenzte Anzahl an Versuchen pro Stufe mit klar definiertem Abbruchkriterium, damit ein fehlschlagender Agent nicht endlos wiederholt wird, sondern nach einer festen Anzahl an Versuchen an einen Menschen eskaliert.

# Retry with bounded attempts and escalation to a human after the limit

MAX_RETRIES = 3

def run_stage_with_retry(stage_id: str, stage_input: dict) -> dict:
    for attempt in range(1, MAX_RETRIES + 1):
        result = run_agent(stage_id, stage_input)
        if validate_result(stage_id, result):
            return result
        print(f"[workflow] {stage_id} failed validation, attempt {attempt}/{MAX_RETRIES}")

    escalate_to_human(stage_id, stage_input, reason="max_retries_exceeded")
    raise RuntimeError(f"Stage {stage_id} failed after {MAX_RETRIES} attempts")

8. Beobachtbarkeit: Logging über mehrere Agenten hinweg

Ohne strukturiertes Logging wird ein Multi Agent Workflow schnell zur Blackbox, in der niemand mehr nachvollziehen kann, welcher Agent welche Entscheidung getroffen hat. Jeder Agentenaufruf sollte daher mit einer eindeutigen Workflow-ID, einem Zeitstempel, der verwendeten Rolle und den Ein- und Ausgaben protokolliert werden. Diese Protokolle erlauben es im Nachhinein, einen fehlerhaften Lauf Schritt für Schritt zu rekonstruieren, statt nur das Endergebnis zu sehen.

Für Teams, die einen Multi Agent Workflow produktiv einsetzen, lohnt sich zusätzlich ein Dashboard, das Laufzeit, Tokenverbrauch und Erfolgsquote pro Agentenrolle aggregiert. So lässt sich frühzeitig erkennen, wenn etwa der Review-Agent überdurchschnittlich oft ablehnt, was auf ein Problem in der vorgelagerten Implementierungsstufe hindeuten kann, statt auf ein Problem der Reviewstufe selbst.

9. Single Agent gegen Multi Agent Workflow im Vergleich

Die folgende Übersicht fasst zusammen, wann ein einzelner Agent ausreicht und wann ein Multi Agent Workflow die bessere Wahl ist. Die Entscheidung hängt weniger von der Komplexität der Aufgabe an sich ab, sondern davon, wie klar sie sich in unabhängige Teilaufgaben zerlegen lässt.

Aus dieser Gegenüberstellung folgt keine pauschale Empfehlung für einen Multi Agent Workflow, sondern eine klare Bedingung: Sobald sich eine Aufgabe in unabhängige, fachlich unterschiedliche Teilschritte zerlegen lässt, überwiegen die Vorteile der Aufteilung. Bleibt die Aufgabe eng zusammenhängend und erfordert durchgängig denselben Kontext, bleibt ein einzelner Agent die effizientere Wahl.

10. Zusammenfassung

Ein Multi Agent Workflow löst genau dann ein reales Problem, wenn eine Aufgabe zu viele fachlich unterschiedliche Teilschritte enthält, um sie effizient von einem einzigen Agenten bearbeiten zu lassen. Orchestrator, Worker und Reviewer sind die drei wiederkehrenden Rollen, die sich in fast jeder produktiven Umsetzung finden. Entscheidend für die Qualität ist eine klare Rollenverteilung, ein schlanker, gezielt weitergegebener Kontext sowie begrenzte Werkzeugrechte pro Agent.

Fehlerbehandlung und Beobachtbarkeit dürfen dabei nicht als nachträgliche Ergänzung betrachtet werden, sondern gehören von Anfang an in den Entwurf eines Multi Agent Workflow. Wer Validierungspunkte zwischen den Stufen einbaut und jeden Agentenaufruf strukturiert protokolliert, erkennt Fehler früh und kann den Workflow gezielt verbessern, statt bei jedem Problem von vorne zu beginnen.

11. FAQ: Multi Agent Workflows mit Claude