Wie man ein Multi-Agent-System baut: Praxisleitfaden zum supervisor-Muster

Sobald Sie das Konzept der „Koordination mehrerer KIs“ in Was ist ein Multi-Agent-System? verstanden haben, lautet die nächste Frage: Wie baut man so etwas konkret. Dieser Artikel führt anhand des De-facto-Standards von 2026 – des supervisor-Musters – Anfänger durch einen praxisorientierten 5-Schritte-Prozess.

Bevor wir über Frameworks reden, das wichtigste Prinzip vorweg: „Bauen Sie zuerst mit einem einzelnen Agenten und fügen Sie erst dann – minimal – weitere hinzu, wenn Sie an eine Grenze stoßen.“ Gleich mit vielen Agenten zu starten, ist meist Over-Engineering. In der zweiten Hälfte finden Sie minimalen, lesbaren Code, der sich an die offizielle Dokumentation des Claude Agent SDK und des OpenAI Agents SDK hält, dazu, wie man Rollen aufteilt, und die Fehlschläge, die tatsächlich passieren. Dieselbe Logik gilt, wenn Sie Tools über MCP anbinden.

Hinweis: Der Code folgt der offiziellen Dokumentation des Claude Agent SDK und des OpenAI Agents SDK (geprüft am 4. Oktober 2026). Diese SDKs ändern sich schnell; prüfen Sie die Parameternamen vor dem Ausführen in der jeweiligen offiziellen Dokumentation. Jede Zahl im Artikel nennt ihre Quelle.

1. Vor dem Bau: Braucht es wirklich Multi?

Die erste Hürde ist nicht technischer Natur – sie ist eine Entscheidung. Multi-Agent ist mächtig, hilft aber nicht bei jeder Aufgabe. Trifft keiner der folgenden Punkte zu, bauen Sie zuerst mit einem einzelnen Agenten.

Umgekehrt kostet Multi-Agent bei einem geradlinigen Ablauf, wie schon im vorigen Artikel erwähnt. In einer Studie von Google Research (veröffentlicht im Januar 2026, 180 Konfigurationen verglichen) schnitten alle getesteten Multi-Agent-Varianten bei einer Aufgabe mit streng sequenziellem Schlussfolgern (PlanCraft) um 39–70 % schlechter ab als ein einzelner Agent. Auch die Kosten steigen: In seiner Beschreibung des eigenen Recherche-Agenten berichtet Anthropic, dass Agenten etwa 4-mal so viele Tokens verbrauchen wie ein Chat und Multi-Agent-Systeme etwa 15-mal so viele. Gehen Sie davon aus, dass mehr Agenten nicht mehr Intelligenz bedeuten.

2. Die Grundform: das supervisor-Muster

Wenn Sie unsicher sind, welches Muster Sie bauen sollen, ist der Start mit dem supervisor-Muster die sichere Wahl. Die wichtigsten SDKs dokumentieren es als Grundmuster. Im Claude Agent SDK ruft der Hauptagent Subagenten über das Tool Agent auf; im OpenAI Agents SDK entspricht dem „agents as tools“: Ein Manager-Agent ruft spezialisierte Agenten wie Tools auf.

Die Mechanik ist einfach. Der supervisor empfängt die Gesamtaufgabe, zerlegt sie in Teilaufgaben, delegiert sie an spezialisierte worker und fasst die Ergebnisse zusammen. Der supervisor muss nicht wissen, wie ein worker seine Arbeit erledigt – nur welchen worker er aufruft und in welchem Ausgabeformat. Das Fachwissen sitzt in den workern.

Achtung: Im OpenAI Agents SDK bedeutet ein Handoff etwas Engeres als die allgemeine Übergabe aus Schritt 4: Ein Triage-Agent übergibt das Gespräch selbst an einen Spezialisten, der danach direkt dem Nutzer antwortet. Es bleibt kein supervisor übrig, behandeln Sie es also als eigenes Muster (wann was passt, steht in Abschnitt 6).

3. In 5 Schritten bauen

Stellen Sie ein minimales supervisor-Setup in fünf Schritten zusammen. Die Faustregel: Beginnen Sie mit 2-3 workern und fügen Sie nur dann weitere hinzu, wenn die Messung es rechtfertigt.

4. Minimaler Code ①: Claude Agent SDK (Python)

Zuerst bauen wir mit dem Claude Agent SDK von Anthropic einen supervisor und zwei worker (einen Rechercheur und einen Prüfer). Vorbereitung: nur pip install claude-agent-sdk und die Umgebungsvariable ANTHROPIC_API_KEY (offizieller Quickstart; das SDK lädt .env-Dateien nicht automatisch). Der Code folgt der offiziellen Subagents-Seite. Zum SDK insgesamt siehe unseren Leitfaden zum Claude Agent SDK.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage

