Multiagenten-Orchestrierung

Mit der „multiagent orchestration“ (Multiagenten-Orchestrierung) kann ein Agent sich mit anderen abstimmen, um komplexe Arbeit zu erledigen. Agenten können parallel mit ihrem eigenen isolierten Kontext arbeiten. Das verbessert die Qualität der Ausgabe und kann auch die Zeit bis zur Fertigstellung verkürzen.

Du bist dir nicht sicher, ob ein Multiagenten-Setup zu deinem Problem passt? Sieh dir an, wann du Multiagenten-Systeme einsetzen solltest (und wann nicht).

Arbeit an andere Agenten übergeben

Der Agent, den eine Session ausführt, kann Arbeit auf zwei Arten an andere Agenten übergeben. Mit Subagents (Subagenten) delegiert er Aufgaben selbst und liest, was jeder Subagent berichtet. Mit Dynamic Workflows (dynamischen Workflows) schreibt er einen Workflow: ein Programm, das viele Agenten im Hintergrund ausführt und ihre Ergebnisse zusammenführt. Er kann außerdem ein Advisor-Modell (Berater-Modell) um Rat fragen, während er die Arbeit selbst erledigt.

Du entscheidest, welche dieser Möglichkeiten der Agent nutzen kann, und der Agent bestimmt, wann er sie nutzt. Um diese Wahl zu lenken, teile dem Agenten in seinem System-Prompt mit, wann er einen Workflow-Run verwenden soll. Siehe Dem Agenten mitteilen, wann er einen Run verwenden soll. Du kannst den Agenten auch auf Agenten beschränken, die du auflistest.

Bei Subagents bestimmt der Agent selbst, was als Nächstes passiert. Der Thread eines Subagents bleibt verfügbar, bis du ihn archivierst, sodass der Agent ihm Folgenachrichten senden kann. Bei dynamischen Workflows schreibt Claude ein Programm, das Agenten ohne direkte Beteiligung von Claude orchestriert. Kontext und Ergebnisse werden programmatisch von einem Agenten zum nächsten weitergegeben. Dadurch bleibt der Haupt-Thread der Session frei, um mit dem Benutzer zu kommunizieren und bei einem oder mehreren laufenden Workflows nachzusehen, um über den Fortschritt zu berichten. Der Agent kann den Threads eines Runs keine Folgenachrichten senden, und der Server archiviert jeden davon spätestens am Ende seines Runs.

Du richtest diese im multiagent-Block der Agentendefinition ein, der einen type hat. Mit dem Typ multiagent_20261001 kann ein Agent alle drei zusammen nutzen, und du kannst jede davon ein- oder ausschalten. Standardmäßig sind subagents und workflows beide aktiviert. Bei subagents und workflows ist jeweils inline_agents aktiviert, die Einstellung für Agenten, die der Agent oder ein Workflow selbst definiert:

{
  "multiagent": { "type": "multiagent_20261001" }
}

Wie du festlegst, welche Agenten der Agent aufrufen kann, erfährst du unter Vordefinierte und Inline-Agenten. Wie du eine Einstellung ausschaltest, erfährst du unter Dynamische Workflows aktivieren.

Vordefinierte und Inline-Agenten

Jeder Subagent und jeder Agent in einem Workflow-Run ist eine von zwei Arten:

• Vordefinierter Agent: Ein Agent, den du bereits erstellt hast und den du im multiagent-Block auflistest. Er verwendet seine eigene Konfiguration: Modell, System-Prompt, Tools, MCP-Server und Skills.
• Inline-Agent: Ein Agent, der nicht gespeichert ist. Der Agent, den die Session ausführt, oder ein Workflow definiert ihn, wenn er die Arbeit verteilt. Er verwendet das Modell, die Tools, die MCP-Server und die Skills dieses Agenten.

Beide Arten funktionieren unter subagents und unter workflows:

subagents.predefined_agents und workflows.predefined_agents sind zwei getrennte Listen. Ein Agent in der einen Liste wird nicht zur anderen hinzugefügt. Beide Listen sind standardmäßig leer. Ein Eintrag in einer der beiden Listen hat eine dieser Formen:

