Multiagenten-Orchestrierung

„Multiagent orchestration“ (Multiagenten-Orchestrierung) ermöglicht es einem Agenten, sich mit anderen zu koordinieren, um komplexe Arbeit zu erledigen. Agenten können parallel mit ihrem eigenen isolierten Kontext agieren, was die Ausgabequalität verbessert und auch die Zeit bis zur Fertigstellung verkürzen kann.

Nicht sicher, ob ein Multiagenten-Setup zu deinem Problem passt? Siehe wann man Multiagentensysteme einsetzen sollte (und wann nicht).

So funktioniert es

Alle Agenten teilen sich dieselbe Sandbox, dasselbe Dateisystem und dieselben Vault-Anmeldedaten, aber jeder Agent läuft in seinem eigenen Session-Thread, einem kontextisolierten Event-Stream mit eigenem Gesprächsverlauf. Der Koordinator meldet Aktivitäten im primären Thread (der identisch mit dem Event-Stream auf Session-Ebene ist); zusätzliche Threads werden zur Laufzeit erzeugt, wenn der Koordinator Arbeit delegiert.

Threads sind persistent: Der Koordinator kann eine Folgenachricht an einen Agenten senden, den er zuvor aufgerufen hat, und dieser Agent behält alles aus seinen vorherigen Turns.

Jeder Agent verwendet seine eigene Konfiguration: Modell, System-Prompt, Tools, MCP-Server und Skills. Überschreibungen der Agentenkonfiguration auf Session-Ebene sind die Ausnahme; sie gelten für den Koordinator und seine self-Kopien. Tools, MCP-Server und Kontext werden nicht geteilt.

Was delegiert werden sollte

Multiagenten-Koordination eignet sich am besten für komplexe Aufgaben, die entweder Arbeit über verschiedene Oberflächen hinweg erfordern oder bei denen mehrere klar abgegrenzte Aufgaben zu einem Gesamtziel beitragen.

Muster, die gut funktionieren:

• Parallelisierung: Verteile unabhängige Teilaufgaben gleichzeitig (Durchsuchen mehrerer Quellen, Analysieren separater Dateien) und lass den Koordinator die Ergebnisse zusammenführen.
• Spezialisierung: Leite an Agenten mit domänenspezifischen System-Prompts und Tools weiter, etwa einen Sicherheitsagenten oder einen Dokumentationsagenten, anstatt einen einzelnen Agenten mit jeder Fähigkeit auszustatten.
• Eskalation: Konsultiere einen leistungsfähigeren Agenten oder ein leistungsfähigeres Modell für eine Teilmenge komplexer Teilaufgaben.

Den Koordinator konfigurieren

Setze beim Definieren deines Agenten multiagent, um die Liste (Roster) der Agenten zu deklarieren, an die der Koordinator delegieren kann:

ant beta:agents create < coordinator.agent.yaml

name: Engineering Lead
model: claude-opus-5
system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.
tools:
  - type: agent_toolset_20260401
multiagent:
  type: coordinator
  agents:
    - type: agent
      id: $REVIEWER_AGENT_ID # replace before running command
    - type: agent
      id: $TEST_WRITER_AGENT_ID # replace before running command

multiagent.agents akzeptiert jede der folgenden Formen:

• {"type": "agent", "id": agent.id} referenziert einen zuvor erstellten agent per ID. Wenn keine version angegeben ist, wird die Referenz auf die neueste Version dieses Agenten zum Zeitpunkt der Erstellung des Koordinators festgelegt.
• {"type": "agent", "id": agent.id, "version": agent.version} legt eine bestimmte Agentenversion fest.
• {"type": "self"} erlaubt dem Koordinator, Kopien von sich selbst zu erzeugen. Wenn die Session mit Überschreibungen der Agentenkonfiguration erstellt wurde, gelten diese Überschreibungen auch für diese Kopien; per ID referenzierte Roster-Einträge bleiben unberührt.
• {"type": "advisor", "model": "<model id>"} gibt dem primären Thread der Session einen Advisor, den er mitten im Turn konsultieren kann. Höchstens ein Advisor-Eintrag pro Roster. Siehe Der Session einen Advisor geben.

Die Konfiguration des Koordinators, einschließlich seines multiagent.agents-Rosters, wird als Snapshot festgehalten, wenn der Koordinator erstellt oder aktualisiert wird. Referenzierte Agenten bleiben auf die zu diesem Zeitpunkt aufgelösten Versionen festgelegt und übernehmen spätere Aktualisierungen ihrer Definitionen nicht automatisch. Um an eine neuere Version eines referenzierten Agenten zu delegieren, aktualisiere den Koordinator, sodass sein Roster diese Version referenziert.