options = ClaudeAgentOptions(
    model="claude-opus-5-5",  # der supervisor (Hauptagent)
    system_prompt=(
        "You coordinate a research report. Delegate research to researcher and fact-checking "
        "to reviewer, and write the final text yourself. When delegating, always state the "
        "goal, the output format, and the scope."
    ),
    allowed_tools=["Agent", "WebSearch", "WebFetch"],  # Tools, die ohne Rückfrage laufen
    agents={
        "researcher": AgentDefinition(
            description="Gathers primary sources. Use when facts or figures are needed.",
            prompt="Find primary sources for the question and return bullet points with source URLs. Never fill gaps with guesses.",
            tools=["WebSearch", "WebFetch"],  # die einzigen Tools dieser Rolle
            model="sonnet",
            maxTurns=15,
        ),
        "reviewer": AgentDefinition(
            description="Fact-checks drafts. Always use before finalizing text.",
            prompt="Check each claim in the draft against its source and list every sentence that lacks support.",
            tools=["WebFetch"],
            model="sonnet",
            maxTurns=10,
        ),
    },
    max_turns=30,         # Obergrenze der Durchläufe für den ganzen Lauf
    max_budget_usd=5.0,   # Ausgabenobergrenze (Schätzung des SDK)
    env={"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"},  # worker erzeugen keine eigenen Subagenten
)


async def main():
    try:
        async for message in query(
            prompt="Find three official statistics on workplace use of generative AI and write a short report",
            options=options,
        ):
            if isinstance(message, ResultMessage):
                print(message.subtype, message.total_cost_usd)
                print(message.result)
    except Exception as error:
        print(f"Stopped early: {error}")  # auch das Erreichen einer Obergrenze landet hier


asyncio.run(main())

Fünf Punkte, auf die es ankommt:

• worker stehen in agents als AgentDefinition-Einträge. Der supervisor liest die description jedes workers, um zu entscheiden, wen er wann aufruft. Beschreiben Sie also konkret, was die Rolle tut und wann sie gebraucht wird.
• Wer tools auflistet, gibt der Rolle nur diese Tools. Deshalb hat der Prüfer keine Schreib-Tools. allowed_tools dagegen listet Tools, die ohne Berechtigungsabfrage laufen; es schränkt nichts ein (offizielle Python-Referenz).
• Setzen Sie Obergrenzen an drei Stellen. Ein maxTurns pro Rolle, ein globales max_turns und eine Ausgabengrenze mit max_budget_usd. Wird eine globale Grenze erreicht, wird der Ergebnis-Subtyp zu error_max_turns oder error_max_budget_usd, und der Lauf stoppt (Doku zur Agentenschleife).
• Unterbinden Sie die Verschachtelung. Subagenten können eigene Subagenten erzeugen. Steht die Umgebungsvariable CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH auf 1, erledigen die worker die Arbeit selbst. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (Standard 20) begrenzt, wie viele gleichzeitig laufen.
• Die Felder von AgentDefinition sind in camelCase. Wer max_turns statt maxTurns schreibt, bekommt schon beim Erzeugen einen TypeError (offizieller Hinweis). Der supervisor nutzt das aktuelle claude-opus-5-5, die worker den Alias "sonnet" – so läuft der Code auch nach einer neuen Version weiter.

Die offizielle Dokumentation weist darauf hin, dass Opus 5 bereitwilliger an Subagenten delegiert als frühere Modelle, und empfiehlt zusätzlich zu Anweisungen im Prompt Grenzen für Tiefe, Parallelität und Ausgaben. Eine Anweisung ändert nur, wie Claude um Hilfe bittet; zuverlässig stoppen einen Lauf nur die Grenzen.

5. Minimaler Code ②: OpenAI Agents SDK (Python)

Im Agents SDK von OpenAI entsteht dieselbe Form, indem man spezialisierte Agenten mit as_tool() zu Tools macht und sie den tools des supervisors übergibt (offizielles „agents as tools“). Vorbereitung: pip install openai-agents und die Umgebungsvariable OPENAI_API_KEY (offizieller Quickstart). Lassen Sie model weg, nutzt das SDK sein Standardmodell; dieses ändert sich zwischen SDK-Versionen, prüfen Sie es daher auf der Models-Seite.

import asyncio
from agents import Agent, Runner, WebSearchTool

researcher = Agent(
    name="Researcher",
    instructions="Find primary sources for the question and return bullet points with source URLs. Never fill gaps with guesses.",
    tools=[WebSearchTool()],
)
reviewer = Agent(
    name="Reviewer",
    instructions="Check each claim in the draft you receive against its source and list every sentence that lacks support.",
)