• {"type": "agent", "id": agent.id} verweist per ID auf einen zuvor erstellten agent. Wenn keine version angegeben ist, wird der Verweis auf die neueste Version des Agenten festgelegt, wenn der Agent, der ihn auflistet, erstellt wird oder wenn ein Update die Liste sendet.
• {"type": "agent", "id": agent.id, "version": agent.version} legt eine bestimmte Agentenversion fest.
• agent.id allein, als String, ist eine Kurzform für {"type": "agent", "id": agent.id}.
• {"type": "self"} listet den Agenten selbst auf, sodass Kopien von ihm die Arbeit erledigen können. Wenn die Session mit Überschreibungen der Agentenkonfiguration erstellt wurde, gelten diese Überschreibungen auch für diese Kopien. Per ID referenzierte Einträge sind davon nicht betroffen.

Die Regeln für diese Einträge und für die Agenten, die sie benennen, gelten für beide Listen. Siehe Die Subagents auflisten.

Inline-Agenten sind unter beiden Einstellungen standardmäßig aktiviert. Um nur die Agenten zuzulassen, die du auflistest, setze inline_agents auf {"type": "disabled"} unter subagents, unter workflows oder unter beiden. Eine Einstellung mit deaktivierten Inline-Agenten benötigt mindestens einen Agenten in ihrer predefined_agents-Liste. Bei einer leeren Liste schlägt die Anfrage mit einem 400-Fehler fehl. Bei einem Update prüft der Server die Einstellungen so, wie sie nach dem Update vorliegen.

Der folgende Agent lässt nur die Agenten zu, die er auflistet. Er kann an einen Agenten und an Kopien von sich selbst delegieren, und ein Workflow kann Version 2 eines anderen Agenten verwenden:

{
  "multiagent": {
    "type": "multiagent_20261001",
    "subagents": {
      "type": "enabled",
      "inline_agents": { "type": "disabled" },
      "predefined_agents": ["agent_01J8XkN5uT3vHpLqRfWdY2", { "type": "self" }]
    },
    "workflows": {
      "type": "enabled",
      "inline_agents": { "type": "disabled" },
      "predefined_agents": [
        { "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h", "version": 2 }
      ]
    }
  }
}

An Subagents delegieren

Was delegiert werden sollte

Multiagenten-Koordination eignet sich am besten für komplexe Aufgaben, die entweder Arbeit über eine Vielzahl von Bereichen hinweg erfordern oder aus mehreren klar abgegrenzten Aufgaben bestehen, die zu einem übergeordneten Ziel beitragen.

Muster, die gut funktionieren:

• Parallelisierung: Verteile unabhängige Teilaufgaben gleichzeitig (mehrere Quellen durchsuchen, separate Dateien analysieren) und lass den Agenten die Ergebnisse zusammenführen.
• Spezialisierung: Leite an Agenten mit fachspezifischen System-Prompts und Tools weiter, etwa einen Sicherheitsagenten oder einen Dokumentationsagenten, anstatt einen einzelnen Agenten mit allen Fähigkeiten zu beladen.
• Eskalation: Konsultiere für einen Teil komplexer Teilaufgaben einen leistungsfähigeren Agenten oder ein leistungsfähigeres Modell. Um ein Modell zu konsultieren, gib der Session einen Advisor.

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 Gesprächsverlauf. Der Agent, den die Session ausführt, meldet seine Aktivität im primären Thread, dem Event-Stream auf Session-Ebene. Weitere Threads werden zur Laufzeit erzeugt, wenn er Arbeit delegiert. Auch ein Workflow-Run erstellt Threads.

Der Thread eines Subagents ist persistent. Der Agent kann einem zuvor aufgerufenen Subagent eine Folgenachricht senden, und dieser Subagent behält alles aus seinen vorherigen Turns.

Welche Konfiguration ein Subagent verwendet, hängt davon ab, ob er ein vordefinierter oder ein Inline-Agent ist. Überschreibungen der Agentenkonfiguration auf Session-Ebene gelten für den Agenten, den die Session ausführt, und für seine self-Kopien. Jeder Agent behält seinen eigenen Gesprächsverlauf.

