Multiagenten-Orchestrierung

„Multiagent orchestration“ (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 Ausgabequalität verbessert und auch die Zeit bis zur Fertigstellung verkürzen kann.

Nicht sicher, ob ein Multiagenten-Setup zu deinem Problem passt? Siehe wann man Multiagentensysteme einsetzen sollte (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 steuern, 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 Subagenten bestimmt der Agent selbst, was als Nächstes passiert. Der Thread eines Subagenten bleibt verfügbar, bis du ihn archivierst, sodass der Agent ihm Folgenachrichten senden kann. Bei dynamischen Workflows schreibt Claude ein Programm, um Agenten ohne Claudes direkte Beteiligung zu orchestrieren. Kontext und Ergebnisse werden programmatisch von einem Agenten an den nächsten weitergegeben, wodurch der Haupt-Session-Thread frei bleibt, 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 einzeln ein- oder ausschalten. Standardmäßig sind subagents und workflows beide aktiviert. subagents und workflows haben jeweils inline_agents aktiviert, die Einstellung für Agenten, die der Agent oder ein Workflow selbst definiert:

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

Um festzulegen, welche Agenten der Agent aufrufen kann, siehe Vordefinierte und Inline-Agenten. Um eine Einstellung auszuschalten, siehe 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 einer 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} referenziert einen zuvor erstellten agent per ID. Wenn keine version angegeben ist, wird die Referenz 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 die 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 nicht betroffen.

Die Regeln für diese Einträge und für die Agenten, die sie benennen, gelten für beide Listen. Siehe Die Subagenten 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 Subagenten 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 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 Agenten die Ergebnisse zusammenführen.
• Spezialisierung: Leite an Agenten mit domänenspezifischen System-Prompts und Tools weiter, etwa einen Sicherheitsagenten oder einen Dokumentationsagenten, anstatt einen einzelnen Agenten mit jeder Fähigkeit 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.

Wie es funktioniert

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 Aktivitäten im primären Thread, dem Event-Stream auf Session-Ebene. Zusätzliche Threads werden zur Laufzeit erzeugt, wenn er Arbeit delegiert. Ein Workflow-Run erstellt ebenfalls Threads.

Der Thread eines Subagenten ist persistent. Der Agent kann einem Subagenten, den er zuvor aufgerufen hat, 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 Subagenten 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:

# Erstelle die Subagents und lies dann ihre IDs aus der Lockfile.
ant apply reviewer.md test-writer.md
REVIEWER_AGENT_ID=$(jq -er '.resources["./reviewer.md"].id' claude-lock.json)
TEST_WRITER_AGENT_ID=$(jq -er '.resources["./test-writer.md"].id' claude-lock.json)

# Schreibe die Definition des Agents und liste jeden Subagent per ID auf.
cat > engineering-lead.md <<EOF
---
name: Engineering Lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: enabled
    predefined_agents:
      - type: agent
        id: $REVIEWER_AGENT_ID
      - type: agent
        id: $TEST_WRITER_AGENT_ID
---

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

# Erstelle den Agent.
ant apply engineering-lead.md reviewer.md test-writer.md

---
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 auch an Inline-Agenten delegieren, sofern du sie nicht deaktivierst. Zu dieser Einstellung und zu den Formen, die ein Eintrag der predefined_agents-Liste von subagents annimmt, 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 mit diesem Typ ebenfalls standardmäßig aktiviert, sodass dieser Agent umfangreiche Arbeit planen kann, die viele Agenten im Hintergrund ausführt. Um sie zu deaktivieren oder um Agenten aufzulisten, die ein Workflow verwenden kann, siehe Dynamische Workflows aktivieren.

Die folgenden Regeln gelten für die Agenten, die du in der predefined_agents-Liste von subagents auflistest, und ebenso 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 spätere Updates ihrer Definitionen nicht. 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 diese Version referenziert.
• Eine Ebene: Der Agent kann nur an eine Ebene von Agenten delegieren. Das Referenzieren eines anderen Agenten, bei dem multiagent gesetzt ist, lässt die Erstellungs- oder Update-Anfrage mit einem 400-Validierungsfehler fehlschlagen.
• 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 Subagenten 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 den Agenten referenziert. Der Agent delegiert bei Bedarf an die Agenten, die du in der predefined_agents-Liste von subagents auflistest. Er kann auch an Inline-Agenten delegieren, sofern du sie nicht deaktivierst.

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

Agenten mit MCP-Servern verbinden

MCP-Server sind agentenbezogen: 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 sind sessionbezogen: 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, Vault-Anmeldedaten 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, und 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 Recherche-Agenten, der den GitHub-MCP-Server deklariert, und den Agenten, der an den Recherche-Agenten delegiert:

# Erstelle den Researcher und lies dann seine ID aus der Lockfile.
ant apply researcher.md
research_agent_id=$(jq -er '.resources["./researcher.md"].id' claude-lock.json)

# Schreibe die Definition des Agenten und liste den Researcher per ID auf.
cat > lead.md <<EOF
---
name: lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: enabled
    predefined_agents:
      - type: agent
        id: $research_agent_id
---
EOF

# Erstelle den Agenten.
ant apply lead.md 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 Recherche-Agent den GitHub-MCP-Server, daher hat der Agent, den die Session ausführt, keinen Zugriff. Die vault_ids der Session liefern die GitHub-Anmeldedaten an den Thread des Recherche-Agenten.

Threads

Der Session-Thread jedes Agenten hat seinen eigenen Event-Stream. Um Threads aufzulisten, zu unterbrechen oder zu archivieren, ihre Events zu lesen und Tool-Berechtigungen über sie hinweg zu handhaben, siehe Session-Threads.

Dynamische Workflows

Mit dynamischen Workflows kann ein Agent Arbeit mit vielen Teilen übernehmen, etwa das Überprüfen von Hunderten von Dokumenten oder das Gegenprüfen vieler Quellen. 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 workflows-Einstellung im multiagent-Block des Agenten ein oder aus. Die Agenten eines Runs können gleichzeitig arbeiten, sodass eine lange Aufgabe schneller fertig werden kann, als wenn ein Agent jeden 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. Siehe Workflow-Runs für die Events, Unterbrechungen, Limits und was die Threads eines Runs zeigen.

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. Nur für dynamische Workflows füge "subagents": {"type": "disabled"} hinzu.

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

ant apply contract-reviewer.md

---
name: Contract Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
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 sein Standardwert „aktiviert“ ist. Dasselbe gilt für subagents.
• Bestehende Sessions: Eine Session kopiert die Einstellung bei ihrer Erstellung, 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 aufgelistet werden und auch nicht in der predefined_agents-Liste von workflows in einem anderen Agenten. Ein Agent kann sich selbst in jeder der beiden Listen mit {"type": "self"} auflisten, was beim Auslesen als seine eigene id und version zurückgegeben wird.
• 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. Eine neue Session wird ebenfalls 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, mit dem du dynamische Workflows aktivierst, oder entferne es. Siehe Benutzerdefinierte Tools.
• Budget: Lege beim Erstellen der Session ein Session-Budget fest, um die Ausgaben der Session einschließlich der Runs zu begrenzen; du kannst einer bestehenden Session 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

Durch das Aktivieren dynamischer Workflows erhält der Agent die Fähigkeit, Workflow-Runs zu starten. Der Agent bestimmt, 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 aus 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 in der Domäne deines Agenten, die einen Run erfordern, sowie 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 erneut bearbeitet und erneut geprüft.“
• Was zu tun ist, wenn ein Agent fehlschlägt: „Das Fehlschlagen eines Agenten darf den Run nicht fehlschlagen lassen. Wenn ein Agent einen Vertrag nicht lesen kann, liste 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 du es bei jedem Agenten tun würdest, 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, dazu, 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 für strategische Orientierung konsultieren kann, etwa um einen Ansatz zu planen, aus einer Sackgasse herauszukommen oder Arbeit vor dem Abschluss zu überprüfen. Die Einstellung ist standardmäßig deaktiviert. Um sie zu aktivieren, setze advisor auf {"type": "enabled", "model": "..."}, das 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, sind also beide aktiviert, und der Agent kann auch an Inline-Agenten delegieren und Workflow-Runs starten. 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 eine Mindestanforderung an die Leistungsfähigkeit 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 und erneut beim Erstellen einer Session mit einem 400-Validierungsfehler abgelehnt. Die Kombination 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 Kombinationen richten sich nach der Tabelle zur Modellkompatibilität des Advisor-Tools.

Der Advisor ist auch als Server-Tool in der Messages API verfügbar. Bei Managed Agents unterscheiden sich Konfiguration und Zustellung: Die advisor-Einstellung hat keine Felder max_uses, max_tokens oder caching, und 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 erzeugter 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 gibt die Standard-Thread-Events aus, gekennzeichnet durch den reservierten Namen anthropic.advisor (die Thread-Lebenszyklus-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 ausgegeben, 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 dafür, dass der Ratschlag bereits zugestellt wurde.

Ob dein Client den Ratschlag lesen kann, hängt von der Richtlinie des Advisor-Modells ab. Sie spiegelt die Aufteilung der Ergebnisvarianten beim Advisor-Tool der Messages API wider. Ein Advisor-Modell, das dort Klartext-Ergebnisse zurückgibt, liefert hier lesbaren Text. Eines, das geschwärzte Ergebnisse zurückgibt, 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 für dich verfügbare Opus-Modell als Advisor. Claude Opus 5.5 gibt geschwärzte Ergebnisse zurück, daher sieht dein Client nur den Platzhalter. Um den Ratschlag im Event-Stream zu lesen, verwende einen Advisor, der Klartext zurückgibt, 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 Agentenmodelle lassen sich nur mit Advisors kombinieren, die geschwärzte Ergebnisse liefern; siehe die Kompatibilitätstabelle des Advisor-Tools. Das Nachdenken des Advisors wird nie angezeigt. 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 Kind-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 Seiten des Advisors 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. Sie werden außerdem zum Listenpreis des Advisor-Modells auf ein Session-Budget angerechnet. Jede Konsultation sendet dem Advisor die bisherige Konversation des primären Threads, sodass Konsultationen spät in einer langen Session mehr Input-Token verbrauchen.

Den Advisor entfernen

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

Vom Typ coordinator umstellen

Wie multiagent_20261001 ermöglicht 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 aktuelle 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 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, sodass beide ihren Standardwert erhalten und aktiviert sind. Der umgestellte Agent kann außerdem 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"}, um das Delegieren deaktiviert zu lassen. 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 es das Beispiel tut. 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.