Mehrere Agenten in einer Sitzung koordinieren

TL;DR

Ein Koordinator delegiert an bis zu 20 verschiedene Agenten, jeder in einem eigenen Strang mit eigenem Verlauf. Alle teilen sich Container und Dateisystem, nicht aber Kontext oder Werkzeuge. Drei Dinge gehen dabei regelmäßig schief — und eines davon ist die Richtung der Nachrichtenereignisse.

Der Aufbau

Die Aufstellung ist ein Feld auf oberster Ebene beim Anlegen des Agenten — kein Eintrag in tools:

koordinator = client.beta.agents.create(
    name="Entwicklungsleitung",
    model="claude-opus-5",
    system="Du koordinierst Entwicklungsarbeit. Delegiere Codeprüfung an den "
           "Review-Agenten und Testerstellung an den Testagenten.",
    tools=[{"type": "agent_toolset_20260401"}],
    multiagent={
        "type": "coordinator",
        "agents": [
            review_agent.id,                                     # neueste Fassung
            {"type": "agent", "id": testagent.id, "version": 4}, # feste Fassung
            {"type": "self"},                                    # Kopien seiner selbst
        ],
    },
)

session = client.beta.sessions.create(agent=koordinator.id,
                                      environment_id=umgebung.id)

An der Sitzung ändert sich nichts — die Aufstellung wird aus der Konfiguration des Koordinators aufgelöst.

Grenzen: bis zu 20 verschiedene Agenten in der Aufstellung, mehrere Kopien je Agent möglich, höchstens 25 gleichzeitige Stränge.

Nur eine Delegationsebene, und das wird durchgesetzt: Einen Agenten aufzunehmen, der selbst eine Aufstellung trägt, scheitert an der Validierung.

Was Stränge teilen und was nicht

Das ist der Punkt, an dem Erwartungen auseinandergehen. Ein Unteragent sieht nicht, was der Koordinator weiß. Wenn er etwas braucht, muss der Koordinator es in der delegierten Nachricht mitgeben — oder auf die Platte schreiben, denn das Dateisystem ist gemeinsam.

Stränge sind persistent: Der Koordinator kann einem Unteragenten später eine Anschlussfrage schicken, und dieser hat seine früheren Runden noch.

Falle 1: die Richtung der Nachrichtenereignisse

Zwei Ereignistypen tragen Nachrichten zwischen Strängen — und ihre Richtung ist relativ zu dem Strang, dessen Strom sie trägt, nicht relativ zum Koordinator.

Dieselbe delegierte Aufgabe erscheint:

• auf dem Hauptstrom als agent.thread_message_sent (der Koordinator hat gesendet)
• auf dem Strom des Unteragenten als agent.thread_message_received (dort ist sie angekommen)

Wer _received als "ein Unteragent ist fertig" liest, liegt falsch, sobald er einen Kindstrom liest. Der Fehler fällt erst auf, wenn jemand von der Sitzungsebene auf die Strangebene wechselt.

Falle 2: Freigaben kommen auf dem Hauptstrom an

Wenn ein Unteragent eine Werkzeugfreigabe oder ein Ergebnis von Ihnen braucht, wird die Anfrage auf den Hauptstrang gespiegelt — mit session_thread_id, die den Ursprung angibt. Sie müssen also nicht jeden Kindstrom offenhalten.

Beim Antworten geben Sie die Strang-Kennung mit zurück:

for event_id in stop.event_ids:
    offen = ereignisse_nach_id[event_id]
    bestaetigung = {
        "type": "user.tool_confirmation",
        "tool_use_id": event_id,       # die Ereignis-ID, kein toolu_-Wert
        "result": "allow",
    }
    if offen.session_thread_id is not None:
        bestaetigung["session_thread_id"] = offen.session_thread_id
    client.beta.sessions.events.send(session.id, events=[bestaetigung])

Zwei Details: tool_use_id ist die Ereignis-ID (typischerweise mit dem Präfix sevt_), nicht eine Werkzeugaufruf-Kennung. Und der Server leitet ohnehin über die Werkzeugkennung — die mitgegebene Strang-Kennung ist Absicherung, keine Pflicht, sollte aber gesetzt werden.

Falle 3: ein Abbruch trifft alles

user.interrupt ohne session_thread_id unterbricht jeden nicht archivierten Strang der Sitzung, einschließlich des Hauptstrangs. Das ist kein reiner Koordinator-Stopp.