Die Subagents auflisten

Wenn du deinen Agenten definierst, setze die predefined_agents-Liste von subagents im multiagent-Block, um die Agenten aufzulisten, an die er delegieren kann:

ant apply engineering-lead.md reviewer.md test-writer.md

---
name: Engineering Lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: enabled
    predefined_agents: # ant apply replaces each path with {type: agent, id, version}
      - ./reviewer.md
      - ./test-writer.md
---

You coordinate engineering work. Delegate code review to the reviewer agent
and test writing to the test agent.

---
name: reviewer
model: claude-haiku-5-5
---

You are a code reviewer.

---
name: test-writer
model: claude-haiku-5-5
---

You write unit tests.

Der Agent kann außerdem an Inline-Agenten delegieren, sofern du sie nicht ausschaltest. Zu dieser Einstellung und zu den Formen, die ein Eintrag der predefined_agents-Liste von subagents annehmen kann, siehe Vordefinierte und Inline-Agenten.

"advisor": {"type": "enabled", "model": "<model id>"} gibt dem primären Thread der Session einen Advisor, den er mitten im Turn konsultieren kann. Der Advisor ist eine Einstellung im multiagent-Block, kein Eintrag in dieser Liste. Siehe Der Session einen Advisor geben.

Dynamische Workflows sind bei diesem Typ ebenfalls standardmäßig aktiviert, sodass dieser Agent umfangreiche Arbeit planen kann, die viele Agenten im Hintergrund ausführt. Wie du sie ausschaltest oder Agenten auflistest, die ein Workflow verwenden kann, erfährst du unter Dynamische Workflows aktivieren.

Die folgenden Regeln gelten für die Agenten, die du in der predefined_agents-Liste von subagents auflistest, und auch für die Agenten, die du in der predefined_agents-Liste von workflows auflistest:

• Festlegung: Die Konfiguration des Agenten, einschließlich der predefined_agents-Liste von subagents, wird als Snapshot gespeichert, wenn der Agent erstellt oder aktualisiert wird. Referenzierte Agenten bleiben auf die damals aufgelösten Versionen festgelegt und übernehmen keine späteren Updates ihrer Definitionen. Ein Update, das die Liste nicht sendet, behält die bereits festgelegten Versionen bei. Um an eine neuere Version eines referenzierten Agenten zu delegieren, aktualisiere den Agenten, sodass die predefined_agents-Liste von subagents auf diese Version verweist.
• Eine Ebene: Der Agent kann nur an eine Ebene von Agenten delegieren. Wird ein anderer Agent referenziert, bei dem multiagent gesetzt ist, schlägt die Erstellungs- oder Update-Anfrage mit einem 400-Validierungsfehler fehl.
• Bis zu 20 Agenten: Die predefined_agents-Liste von subagents kann bis zu 20 eindeutige Agenten auflisten. Das Limit gilt pro Liste: Die predefined_agents-Liste von workflows kann ebenfalls bis zu 20 auflisten. Der Agent kann mehrere Kopien jedes Subagents aufrufen, innerhalb des Thread-Limits der Session.
• Inferenz-Geografie: Der Agent und jeder Agent, den du in der predefined_agents-Liste von subagents oder von workflows auflistest, müssen dieselbe Inferenz-Geografie festlegen (inference_geo im model der Agentendefinition), oder keiner von ihnen darf eine festlegen. Eine Abweichung in einer der beiden Listen wird mit einem 400-Validierungsfehler abgelehnt. Diese Prüfung läuft sowohl beim Speichern des Agenten als auch dann, wenn eine Überschreibung bei der Session-Erstellung eine der Festlegungen ändert.

Die Session erstellen

Erstelle eine Session, die auf den Agenten verweist. Der Agent delegiert bei Bedarf an die Agenten, die du in der predefined_agents-Liste von subagents auflistest. Er kann außerdem an Inline-Agenten delegieren, sofern du sie nicht ausschaltest.

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