Der Koordinator kann nur an eine Ebene von Agenten delegieren; das Referenzieren eines Agenten, der ein eigenes multiagent.agents-Roster hat, lässt die Erstellungs- oder Aktualisierungsanfrage mit einem Validierungsfehler fehlschlagen. Maximal 20 eindeutige Agenten können in multiagent.agents aufgeführt werden, aber der Koordinator kann mehrere Kopien jedes Agenten aufrufen.

Wenn Agenten eine Inferenz-Geografie festlegen (model.inference_geo in der Agentendefinition), müssen die Festlegung des Koordinators und die jedes Roster-Mitglieds entweder alle auf denselben Wert gesetzt oder alle nicht gesetzt sein. Ein nicht übereinstimmendes Roster wird mit einem 400-Validierungsfehler abgelehnt, sowohl beim Speichern des Agenten als auch wenn eine Überschreibung bei der Session-Erstellung eine der Festlegungen ändert.

Der Session einen Advisor geben

Ein Advisor-Eintrag in multiagent.agents gibt dem primären Thread der Session einen Advisor (Berater): ein Modell, das er mitten im Turn für strategische Orientierung konsultieren kann, etwa um einen Ansatz zu planen, aus einer Sackgasse herauszukommen oder Arbeit vor dem Abschluss zu überprüfen. Der Eintrag hat genau zwei Felder, type und model:

curl -fsS https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Backend engineer",
    "model": "claude-sonnet-5",
    "system": "You implement backend features end to end. Consult the advisor before major backend design decisions.",
    "multiagent": {
      "type": "coordinator",
      "agents": [
        {"type": "advisor", "model": "claude-opus-5"}
      ]
    }
  }'

Ein Roster kann höchstens einen Advisor-Eintrag enthalten, neben beliebigen anderen Roster-Formen. Der Eintrag belegt den reservierten Roster-Namen anthropic.advisor: Ein Roster, das sowohl einen Advisor-Eintrag als auch ein Mitglied mit dem wörtlichen Namen anthropic.advisor aufführt, wird mit einem 400-Validierungsfehler abgelehnt. In Antworten wird der Advisor-Eintrag unabhängig von der Position, an der er übermittelt wurde, als letzter im Roster zurückgegeben.

Das Advisor-Modell muss eine Mindestanforderung an Leistungsfähigkeit erfüllen, und das eigene Modell des Agenten darf nicht leistungsfähiger sein als sein Advisor; Modelle gleicher Leistungsfähigkeit können gepaart werden. Eine ungültige Paarung wird beim Speichern des Agenten mit einem 400-Validierungsfehler abgelehnt. Gültige Paarungen folgen der Tabelle zur Modellkompatibilität des Advisor-Tools.

Der Advisor ist auch als Server-Tool in der Messages API verfügbar. Die Managed-Agents-Oberfläche unterscheidet sich in Konfiguration und Zustellung: Der Roster-Eintrag hat keine Felder max_uses, max_tokens oder caching, und Ratschläge kommen über Thread-Events statt über advisor_tool_result-Blöcke an.

Wie Konsultationen funktionieren

Jede Konsultation läuft als von der Plattform erzeugter Thread namens anthropic.advisor, der sich selbst beendet, wenn die Konsultation abgeschlossen ist, und der Ratschlag wird dem primären Thread als agent.thread_message_received-Event zugestellt. Eine Konsultation gibt die Standard-Thread-Events aus, identifiziert durch den reservierten Namen anthropic.advisor (die Thread-Lebenszyklus-Events tragen ihn als agent_name, und die Zustellung des Ratschlags trägt ihn als from_agent_name), typischerweise in dieser Reihenfolge:

1. session.thread_created
2. session.thread_status_running
3. agent.thread_message_received (der Ratschlag)
4. session.thread_status_idle (stop_reason: end_turn)
5. session.thread_status_terminated

Für eine Konsultation werden keine agent.tool_use-Events ausgegeben, und im Event-Stream der Session erscheint kein agent.thread_message_sent-Event, da die Konsultationseingabe von der Plattform zusammengestellt und nicht vom Agenten gesendet wird. Wenn du die eigenen Events des Advisor-Threads auflistest, erscheint der Ratschlag dort ebenfalls als agent.thread_message_sent-Event. Es ist nicht garantiert, dass die Zustellung des Ratschlags (Event 3) vor den Idle- und Terminated-Events des Advisor-Threads eintrifft; behandle diese also nicht als Signal dafür, dass der Ratschlag bereits zugestellt wurde.

