Multiagent-Sitzungen

Die Multi-Agent-Orchestrierung ermöglicht es einem Agenten, mit anderen zusammenzuarbeiten, um komplexe Aufgaben zu erledigen. Agenten können parallel mit ihrem eigenen isolierten Kontext arbeiten, was die Ausgabequalität verbessert und die Zeit bis zur Fertigstellung verkürzt.

Funktionsweise

Alle Agenten teilen sich denselben Container und das Dateisystem, aber jeder Agent läuft in seinem eigenen Sitzungs-Thread, einem kontextisolierten Ereignisstrom mit seiner eigenen Gesprächshistorie. Der Koordinator meldet Aktivitäten im primären Thread (der mit dem Sitzungs-Ereignisstrom identisch ist); zusätzliche Threads werden zur Laufzeit erzeugt, wenn der Koordinator beschließt, zu delegieren.

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

Jeder Agent verwendet seine eigene Konfiguration (Modell, Systemaufforderung, Tools, MCP-Server und Skills), wie sie bei der Erstellung des Agenten definiert wurde. Tools und Kontext werden nicht geteilt.

Was delegiert werden sollte

Multiagent-Sitzungen funktionieren am besten, wenn es mehrere gut abgegrenzte, spezialisierte Aufgaben in einem übergeordneten Ziel gibt:

• Code-Review: Ein Reviewer-Agent mit einer fokussierten Systemaufforderung und schreibgeschützten Tools.
• Testgenerierung: Ein Test-Agent, der Tests schreibt und ausführt, ohne Produktionscode zu berühren.
• Recherche: Ein Such-Agent mit Web-Tools, der Erkenntnisse an den Koordinator zurückmeldet.

Aufrufbare Agenten deklarieren

Wenn Sie Ihren Agenten definieren, listen Sie zusätzliche IDs von Agenten auf, die er aufrufen darf:

ant beta:agents create <<YAML
name: Engineering Lead
model: claude-opus-4-7
system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.
tools:
  - type: agent_toolset_20260401
callable_agents:
  - type: agent
    id: $REVIEWER_AGENT_ID
    version: $REVIEWER_AGENT_VERSION
  - type: agent
    id: $TEST_WRITER_AGENT_ID
    version: $TEST_WRITER_AGENT_VERSION
YAML

Jeder Eintrag in callable_agents muss die ID eines vorhandenen Agenten sein. Es wird nur eine Ebene der Delegierung unterstützt: Der Koordinator kann andere Agenten aufrufen, aber diese Agenten können nicht selbst Agenten aufrufen.

Erstellen Sie dann eine Sitzung, die auf den Orchestrator verweist:

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

Die aufrufbaren Agenten werden aus der Konfiguration des Orchestrators aufgelöst. Sie müssen nicht auf sie bei der Sitzungserstellung verweisen.

Sitzungs-Threads

Der Sitzungs-Ereignisstrom (/v1/sessions/:id/stream) wird als primärer Thread betrachtet und enthält eine kondensierte Ansicht aller Aktivitäten über alle Threads hinweg. Sie sehen nicht die einzelnen Traces der aufgerufenen Agenten, aber Sie sehen den Anfang und das Ende ihrer Arbeit. Sitzungs-Threads sind der Ort, an dem Sie sich in die Überlegungen und Tool-Aufrufe eines bestimmten Agenten vertiefen können.

Der Sitzungsstatus ist auch eine Aggregation aller Agent-Aktivitäten; wenn mindestens ein Thread running ist, dann ist der Gesamtsitzungsstatus auch running.

Listen Sie alle Threads in einer Sitzung wie folgt auf:

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

Streamen Sie Ereignisse aus einem bestimmten Thread:

with client.beta.sessions.threads.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_idle":
                break

Listen Sie frühere Ereignisse für einen Thread auf:

for event in client.beta.sessions.threads.events.list(
    thread.id,
    session_id=session.id,
):
    print(f"[{event.type}] {event.processed_at}")

Multiagent-Ereignistypen

Diese Ereignisse zeigen Multiagent-Aktivitäten im Top-Level-Sitzungsstrom.

Tool-Berechtigungen und benutzerdefinierte Tools in Threads

Wenn ein callable_agent-Thread etwas von Ihrem Client benötigt (Berechtigung zum Ausführen eines always_ask-Tools oder das Ergebnis eines benutzerdefinierten Tools), wird die Anfrage im Sitzungsstrom mit einem session_thread_id-Feld angezeigt. Fügen Sie dieselbe session_thread_id ein, wenn Sie Ihre Antwort posten, damit die Plattform sie an den wartenden Thread zurückleitet.

• session_thread_id ist vorhanden: Das Ereignis stammt aus einem Subagenten-Thread. Wiederholen Sie es in Ihrer Antwort.
• session_thread_id fehlt: Das Ereignis kam aus dem primären Thread. Antworten Sie ohne das Feld.
• Vergleichen Sie tool_use_id, um Anfragen mit Antworten zu koppeln.

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

for event_id in stop.event_ids:
    pending = events_by_id[event_id]
    confirmation = {
        "type": "user.tool_confirmation",
        "tool_use_id": event_id,
        "result": "allow",
    }
    # Echo session_thread_id when the request came from a subagent thread
    if pending.session_thread_id is not None:
        confirmation["session_thread_id"] = pending.session_thread_id
    client.beta.sessions.events.send(session.id, events=[confirmation])