Agenten mit MCP-Servern verbinden

MCP-Server gelten pro Agent: Jede Agentendefinition deklariert ihre eigenen Server und Tools. Ein Inline-Agent hat keine Agentendefinition, daher verwendet er die MCP-Server und Tools des Agenten, den die Session ausführt. Vault-Anmeldedaten gelten pro Session: 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 für jeden MCP-Server, der von irgendeinem Agenten verwendet wird, eine Vault-Anmeldung hinzu.
• Um den Zugriff eines Agenten einzuschränken, deklariere in seiner Agentendefinition nur die Server, die er benötigt. Einen Inline-Agenten kannst du auf diese Weise nicht einschränken. Um nur die Agenten zuzulassen, die du auflistest, deaktiviere inline_agents sowohl in subagents als auch in workflows, und liste in jedem mindestens einen Agenten auf. Siehe Vordefinierte und Inline-Agenten.

Überschreibungen der Agentenkonfiguration bei der Session-Erstellung können die MCP-Server des Agenten, den die Session ausführt, sowie die seiner self-Kopien ersetzen.

Bei einer limited-Umgebung schlägt die Session-Erstellung mit einem 400-Fehler fehl, wenn der Agent oder ein Agent, den du in der predefined_agents-Liste von subagents oder workflows auflistest, einen MCP-Server deklariert, dessen Host nicht in allowed_hosts enthalten ist. Wenn du allow_mcp_servers in den Netzwerkeinstellungen der Umgebung auf true setzt, wird diese Prüfung deaktiviert.

Erstelle den Researcher, der den GitHub-MCP-Server deklariert, und den Agenten, der an den Researcher delegiert:

ant apply lead.md researcher.md

---
name: lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: enabled
    predefined_agents: # ant apply replaces each path with {type: agent, id, version}
      - ./researcher.md
---

---
name: researcher
model: claude-haiku-5-5
mcp_servers:
  - type: url
    name: github
    url: https://api.githubcopilot.com/mcp/
tools:
  - type: mcp_toolset
    mcp_server_name: github
---

Erstelle dann die Session mit dem Vault, der die GitHub-Anmeldedaten enthält:

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

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

Threads

Der Session-Thread jedes Agenten hat seinen eigenen Event-Stream. Wie du Threads auflistest, unterbrichst oder archivierst, ihre Events liest und Tool-Berechtigungen über sie hinweg handhabst, erfährst du unter Session-Threads.

Dynamische Workflows

Mit dynamischen Workflows kann ein Agent Arbeit mit vielen Teilen übernehmen, etwa Hunderte von Dokumenten überprüfen oder viele Quellen gegenprüfen. Der Agent schreibt einen Workflow: ein Programm, das viele Agenten in Phasen ausführt und zusammenführt, was sie zurückgeben. Der Server führt ihn im Hintergrund als Workflow-Run aus, während der Agent weiterarbeitet oder seinen Turn beendet. Du schaltest dynamische Workflows mit der Einstellung workflows im multiagent-Block des Agenten ein oder aus. Die Agenten eines Runs können gleichzeitig arbeiten, sodass eine lange Aufgabe schneller abgeschlossen werden kann, als wenn ein Agent jedes Teil nacheinander erledigen würde.

• Wie ein Run startet: Du beschreibst die Arbeit in einer user.message. Daraus bestimmt der Agent, ob und wann er einen Run startet, sodass kein zusätzlicher API-Aufruf nötig ist. Stattdessen beeinflusst du die Entscheidung des Agenten, indem du in der user.message oder im System-Prompt des Agenten beschreibst, wann ein Run verwendet werden soll. (Berechtigungsrichtlinien gelten für die Tools, die die Agenten eines Runs aufrufen, nicht für das Starten des Runs.)
• Welche Agenten er verwendet: Inline-Agenten, die der Workflow definiert, vordefinierte Agenten, die du in der predefined_agents-Liste von workflows auflistest, oder beides. Wenn du keine auflistest, definiert der Workflow sie alle. Ein Inline-Agent verwendet das Modell des Agenten, den die Session ausführt. Damit ein Run für einige seiner Agenten ein anderes Modell verwenden kann, erstelle sie als Agenten und liste sie in der predefined_agents-Liste von workflows auf.
• Wie du ihn verfolgst: Run-Events kommen im Event-Stream der Session an, und jeder Agent im Run arbeitet in einem Session-Thread, den du auflisten, lesen und streamen kannst. Unter Workflow-Runs findest du die Events, Unterbrechungen, Limits und was die Threads eines Runs anzeigen.