Wer einen einzelnen Unteragenten stoppen will, gibt die Strang-Kennung mit.

Zum Verhalten: Trifft der Abbruch einen Kindstrang, der auf eine Aktion wartet, werden offene Werkzeugaufrufe mit einem Fehlerergebnis geschlossen, und der Strang meldet Leerlauf mit dem Grund end_turn — das Modell wird nicht erneut befragt. Bei einem bereits im Leerlauf befindlichen Strang passiert nichts.

Und beim Archivieren: Ein Strang muss dafür im Leerlauf sein, wobei "wartet auf Aktion" als Leerlauf zählt. Nur ein tatsächlich laufender Strang muss vorher unterbrochen werden.

Die Ereignisse auf dem Hauptstrom

Der Sitzungszustand fasst die Strangzustände zusammen: Läuft irgendein Strang, ist die Sitzung running.

Wollen Sie einen Unteragenten im Detail verfolgen, öffnen Sie dessen eigenen Strang-Strom. Der Hauptstrom zeigt nur eine verdichtete Sicht — Zustandswechsel und Nachrichten zwischen Strängen, nicht jeden Werkzeugaufruf des Unteragenten.

Wann sich das lohnt

Ja, wenn die Arbeit sich in unabhängige Teilaufgaben zerlegen lässt — mehrere Module gleichzeitig durchsehen, mehrere Datenquellen parallel auswerten.

Nein, wenn die Teilaufgaben voneinander abhängen. Dann kostet die Koordination mehr, als die Parallelität einbringt: Jeder Unteragent baut seinen Kontext neu auf, berichtet zurück, und der Koordinator liest den Bericht.

Ein Hinweis zum Verhalten neuerer Modelle: Claude Opus 5 delegiert bereitwilliger als seine Vorgänger. Wer für ein älteres Modell eine Anweisung zum stärkeren Delegieren im Systemprompt hatte, sollte sie entfernen — und stattdessen eine Obergrenze setzen, sonst vervielfachen sich Kosten und Laufzeit.

Häufig gestellte Fragen

Wie richte ich mehrere zusammenarbeitende Claude-Agenten ein?

Über das Feld multiagent auf oberster Ebene beim Anlegen des Koordinator-Agenten, mit einer Aufstellung von bis zu 20 Agenten. Es ist kein Eintrag in tools, und an der Sitzung ändert sich nichts — die Aufstellung wird aus der Konfiguration des Koordinators aufgelöst.

Teilen Unteragenten den Kontext des Koordinators?

Nein. Stränge teilen sich Container und Dateisystem, nicht aber Gesprächsverlauf, Modell, Systemanweisung oder Werkzeuge. Was ein Unteragent wissen muss, gehört in die delegierte Nachricht — oder auf die gemeinsame Platte.

Warum stimmt die Richtung meiner Nachrichtenereignisse nicht?

Weil sie relativ zu dem Strang ist, dessen Strom sie trägt, nicht relativ zum Koordinator. Dieselbe delegierte Aufgabe erscheint auf dem Hauptstrom als gesendet und auf dem Strom des Unteragenten als empfangen. Wer "empfangen" als "Unteragent fertig" liest, liegt beim Lesen eines Kindstroms falsch.

Muss ich für Werkzeugfreigaben jeden Strang offenhalten?

Nein. Anfragen aus Unteragenten werden auf den Hauptstrang gespiegelt und tragen die Kennung des Ursprungsstrangs. Sie antworten auf dem Hauptstrom und geben diese Kennung mit zurück; die Werkzeugkennung ist dabei die Ereignis-ID, nicht eine separate Werkzeugaufruf-Kennung.

Was passiert bei einem Abbruch ohne Strang-Angabe?

Er unterbricht jeden nicht archivierten Strang der Sitzung, einschließlich des Hauptstrangs — es ist kein reiner Koordinator-Stopp. Für einen einzelnen Unteragenten geben Sie die Strang-Kennung mit. Offene Werkzeugaufrufe werden dabei mit einem Fehlerergebnis geschlossen.

Der nächste Schritt

Klären Sie, ob Ihre Aufgabe sich in wirklich unabhängige Teile zerlegen lässt. Wenn nicht, kostet die Koordination mehr, als die Parallelität einbringt — und bei neueren Modellen brauchen Sie eher eine Obergrenze als eine Aufforderung zum Delegieren. Beim Zuschnitt helfen wir gern.