Multiagenten-Orchestrierung

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 Qualität der Ergebnisse verbessert und auch die Zeit bis zur Fertigstellung verkürzen kann.

Nicht sicher, ob ein Multiagenten-Setup zu deinem Problem passt? Siehe wann man Multiagenten-Systeme verwenden 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 eigener Gesprächshistorie. 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. Agent-Konfigurationsüberschreibungen 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 eine Vielzahl von 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 lasse den Koordinator die Ergebnisse zusammenführen.
• Spezialisierung: Leite an Agenten mit domänenspezifischen System-Prompts und Tools weiter, wie z. B. einen Sicherheits-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

Wenn du deinen Agenten definierst, setze 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-4-8
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 akzeptiert Folgendes:

• {"type": "agent", "id": agent.id} referenziert einen zuvor erstellten agent anhand der 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 Agent-Version fest.
• {"type": "self"} erlaubt dem Koordinator, Kopien von sich selbst zu erzeugen. Wenn die Session mit Agent-Konfigurationsüberschreibungen erstellt wurde, gelten diese Überschreibungen auch für diese Kopien; per ID referenzierte Listeneinträge sind davon nicht betroffen.

Die Konfiguration des Koordinators, einschließlich seiner multiagent.agents-Liste, wird als Snapshot gespeichert, 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 seine Liste diese Version referenziert.

Der Koordinator kann nur an eine Ebene von Agenten delegieren; das Referenzieren eines Agenten, der eine eigene multiagent.agents-Liste 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.



Die Session erstellen

Erstelle eine Session, die den Koordinator referenziert. Der Koordinator delegiert bei Bedarf an die Agenten in seiner Liste.

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 für jeden MCP-Server, der über alle Agenten hinweg verwendet wird, eine Vault-Anmeldeinformation hinzu.
• Um den Zugriff eines Agenten einzuschränken, deklariere in seiner Agent-Definition nur die Server, die er benötigt.

Agent-Konfigurationsüberschreibungen 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-4-8",
    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 die GitHub-Anmeldeinformation für den Thread des Researchers bereit.



Threads

Der Event-Stream auf Session-Ebene (/v1/sessions/{session_id}/events/stream) gilt als primärer Thread und enthält eine komprimierte 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 Session-status ist eine Aggregation aller Agenten-Aktivitäten; wenn mindestens ein Thread running ist, dann ist der Gesamtstatus der Session ebenfalls running.

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 Multiagenten-Aktivität auf dem primären Thread unter /v1/sessions/{session_id}/events/stream an. Events zur Nachrichtenrichtung sind relativ zu dem Thread benannt, auf dessen Stream sie erscheinen: agent.thread_message_received bedeutet, dass eine Nachricht von einem anderen Thread auf diesem Thread eingegangen ist, und agent.thread_message_sent bedeutet, dass dieser Thread eine gesendet hat. Die Aufgabe, die der Koordinator delegiert, kommt beispielsweise auf dem eigenen Stream des Child-Threads als agent.thread_message_received-Event an.



Session-Thread-Events

Kritische Events werden an den primären Thread weitergeleitet. Möglicherweise möchtest du dennoch die Argumentation 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 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 den Thread in der Vorschau an, den sie liest: Die Vorschauen eines Child-Threads erscheinen nie auf dem 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, wie z. B. die Berechtigung, ein always_ask-Tool auszuführen, oder das Ergebnis eines benutzerdefinierten 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": ["toolu_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",
            }
        ],
    )