Dynamische Workflows aktivieren

Wenn du deinen Agenten definierst, setze multiagent.type auf "multiagent_20261001" und aktiviere workflows. Dynamische Workflows und das Delegieren (subagents) sind bei diesem Typ beide standardmäßig aktiviert. Wenn du nur dynamische Workflows möchtest, setze zusätzlich subagents auf {"type": "disabled"}.

Bevor du den multiagent.type eines bestehenden Agenten änderst, lies nach, wie du einen Agenten auf diesen Typ umstellst.

Dieses Beispiel deaktiviert außerdem Websuche und Web-Fetch, da das Prüfen von Verträgen das Web nicht nutzt:

ant apply contract-reviewer.md

---
name: Contract Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_search
        enabled: false
      - name: web_fetch
        enabled: false
multiagent:
  type: multiagent_20261001
  workflows:
    type: enabled
---

You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.

Damit ein Workflow Agenten verwenden kann, die du bereits erstellt hast, liste sie in workflows.predefined_agents auf. Die Einstellungen subagents und advisor gehören in denselben multiagent-Block. Wie du Subagenten auflistest, erfährst du unter An Subagenten delegieren. Wie du einen Advisor festlegst, erfährst du unter Der Session einen Advisor geben. Dieser Agent erlaubt einem Workflow, einen von dir erstellten Agenten zu verwenden, listet zwei Subagenten auf und hat einen Advisor:

