Multi-Agent-Sessions

Multi-Agent-Orchestrierung ermöglicht es einem Agent, sich mit anderen zu koordinieren, um komplexe Aufgaben zu erledigen. Agents können parallel mit ihrem eigenen isolierten Kontext agieren, was die Ausgabequalität verbessert und auch die Zeit bis zur Fertigstellung verkürzen kann.



Funktionsweise

Alle Agents 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 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 Folgeanfrage an einen Agent 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

Multi-Agent-Koordination eignet sich am besten für komplexe Aufgaben, die entweder Arbeit über verschiedene Bereiche 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 Agents mit domänenspezifischen System-Prompts und Tools weiter, etwa einen Security-Agent oder einen Dokumentations-Agent, anstatt einen einzelnen Agent mit allen Fähigkeiten zu überladen.
• Eskalation: Ziehe für eine Teilmenge komplexer Teilaufgaben einen leistungsfähigeren Agent oder ein leistungsfähigeres Modell hinzu.



Den Koordinator konfigurieren

Setze beim Definieren deines Agents multiagent, um die Liste der Agents 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 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 Agents 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-Overrides erstellt wurde, gelten diese Overrides auch für diese Kopien; per ID referenzierte Roster-Einträge sind davon nicht betroffen.

Die Konfiguration des Koordinators, einschließlich seines multiagent.agents-Rosters, wird beim Erstellen oder Aktualisieren des Koordinators als Snapshot gespeichert. Referenzierte Agents 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 Agents zu delegieren, aktualisiere den Koordinator, sodass sein Roster diese Version referenziert.

Der Koordinator kann nur an eine Ebene von Agents delegieren; Tiefe > 1 wird ignoriert. Maximal 20 eindeutige Agents können in multiagent.agents aufgelistet werden, aber der Koordinator kann mehrere Kopien jedes Agents aufrufen.



Die Session erstellen

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

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



Agents mit MCP-Servern verbinden

MCP-Server sind agent-bezogen (jede Agent-Definition deklariert ihre eigenen Server und Tools), während Vault-Anmeldedaten session-bezogen sind (vault_ids, die bei der Session-Erstellung übergeben werden, gelten für jeden Thread). Zwei Auswirkungen für deine Integration:

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

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-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-Anmeldedaten für den Thread des Researchers bereit.



Threads

Der Event-Stream auf Session-Ebene (/v1/sessions/: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 Subagents, aber du siehst den Beginn und das Ende ihrer Arbeit sowie blockierende Events wie Tool-Berechtigungsanfragen.

Session-Threads sind der Ort, an dem du die Aktivität eines bestimmten Agents im Detail untersuchst.

Der Session-status ist eine Aggregation aller Agent-Aktivitäten; wenn mindestens ein Thread running ist, dann ist auch der gesamte Session-Status running.



Events des primären Threads

Diese Events zeigen Multi-Agent-Aktivität auf dem primären Thread unter /v1/sessions/:id/events/stream an.



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 Agents untersuchen. Streame oder liste dazu die Events aus dem zugehörigen Session-Thread.



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": ["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",
            }
        ],
    )