manager = Agent(
    name="Manager",
    instructions=(
        "You coordinate a research report. Delegate research to research and fact-checking "
        "to review, and write the final text yourself."
    ),
    tools=[
        researcher.as_tool(
            tool_name="research",
            tool_description="Gather primary sources with citations",
            max_turns=10,  # Obergrenze der Durchläufe dieser Rolle
        ),
        reviewer.as_tool(
            tool_name="review",
            tool_description="Fact-check a draft",
        ),
    ],
)


async def main():
    result = await Runner.run(
        manager,
        input="Find three official statistics on workplace use of generative AI and write a short report",
        max_turns=10,  # bei Überschreitung: MaxTurnsExceeded
    )
    print(result.final_output)


asyncio.run(main())

Was beide SDKs gemeinsam haben und worin sie sich unterscheiden:

• worker kennen das Gespräch des Elternagenten nicht. Ein über as_tool() aufgerufener Agent übernimmt den Gesprächszustand des Elternlaufs nicht automatisch (offizielle Doku). Im Claude Agent SDK ist es genauso: Ein Subagent erhält vom Elternagenten nur den Prompt des Agent-Tools. Schreiben Sie Dateipfade, Fehlermeldungen und getroffene Entscheidungen direkt in den Auftrag.
• Die Obergrenze ist Runner.run(..., max_turns=). Wird sie überschritten, wird MaxTurnsExceeded ausgelöst. Mit error_handlers={"max_turns": ...} können Sie statt einer Ausnahme eine kontrollierte Antwort zurückgeben (Running agents).
• Mit Handoffs schriebe man Agent(..., handoffs=[billing_agent, refund_agent]). Der empfangende Agent übernimmt das Gespräch und sieht standardmäßig den gesamten bisherigen Verlauf. Soll er bestimmte Informationen nicht bekommen, filtern Sie sie mit einem input_filter.

6. Rollen aufteilen: gute und schlechte Schnitte

Der Schnitt ist schwieriger als der Code. Anthropic schreibt, dass jeder Subagent ein Ziel, ein Ausgabeformat, Hinweise zu den zu nutzenden Tools und Quellen und klare Aufgabengrenzen braucht (dieselbe Beschreibung). Hier stehen Schnitte, die diese vier Bedingungen erfüllen, neben solchen, die es nicht tun.

Dieselbe Beschreibung liefert einen Richtwert für die Zahl der Agenten. Anthropic schrieb Skalierungsregeln in den Prompt seines Recherche-supervisors: Einfache Faktensuche braucht 1 Agenten mit 3–10 Tool-Aufrufen, direkte Vergleiche 2–4 Subagenten mit je 10–15 Aufrufen, komplexe Recherchen können mehr als 10 Subagenten nutzen. Das sind Zahlen für Recherchearbeit; beginnen Sie bei Ihrer eigenen Aufgabe am unteren Ende und erweitern Sie erst nach dem Messen.

Für die Wahl zwischen supervisor und Handoff gibt die OpenAI-Dokumentation ein klares Kriterium. Soll ein Agent die Endantwort verantworten oder sollen die Ergebnisse mehrerer Spezialisten zusammengeführt werden, nehmen Sie den supervisor (agents as tools). Ist das Weiterleiten selbst die Aufgabe und soll der gewählte Spezialist dem Nutzer direkt antworten (etwa beim Sortieren von Support-Anfragen), nehmen Sie einen Handoff. Beides lässt sich kombinieren.

7. Häufige Fehlschläge und Lösungen

Wo man stolpert, ist vorhersehbar. Unten stehen Fehlschläge, die laut Anthropic mit seinem Recherche-Agenten tatsächlich auftraten, sowie die Punkte, vor denen die offizielle Dokumentation beider SDKs warnt.

Die gemeinsame Lektion: „Prompts, Tool-Design und das eval-Harness entscheiden mehr über den Erfolg als das Framework.“ Auch die OpenAI-Dokumentation nennt Investitionen in gute Prompts, Überwachen und Nachbessern, spezialisierte Agenten und evals. Statt einer auffälligen Architektur ist am Ende die Disziplin am schnellsten, klein zu bauen, zu messen und nur dann zu erweitern, wenn es sich lohnt.

Fazit

Ein Multi-Agent-System zu bauen ist nicht beängstigend, wenn Sie mit dem supervisor-Muster aus einem minimalen Setup beginnen. Fassen wir zusammen.

„Klein bauen, messen, dann erweitern.“ Halten Sie diese Disziplin ein, und ein Multi-Agent-System wird zu einem leistungsstarken Partner für komplexe Arbeit. Zum Konzept siehe Was ist ein Multi-Agent-System?; zum Bau eines einzelnen Wie man einen KI-Agenten baut.

FAQ