{
  "multiagent": {
    "type": "multiagent_20261001",
    "workflows": {
      "type": "enabled",
      "predefined_agents": [{ "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h" }]
    },
    "subagents": {
      "type": "enabled",
      "predefined_agents": [
        { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
        { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
      ]
    },
    "advisor": { "type": "enabled", "model": "claude-opus-5-5" }
  }
}

Jede Einstellung wird einzeln aktiviert oder deaktiviert:

Was in jede Liste gehört und wie du nur die von dir aufgelisteten Agenten zulässt, erfährst du unter Vordefinierte und Inline-Agenten.

Beachte Folgendes:

• Aktualisieren: Ein Update, das den Typ multiagent_20261001 beibehält, ändert nur das, was es sendet:
  • Eine Einstellung oder ein Feld, das du weglässt, behält seinen gespeicherten Wert.
  • Eine Einstellung oder ein Feld, das du als null sendest, erhält seinen Standardwert, ebenso alles darin, unabhängig davon, was du gespeichert hattest.
  • Eine predefined_agents-Liste, die du sendest, ersetzt die gespeicherte Liste.
  • Eine Einstellung, die du mit einem anderen type sendest, ersetzt die gespeicherte Einstellung, und die Felder, die du darin weglässt, erhalten ihre Standardwerte.
  • Jedes Objekt, das du sendest, benötigt seinen type, und ein aktivierter advisor benötigt sein model.
• Deaktivieren: Setze workflows auf {"type": "disabled"}. Es bleibt deaktiviert, bis ein Update es wieder aktiviert. Das Senden von null aktiviert es, weil der Standardwert „aktiviert“ ist. Dasselbe gilt für subagents.
• Bestehende Sessions: Eine Session kopiert die Einstellung, wenn sie erstellt wird, daher ändert eine spätere Änderung des Agenten keine bereits bestehende Session.
• Agenten, die du auflisten kannst: Ein Agent, bei dem multiagent gesetzt ist, kann nicht als Subagent eines anderen Agenten oder in der predefined_agents-Liste von workflows in einem anderen Agenten aufgelistet werden. Ein Agent kann sich selbst mit {"type": "self"} in einer der beiden Listen aufführen; beim Auslesen erscheint das als seine eigene id und version.
• Tool-Namen: Das Präfix ant__ ist reserviert. Wenn dein Agent bereits ein benutzerdefiniertes Tool hat, dessen Name mit ant__ beginnt, schlägt ein Update mit einem 400-Fehler fehl, bis du tools ohne diesen Namen sendest. Auch eine neue Session wird mit einem 400-Fehler abgelehnt, wenn ihr Agent oder ein Agent in einer der beiden Listen ein solches Tool hat. Benenne das Tool im selben Update um oder entferne es, mit dem du dynamische Workflows aktivierst. Siehe Benutzerdefinierte Tools.
• Budget: Lege beim Erstellen der Session ein Session-Budget fest, um die Ausgaben der Session einschließlich der Runs zu begrenzen; zu einer bestehenden Session kannst du keines hinzufügen. Runs pausieren, wenn die Session das Budget erreicht, und Runs, die durch das Budget pausiert wurden, werden fortgesetzt, wenn du es erhöhst oder entfernst, es sei denn, eine Unterbrechung hat sie ebenfalls pausiert. Siehe Kosten und Budgets.

Dem Agenten mitteilen, wann er einen Run verwenden soll

Das Aktivieren dynamischer Workflows gibt dem Agenten die Möglichkeit, Workflow-Runs zu starten. Der Agent entscheidet, wann er einen startet. Um diese Entscheidung zu steuern, füge dem System-Prompt des Agenten eine Anweisung wie die folgende hinzu. Der Vertragsprüfungs-Agent in Dynamische Workflows aktivieren verwendet diesen System-Prompt:

You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.

Um ihn anzupassen, benenne die Aufgaben im Bereich deines Agenten, die einen Run erfordern, und die kleinen Aufgaben, die der Agent selbst erledigen soll. Du kannst auch steuern, wie ein Run die Arbeit erledigt, wie in diesen Beispielen:

• Wie die Arbeit aufgeteilt wird: „Verwende in einem Run einen Agenten pro Vertrag. Lass dann einen zweiten Agenten jeden Vertrag prüfen, nicht nur die, bei denen der erste Agent etwas gefunden hat, und nach dem suchen, was der erste Agent übersehen hat. Alles, was die Prüfung nicht besteht, wird neu bearbeitet und erneut geprüft.“
• Was zu tun ist, wenn ein Agent fehlschlägt: „Das Fehlschlagen eines einzelnen Agenten darf den Run nicht fehlschlagen lassen. Wenn ein Agent einen Vertrag nicht lesen kann, führe diesen Vertrag als nicht abgedeckt auf. Wenn der Run endet, sag mir, welche Verträge nicht abgedeckt wurden.“
• Ein Zeitlimit: „Gib dem Run ein Zeitlimit von einer Stunde.“
• Zuerst planen: „Bevor du einen Run startest, beschreibe seine Phasen und wie viele Agenten jede davon ausführt. Warte dann auf meine Freigabe.“ Es gibt keinen Genehmigungsschritt, bevor ein Run startet, daher wird dies durch nichts erzwungen.

Beschränke Runs auf die Aufgaben, die sie benötigen, denn jeder Agent in einem Run verbraucht Token.

Erstelle dann eine Session mit dem Agenten, wie bei jedem anderen Agenten, und beschreibe die Arbeit in einer user.message. Du kannst in dieser Nachricht auch um einen Run bitten.

Informationen zu den Events eines Runs, zum Unterbrechen einer Session mit offenen Runs, zu dem, was sich ändert, während ein Run offen ist, sowie zu Budgets und Limits findest du unter Workflow-Runs.

Der Session einen Advisor geben

Eine aktivierte advisor-Einstellung im multiagent-Block des Agenten gibt dem primären Thread der Session einen Advisor: ein Modell, das er mitten im Turn um strategische Beratung bitten kann, etwa um einen Ansatz zu planen, ein Hindernis zu überwinden oder die Arbeit vor dem Abschluss zu überprüfen. Die Einstellung ist standardmäßig deaktiviert. Um sie zu aktivieren, setze advisor auf {"type": "enabled", "model": "..."}, was genau zwei Felder hat, type und model:

ant apply backend-engineer.md

---
name: Backend engineer
model: claude-sonnet-5
multiagent:
  type: multiagent_20261001
  advisor:
    type: enabled
    model: claude-opus-5-5
---

You implement backend features end to end. Consult the advisor before major backend design decisions.

Dieses Beispiel setzt nur advisor. Die anderen beiden Einstellungen, subagents und workflows, behalten ihre Standardwerte, sodass beide aktiviert sind und der Agent außerdem an Inline-Agenten delegieren und Workflow-Runs starten kann. Für einen Agenten, der einen Advisor konsultiert und die gesamte Arbeit selbst erledigt, setze beide auf {"type": "disabled"}.

Du kannst den Advisor nicht in der predefined_agents-Liste von subagents oder workflows aufführen. Ein aktivierter advisor reserviert den Namen anthropic.advisor. Solange er aktiviert ist, darf keine der beiden Listen einen Agenten enthalten, der wörtlich anthropic.advisor heißt: Die Anfrage wird mit einem 400-Validierungsfehler abgelehnt.

Das Advisor-Modell muss ein Mindestmaß 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 mit einem 400-Validierungsfehler abgelehnt, wenn der Agent gespeichert wird, und erneut, wenn eine Session erstellt wird. Die Paarung wird außerdem zu Beginn jeder Konsultation geprüft: Ist sie nicht mehr gültig, schlägt diese Konsultation fehl und die Session wird fortgesetzt. 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 Auslieferung: Die advisor-Einstellung hat keine Felder max_uses, max_tokens oder caching, und die 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 gestarteter 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 erzeugt die üblichen Thread-Events, gekennzeichnet durch den reservierten Namen anthropic.advisor (die Thread-Lifecycle-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 erzeugt, und im Event-Stream der Session erscheint kein agent.thread_message_sent-Event, weil die Eingabe der Konsultation von der Plattform zusammengestellt und nicht vom Agenten gesendet wird. Wenn du die eigenen Events des Advisor-Threads auflistest, erscheint der Ratschlag dort auch 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 ankommt, behandle diese also nicht als Signal, dass der Ratschlag bereits zugestellt wurde.

Ob dein Client den Ratschlag lesen kann, hängt von der Richtlinie des Advisor-Modells ab. Sie entspricht der Aufteilung der Ergebnisvarianten beim Advisor-Tool der Messages API. Ein Advisor-Modell, das dort Klartext-Ergebnisse liefert, liefert hier lesbaren Text. Eines, das geschwärzte Ergebnisse liefert, liefert auf jeder Client-Oberfläche einen [{"type": "redacted"}]-Platzhalter, während der Agent den vollständigen Ratschlag serverseitig weiterhin liest. Das vorherige Beispiel verwendet das neueste dir zur Verfügung stehende Opus-Modell als Advisor. Es liefert geschwärzte Ergebnisse, daher sieht dein Client nur den Platzhalter. Um den Ratschlag im Event-Stream zu lesen, verwende einen Advisor, der Klartext liefert, etwa Claude Opus 4.8. Die Richtlinie eines Modells kann sich ohne Änderung an der API ändern, behandle also sowohl text- als auch redacted-Blöcke. Manche Agenten-Modelle lassen sich nur mit Advisors paaren, die geschwärzte Ergebnisse liefern; siehe den Abschnitt Modellkompatibilität des Advisor-Tools. Das Nachdenken des Advisors wird nie offengelegt. Clients können selbst keine redacted-Blöcke senden; ein Event, das einen solchen 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 fort, dass die Konsultation fehlgeschlagen ist. 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 Subagent. Das list_agents-Tool des Agenten zeigt ihn nicht an, und send_to_agent, das einem Subagenten eine Folgenachricht sendet, kann ihn nicht erreichen. Nur der primäre Thread der Session kann ihn konsultieren; Subagenten können das nicht.

Advisor-Threads sind vom Limit von 25 Child-Threads ausgenommen. Sie erscheinen in der Thread-Liste der Session. Ihr agent ist die Advisor-Form, {"type": "advisor", "model": ...}, mit dem von dir konfigurierten Modell, und ihre parent_thread_id ist der primäre Thread.

Prompt-Caching auf der Seite des Advisors erfolgt automatisch; es gibt nichts zu konfigurieren. Konsultationen werden zu den Preisen des Advisor-Modells abgerechnet, und ihre Token erscheinen in der Nutzung des Advisor-Threads und in den Nutzungssummen der Session. Sie werden außerdem auf ein Session-Budget angerechnet, zum Listenpreis des Advisor-Modells. Jede Konsultation sendet dem Advisor die bisherige Konversation des primären Threads, daher verbrauchen Konsultationen spät in einer langen Session mehr Input-Token.

Den Advisor entfernen

Um den Advisor zu entfernen, aktualisiere den Agenten mit advisor gesetzt auf {"type": "disabled"}. Bei einem Agenten, der bereits den Typ multiagent_20261001 hat, behält eine Einstellung, die das Update weglässt, ihren gespeicherten Wert, du musst also subagents oder workflows nicht erneut senden. Aus demselben Grund behält ein Update, das advisor weglässt, den Advisor bei. Bevor du den multiagent.type eines bestehenden Agenten änderst, lies nach, wie du einen Agenten auf diesen Typ umstellst.

Vom Typ coordinator umsteigen

Wie multiagent_20261001 ermöglicht auch der Typ coordinator einem Agenten, an von dir aufgelistete Subagenten zu delegieren und ein Advisor-Modell zu konsultieren. Mit dem Typ coordinator kann der Agent keine Workflow-Runs starten und keine Subagenten selbst definieren. Die API akzeptiert beide Typen.

Um einen Agenten auf multiagent_20261001 umzustellen, aktualisiere den Agenten mit einem multiagent-Block dieses Typs:

1. Setze type auf "multiagent_20261001".
2. Liste die Agenten, die der Agent aufrufen kann, in subagents.predefined_agents auf. Die Einträge behalten ihre bisherige Form.
3. Wenn der Agent einen Advisor hat, setze advisor auf {"type": "enabled", "model": "..."} mit dem Modell des Advisors.
4. Sende den gesamten Block in einem einzigen Update.

Dieser Block gibt einem Agenten beispielsweise zwei Subagenten und einen Advisor:

{
  "multiagent": {
    "type": "multiagent_20261001",
    "subagents": {
      "type": "enabled",
      "predefined_agents": [
        { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
        { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
      ]
    },
    "advisor": { "type": "enabled", "model": "claude-opus-5-5" }
  }
}

Dieser Block lässt workflows und subagents.inline_agents weg, daher erhalten beide ihren Standardwert und sind aktiviert. Der umgestellte Agent kann also auch Workflow-Runs starten und Subagenten selbst definieren. Um eines davon deaktiviert zu lassen, setze es im selben Update auf {"type": "disabled"}. Siehe Dynamische Workflows aktivieren und Vordefinierte und Inline-Agenten.

Wenn der Agent einen Advisor und keine Subagenten hat, setze subagents auf {"type": "disabled"}, damit das Delegieren deaktiviert bleibt. Eine Anfrage, die subagents.inline_agents deaktiviert und keine Agenten auflistet, schlägt mit einem 400-Fehler fehl.

Das Update ersetzt den gesamten multiagent-Block, sende also die Liste der Agenten und den Advisor erneut, wie im Beispiel. Was du weglässt, erhält seinen Standardwert:

• subagents.predefined_agents: Die Liste ist leer, sodass der Agent die von dir aufgelisteten Subagenten verliert.
• advisor: Der Advisor ist deaktiviert.

Sobald der Agent den Typ multiagent_20261001 hat, behält eine Einstellung, die ein späteres Update weglässt, ihren gespeicherten Wert.

Das Update ändert keine bereits bestehenden Sessions. Um den neuen Block zu verwenden, erstelle nach dem Update eine Session.

Verfügbarkeit