Ob dein Client den Ratschlag lesen kann, hängt von der Richtlinie des Advisor-Modells ab und spiegelt die Aufteilung der Ergebnisvarianten beim Advisor-Tool der Messages API wider. Advisor-Modelle, die dort Klartext-Ergebnisse zurückgeben, liefern den Ratschlag hier als lesbaren Textinhalt; Advisor-Modelle, die dort geschwärzte Ergebnisse zurückgeben, liefern auf jeder Client-Oberfläche einen [{"type": "redacted"}]-Platzhalter als Nachrichteninhalt, während der Agent selbst serverseitig weiterhin den vollständigen Ratschlag liest. Im vorangehenden Beispiel ist Claude Opus 5 ein Advisor mit geschwärzten Ergebnissen, sodass dein Client den Platzhalter sieht, während der Agent den vollständigen Ratschlag liest; wähle stattdessen Claude Opus 4.8 als Advisor, wenn der Ratschlag im Event-Stream lesbar sein soll. Das Denken des Advisors wird nie offengelegt. Clients können selbst keine redacted-Blöcke senden; ein Event, das einen enthält, wird mit einem 400-Validierungsfehler abgelehnt.

Eine fehlgeschlagene oder unterbrochene Konsultation lässt den Turn des Agenten nie fehlschlagen: Der Agent fährt nach einem allgemeinen Hinweis, dass die Konsultation fehlgeschlagen ist, fort. Ein user.interrupt auf Session-Ebene während einer Konsultation beendet den Advisor-Thread, ohne dass ein Ratschlag zugestellt wird; ein user.interrupt mit der session_thread_id des Advisor-Threads bricht nur diese Konsultation ab.

Advisor-Threads

Der Advisor ist kein Roster-Agent: Er ist für das list_agents-Tool des Koordinators unsichtbar, er kann nicht mit send_to_agent angeschrieben werden, und nur der primäre Thread der Session kann ihn konsultieren. Roster-Agenten können das nicht.

Advisor-Threads sind vom Limit für gleichzeitige Threads ausgenommen. Sie erscheinen in der Thread-Liste der Session mit agent auf die Advisor-Form genau wie konfiguriert gesetzt ({"type": "advisor", "model": ...}) und parent_thread_id auf den primären Thread gesetzt.

Prompt-Caching auf Seiten des Advisors erfolgt automatisch; es gibt nichts zu konfigurieren. Konsultationen werden zu den Tarifen des Advisor-Modells abgerechnet, und ihre Token erscheinen in der Nutzung des Advisor-Threads und in den Nutzungssummen der Session.

Den Advisor entfernen

Um den Advisor zu entfernen, aktualisiere den Agenten mit einem Roster, das den Advisor-Eintrag nicht mehr enthält. Wenn der Advisor der einzige Eintrag im Roster ist, leere das Roster vollständig, indem du "multiagent": null setzt.

Die Session erstellen

Erstelle eine Session, die den Koordinator referenziert. Der Koordinator delegiert nach Bedarf an die Agenten in seinem Roster.

session = client.beta.sessions.create(
    agent=coordinator.id,
    environment_id=environment.id,
)

Agenten mit MCP-Servern verbinden

MCP-Server sind agentenbezogen (jede Agentendefinition deklariert ihre eigenen Server und Tools), während Vault-Anmeldedaten sessionbezogen sind (bei der Session-Erstellung übergebene vault_ids gelten für jeden Thread). Zwei Konsequenzen für deine Integration:

• Um MCP-Server zu authentifizieren, füge für jeden MCP-Server, der über alle Agenten hinweg verwendet wird, Vault-Anmeldedaten hinzu.
• Um den Zugriff eines Agenten einzuschränken, deklariere in seiner Agentendefinition nur die Server, die er benötigt.

Überschreibungen der Agentenkonfiguration bei der Session-Erstellung können die MCP-Server des Koordinators und die seiner self-Kopien ersetzen.

research_agent = client.beta.agents.create(
    name="researcher",
    model="claude-haiku-4-5",
    mcp_servers=[
        {"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"},
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "github"}],
)

coordinator = client.beta.agents.create(
    name="coordinator",
    model="claude-opus-5",
    tools=[{"type": "agent_toolset_20260401"}],
    multiagent={
        "type": "coordinator",
        "agents": [{"type": "agent", "id": research_agent.id}],
    },
)

session = client.beta.sessions.create(
    agent=coordinator.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)
