Multiagent-Orchestrierung

Multiagent-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 Multiagent-Setup zu deinem Problem passt? Siehe when to use multiagent systems (and when not to).



Funktionsweise

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 Konversationsverlauf. Der Koordinator meldet Aktivitäten im primären Thread (der dem Event-Stream auf Session-Ebene entspricht); 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. Agent-Konfigurations-Overrides 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

Multiagent-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 Security-Agenten oder einen Dokumentations-Agenten, anstatt einen einzelnen Agenten mit allen Fähigkeiten zu überladen.
• Eskalation: Konsultiere einen leistungsfähigeren Agenten oder ein leistungsfähigeres Modell für eine Teilmenge komplexer Teilaufgaben.



Den Koordinator konfigurieren

Beim Definieren deines Agenten setzt du multiagent, um die Liste der Agenten zu deklarieren, an die der Koordinator delegieren kann:

ant beta:agents create <<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
    - type: agent
      id: $TEST_WRITER_AGENT_ID
YAML

multiagent.agents kann Folgendes akzeptieren:

• {"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 Agenten-Version fest.
• {"type": "self"} erlaubt dem Koordinator, Kopien von sich selbst zu erzeugen. Wenn die Session mit Agent-Konfigurations-Overrides erstellt wurde, gelten diese Overrides auch für diese Kopien; per ID referenzierte Roster-Einträge sind davon nicht betroffen.
• {"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 beim Erstellen oder Aktualisieren des Koordinators als Snapshot gespeichert. 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 sein eigenes multiagent.agents-Roster hat, lässt die Create- oder Update-Anfrage mit einem Validierungsfehler fehlschlagen. Maximal 20 eindeutige Agenten können in multiagent.agents aufgelistet werden, aber der Koordinator kann mehrere Kopien jedes Agenten aufrufen.

Wenn Agenten eine Inferenz-Geografie festlegen (model.inference_geo in der Agent-Definition), 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 ein Session-Create-Override eine der Festlegungen ändert.



Der Session einen Advisor geben

Ein Advisor-Eintrag in multiagent.agents gibt dem primären Thread der Session einen Advisor: ein Modell, das er mitten im Turn für strategische Beratung konsultieren kann, etwa zum Planen eines Ansatzes, um aus einer Sackgasse herauszukommen oder um 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 auflistet, 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 Mindestfähigkeitsschwelle erfüllen, und das eigene Modell des Agenten darf nicht leistungsfähiger sein als sein Advisor; Modelle gleicher Leistungsfähigkeit können kombiniert werden. Eine ungültige Kombination wird beim Speichern des Agenten mit einem 400-Validierungsfehler abgelehnt. Gültige Kombinationen folgen der Modellkompatibilitäts-Tabelle 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 Auslieferung: Der Roster-Eintrag hat keine Felder max_uses, max_tokens oder caching, und der Rat wird über Thread-Events statt über advisor_tool_result-Blöcke geliefert.



Wie Konsultationen funktionieren

Jede Konsultation läuft als plattformseitig erzeugter Thread namens anthropic.advisor, der sich selbst beendet, wenn die Konsultation abgeschlossen ist, und der Rat wird dem primären Thread als agent.thread_message_received-Event zugestellt. Eine Konsultation emittiert die Standard-Thread-Events, identifiziert durch den reservierten Namen anthropic.advisor (die Thread-Lifecycle-Events tragen ihn als agent_name, und die Ratszustellung 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 Rat)
4. session.thread_status_idle (stop_reason: end_turn)
5. session.thread_status_terminated

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

Ob dein Client den Rat 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 Rat hier als lesbaren Textinhalt; Advisor-Modelle, die dort redigierte Ergebnisse zurückgeben, liefern einen [{"type": "redacted"}]-Platzhalter als Nachrichteninhalt auf jeder Client-Oberfläche, während der Agent selbst den vollständigen Rat serverseitig weiterhin liest. Im vorangegangenen Beispiel ist Claude Opus 5 ein Advisor mit redigierten Ergebnissen, sodass dein Client den Platzhalter sieht, während der Agent den vollständigen Rat liest; wähle stattdessen Claude Opus 4.8 als Advisor, wenn du möchtest, dass der Rat im Event-Stream lesbar ist. Advisor-Thinking wird nie angezeigt. 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 generischen Hinweis fort, dass die Konsultation fehlgeschlagen ist. Ein user.interrupt auf Session-Ebene während einer Konsultation beendet den Advisor-Thread, ohne dass ein Rat 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 in der Advisor-Form genau wie konfiguriert ({"type": "advisor", "model": ...}) und parent_thread_id auf den primären Thread gesetzt.

Prompt-Caching auf der Advisor-Seite 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 Agent-Definition deklariert ihre eigenen Server und Tools), während Vault-Anmeldedaten sessionbezogen sind (vault_ids, die bei der Session-Erstellung übergeben werden, gelten für jeden Thread). Zwei Implikationen für deine Integration:

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

Agent-Konfigurations-Overrides 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 liefern die GitHub-Anmeldedaten an den Thread des Researchers.



Threads

Der Event-Stream auf Session-Ebene (/v1/sessions/{session_id}/events/stream) gilt als der primäre Thread und enthält eine komprimierte Ansicht aller Aktivitäten über alle Threads hinweg. Du siehst nicht die vollständige Aktivität von Subagenten, aber du siehst den Anfang 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 Session-status ist eine Aggregation aller Agenten-Aktivitäten; wenn mindestens ein Thread running ist, dann ist auch der Gesamtstatus der Session running.

Ein Session-Budget ist eine einzelne gemeinsame Obergrenze über alle Threads einer Session hinweg. Wenn die Obergrenze erreicht wird, pausieren Threads unabhängig voneinander, und die Kosten jedes Threads werden zum 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 zeigen Multiagent-Aktivität auf dem primären Thread unter /v1/sessions/{session_id}/events/stream an. Nachrichtenrichtungs-Events sind relativ zu dem Thread benannt, auf dessen Stream sie erscheinen: agent.thread_message_received bedeutet, dass eine Nachricht auf diesem Thread von einem anderen Thread eingetroffen ist, und agent.thread_message_sent bedeutet, dass dieser Thread eine gesendet hat. Die Aufgabe, die der Koordinator delegiert, trifft beispielsweise auf dem eigenen Stream des Child-Threads als agent.thread_message_received-Event ein.

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



Session-Thread-Events

Kritische Events werden an den primären Thread weitergeleitet. Du möchtest jedoch möglicherweise trotzdem das Reasoning und die Tool-Aufrufe eines bestimmten Agenten untersuchen. Streame oder liste dazu die Events aus dem zugehörigen Session-Thread.

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 als Vorschau sehen kannst, während das Modell ihn generiert. Eine Verbindung zeigt nur Vorschauen des Threads, den sie liest: Die Vorschauen eines Child-Threads erscheinen nie im Stream auf Session-Ebene. Um einen Subagenten live zu beobachten, öffne also seinen eigenen Thread-Stream. Siehe Session-Thread-Events als Vorschau anzeigen für das 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 Custom-Tools

Wenn ein Subagent etwas von deinem Client benötigt, etwa die Berechtigung zum Ausführen eines always_ask-Tools oder das Ergebnis eines Custom-Tools, wird das Event an den primären Thread weitergeleitet, 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 Tool-Bestätigungs-Handler, 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",
            }
        ],
    )