print(session.id)

In diesem Beispiel deklariert nur der Researcher den GitHub-MCP-Server, sodass der Koordinator keinen Zugriff hat. Die vault_ids der Session stellen dem Thread des Researchers die GitHub-Anmeldedaten bereit.

Threads

Der Event-Stream auf Session-Ebene (/v1/sessions/{session_id}/events/stream) gilt als der primäre Thread und enthält eine verdichtete Ansicht aller Aktivitäten über alle Threads hinweg. Du siehst nicht die vollständige Aktivität der Subagenten, aber du siehst den Beginn und das Ende ihrer Arbeit sowie blockierende Events wie Tool-Berechtigungsanfragen.

Session-Threads sind der Ort, an dem du in die Aktivität eines bestimmten Agenten eintauchst.

Der status der Session ist eine Aggregation aller Agentenaktivitäten; wenn mindestens ein Thread running ist, ist der Gesamtstatus der Session ebenfalls running.

Ein Session-Budget ist eine einzige gemeinsame Obergrenze über alle Threads einer Session hinweg. Wenn die Obergrenze erreicht wird, pausieren Threads unabhängig voneinander, und die Kosten jedes Threads werden nach dem jeweils bedienten Modell des Threads berechnet.

for thread in client.beta.sessions.threads.list(session.id):
    print(f"[{thread.agent.name}] {thread.status}")

Events des primären Threads

Diese Events machen Multiagenten-Aktivität im primären Thread unter /v1/sessions/{session_id}/events/stream sichtbar. Events mit Nachrichtenrichtung sind relativ zu dem Thread benannt, in dessen Stream sie erscheinen: agent.thread_message_received bedeutet, dass in diesem Thread eine Nachricht von einem anderen Thread eingegangen ist, und agent.thread_message_sent bedeutet, dass dieser Thread eine gesendet hat. Die Aufgabe, die der Koordinator delegiert, kommt beispielsweise im eigenen Stream des Kind-Threads als agent.thread_message_received-Event an.

Advisor-Konsultationen geben dieselben Thread-Events unter dem reservierten Namen anthropic.advisor aus (als agent_name bei den Thread-Lebenszyklus-Events und als from_agent_name bei der Zustellung des Ratschlags); siehe Der Session einen Advisor geben für die Abfolge.

Events von Session-Threads

Kritische Events werden an den primären Thread weitergeleitet. Dennoch möchtest du vielleicht das Reasoning und die Tool-Aufrufe eines bestimmten Agenten untersuchen. Streame oder liste dazu die Events des zugehörigen Session-Threads auf.

Jeder Session-Thread hat seinen eigenen Event-Stream unter /v1/sessions/{session_id}/threads/{thread_id}/stream, und er akzeptiert denselben event_deltas[]-Parameter wie der Stream auf Session-Ebene, sodass du den Text eines Subagenten in der Vorschau sehen kannst, während das Modell ihn generiert. Eine Verbindung zeigt nur Vorschauen des Threads, den sie liest: Die Vorschauen eines Kind-Threads erscheinen nie im Stream auf Session-Ebene; um einen Subagenten live zu beobachten, öffne also seinen eigenen Thread-Stream. Siehe Vorschau von Session-Thread-Events zum Aktivieren, Akkumulieren und Abgleichen von Vorschauen.

with client.beta.sessions.threads.events.stream(
    thread.id,
    session_id=session.id,
) as stream:
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "session.thread_status_idle":
                break

Tool-Berechtigungen und benutzerdefinierte Tools

Wenn ein Subagent etwas von deinem Client benötigt, etwa die Berechtigung, ein always_ask-Tool auszuführen, oder das Ergebnis eines benutzerdefinierten Tools, wird das Event in den primären Thread übernommen, wobei session_thread_id den ursprünglichen Session-Thread identifiziert.

{
  "type": "session.thread_status_idle",
  "id": "sevt_01ABC...",
  "session_thread_id": "sth_01DEF...",
  "agent_name": "code-reviewer",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["sevt_01XYZ..."]
  }
}

Sende user.tool_confirmation (mit tool_use_id) oder user.custom_tool_result (mit custom_tool_use_id); der Server leitet die Antwort automatisch an den richtigen Thread weiter.

Das folgende Beispiel erweitert den Handler für Tool-Bestätigungen, um Antworten weiterzuleiten. Dasselbe Muster gilt für user.custom_tool_result.

for event_id in stop.event_ids:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.tool_confirmation",
                "tool_use_id": event_id,
                "result": "allow",
            }
        ],
    )