Zum Hauptinhalt springen
Subagenten ermöglichen es dem Hauptagenten, unabhängige Worker zu starten, die Teilaufgaben übernehmen. Ein Subagent teilt Tools und den Kontext der Codebasis mit dem übergeordneten Agenten, arbeitet jedoch in einem eigenen Unterhaltungsstrang — er übernimmt nicht den Unterhaltungsverlauf des übergeordneten Agenten. Das ist nützlich für Aufgaben, die von fokussierter, unabhängiger Arbeit profitieren — etwa beim Erkunden einer Codebasis, beim Ausführen von Tests oder bei der parallelen Implementierung eines Features. Sie können den Agenten ausdrücklich bitten, Subagenten zu verwenden (z. B. „recherchiere in einem Subagenten, wie Authentifizierung funktioniert“), oder der Agent kann selbst entscheiden, einen Subagenten zu beauftragen, wenn er feststellt, dass eine Aufgabe von unabhängiger Arbeit profitieren würde. In unseren Messungen verbessern Subagenten sowohl die Gesamtleistung beim Programmieren als auch reduzieren sie die Kosten.

So funktionieren Subagents

Wenn der Agent einen Subagent startet, wählt er eines der verfügbaren Subagent-Profile aus und legt fest, ob der Subagent im Vordergrund oder im Hintergrund ausgeführt werden soll. Subagents können in zwei Modi ausgeführt werden:

Vordergrund

Läuft direkt in Ihrer Sitzung. Der übergeordnete Agent pausiert und wartet, bis der Subagent fertig ist, bevor er fortfährt. Sie können Tool-Aufrufe genehmigen oder ablehnen, wenn sie anfallen.

Hintergrund

Läuft parallel, während der übergeordnete Agent weiterarbeitet. Der übergeordnete Agent wird automatisch benachrichtigt, wenn der Subagent abgeschlossen ist. Nicht genehmigte Tools werden automatisch abgelehnt.
Sie sehen die Rohausgabe des Subagenten nicht direkt. Wenn ein Subagent fertig ist, liest der übergeordnete Agent das Ergebnis und fasst die wichtigsten Befunde und Maßnahmen für Sie zusammen.

Subagent-Kosten

Subagenten laufen als eigenständige Agent-Sitzungen, jeweils mit eigenem Kontextfenster und eigenen Inferenzaufrufen, und verursachen daher unabhängig vom übergeordneten Agenten Kosten. Die Ausgaben des übergeordneten Agenten decken nur seine eigene Arbeit ab; jeder Subagent, den er startet, verursacht darüber hinaus eigene Nutzung.
Bei promptbasierten Tarifen verbraucht jeder Subagent zusätzliche Credits, genau wie eine Nutzernachricht. Die Anzahl der Credits hängt vom Modell ab, das der Subagent verwendet. Daher verbrauchen Aufgaben, die mehrere Subagenten starten (oder verschachteln), mehr Credits.
Da die Kosten mit der Anzahl der Subagenten steigen, sind Aufgaben teurer, die auf viele Subagenten aufgeteilt werden (oder diese verschachteln). Setze Subagenten gezielt ein, wenn sich die Parallelisierung oder der fokussierte Kontext trotz der zusätzlichen Ausgaben lohnt.

Welches Modell verwendet ein Subagent?

Subagenten laufen nicht alle mit dem Modell, das Sie in der Modellauswahl ausgewählt haben. Jedes Profil bestimmt, woher sein Modell stammt:
subagent_general übernimmt das Modell des übergeordneten Agenten. Wenn Sie ein Premium-Modell verwenden, läuft jeder allgemeine Subagent ebenfalls mit diesem Premium-Modell, mit eigenem Kontextfenster und eigenen Inferenzaufrufen — eine Aufgabe, die auf mehrere allgemeine Subagenten verteilt wird, vervielfacht also Ihre Kosten. Fordern Sie einen Explore-Subagenten an (oder einen benutzerdefinierten Subagenten mit einem günstigeren, angepinnten model:), wenn es bei der Arbeit eher um Recherche als um Codeänderungen geht.
Das Standard-Subagent-Modell ist kein fester Modellname — es wird beim Start über einen Router aufgelöst, und ein Admin kann ihn überschreiben (siehe unten). Mit der Standard-Einstellung Subagent router wird es zu SWE-1.6 aufgelöst (je nach Plan-Ebene als schnellere oder langsamere SWE-1.6-Variante).
Die CLI kennzeichnet im Subagent-Panel derzeit nicht, welches Modell ein laufender Subagent verwendet.

Das Modell beeinflussen

Es gibt keine Möglichkeit, in einem Prompt ein Modell für einen Subagenten festzulegen — das Tool run_subagent verwendet ein Profil, kein Modell. Sie haben zwei Möglichkeiten:
  1. Geben Sie ein Profil in natürlicher Sprache an. Wenn Sie einen Explore-Subagenten anfordern („Untersuche in einem Explore-Subagenten, wie Auth funktioniert“), bleibt die Aufgabe beim günstigen Standardmodell für Subagenten. Wenn Sie um Codeänderungen bitten, erhalten Sie subagent_general, das auf dem von Ihnen ausgewählten Modell läuft.
  2. Pinnen Sie ein Modell in einem Profil für einen benutzerdefinierten Subagenten an. model: in AGENT.md ist die einzige Möglichkeit, einen Subagenten mit Schreibzugriff auf einem anderen Modell als dem des übergeordneten Agenten auszuführen. Ein Skill, der in einem Subagenten ausgeführt wird, kann außerdem model: in seinem Frontmatter festlegen, um das Modell des Profils zu überschreiben.

Enterprise-Steuerung

Administrator:innen können über die Einstellung Standard-Subagent-Modell in den org-/Enterprise-Settings festlegen, welches Modell Subagenten verwenden — und ob Subagenten überhaupt zum Einsatz kommen. Diese Einstellung steuert das Modell für subagent_explore und für benutzerdefinierte Subagenten, die kein model: anpinnen — sie ändert nicht subagent_general, das immer dem Modell des übergeordneten Agenten folgt.
Einstellung für das Standardmodell von Subagenten
Es gibt drei Optionen:

Subagent-Profile

Jeder Subagent verwendet ein spezifisches Profil, das seine Fähigkeiten bestimmt. Es gibt zwei integrierte Profile:
Der Agent wählt anhand der Aufgabe automatisch das passende Profil aus. Explore-Subagents sind ideal für Recherche und zum Verstehen, während allgemeine Subagents Änderungen vornehmen können. Unter Welches Modell verwendet ein Subagent? erfahren Sie, wie jedes Profil sein Modell auswählt — die beiden Profile laufen nicht auf demselben Modell.
Sie können auch eigene benutzerdefinierte Subagent-Profile definieren — siehe Custom Subagents weiter unten.

Tool-Berechtigungen

Wie Tool-Berechtigungen funktionieren, hängt davon ab, ob der Subagent im Vordergrund oder im Hintergrund ausgeführt wird:
  • Subagenten im Vordergrund verhalten sich wie der Hauptagent — Sie werden wie gewohnt aufgefordert, Tool-Aufrufe zuzulassen oder abzulehnen.
  • Subagenten im Hintergrund übernehmen alle Tool-Berechtigungen, die Sie in der aktuellen Sitzung bereits erteilt haben. Jedes Tool, das nicht vorab genehmigt wurde, wird automatisch abgelehnt. Subagenten im Hintergrund können keine neuen Berechtigungen anfordern.
Wenn ein Subagent im Hintergrund fehlschlägt, weil ein erforderliches Tool abgelehnt wurde, können Sie ihn im Vordergrund fortsetzen, um die erforderlichen Berechtigungen zu erteilen. Weitere Informationen finden Sie unten unter Subagenten fortsetzen.

Subagents überwachen

Subagent-Indikator

Wenn Subagents im Hintergrund laufen, erscheint unter dem Eingabebereich ein Indikator, der ihren Status anzeigt. Sie können zum Indikator wechseln, indem Sie im Eingabebereich drücken und dann Enter, um das Subagent-Panel zu öffnen. Wenn ein Subagent im Vordergrund läuft, zeigt das Ladesymbol „Subagent wird ausgeführt · Ctrl+B, um ihn im Hintergrund auszuführen“ an.

Subagent-Panel

Im Subagent-Panel können Sie alle aktiven und beendeten Subagents anzeigen und verwalten. Es zeigt für jeden Subagent das Profil, den Titel, den Status, die verstrichene Zeit und die Anzahl der Tool-Aufrufe an.

Wechsel zwischen Vordergrund und Hintergrund

Du kannst Subagents während der Ausführung zwischen Vordergrund und Hintergrund verschieben:
  • Einen Subagent aus dem Vordergrund in den Hintergrund verschieben: Drücke Ctrl+B, während ein Subagent im Vordergrund läuft. Der Subagent arbeitet im Hintergrund weiter, und der übergeordnete Agent setzt seine Arbeit fort.
  • Einen Subagent aus dem Hintergrund in den Vordergrund holen: Öffne das Subagent-Panel und drücke f bei einem laufenden Subagent im Hintergrund. Die Ausgabe des Subagents wird inline angezeigt.
Wenn du einen Subagent in den Hintergrund verschiebst, ist der Tool-Aufruf des übergeordneten Agenten bereits zurückgekehrt, sodass der übergeordnete Agent unabhängig weiterarbeitet. Das Ergebnis des Subagents fließt nicht in die aktuelle Pipeline des übergeordneten Agenten zurück, aber du wirst benachrichtigt, wenn er fertig ist.

Subagents abbrechen

Sie können einen laufenden Subagent auf zwei Arten abbrechen:
  1. Über das Subagent-Panel: Öffnen Sie das Panel und drücken Sie bei einem laufenden Subagenten x.
  2. Subagent im Vordergrund: Drücken Sie Ctrl+C oder Esc, um den aktuell im Vordergrund laufenden Subagenten abzubrechen.

Subagenten fortsetzen

Abgebrochene, fehlgeschlagene oder abgeschlossene Subagenten können mit einem neuen Prompt fortgesetzt werden. Du kannst den Agenten bitten, einen Subagenten fortzusetzen; er macht dann dort weiter, wo er aufgehört hat. Fortgesetzte Subagenten werden immer im Vordergrund ausgeführt, sodass du alle Tool-Aufrufe genehmigen kannst, die zuvor abgelehnt wurden. Das ist besonders nützlich, wenn:
  • Ein Subagent im Hintergrund fehlgeschlagen ist, weil ein erforderlicher Tool-Aufruf abgelehnt wurde — setze ihn im Vordergrund fort, um die nötigen Berechtigungen zu erteilen.
  • Ein Subagent abgeschlossen ist, du aber möchtest, dass er auf Grundlage seiner Befunde weitere Folgearbeiten ausführt.
  • Ein Subagent vorzeitig abgebrochen wurde und du möchtest, dass er weiterläuft.

Verschachtelungstiefe

Standardmäßig können Subagents keine eigenen Subagents starten — das kann nur der Root-Agent. Subagent-Tools (run_subagent und read_subagent) sind innerhalb eines Subagents deaktiviert, um eine unbegrenzte Verschachtelung zu verhindern. Benutzerdefinierte Subagent-Profile können jedoch die verschachtelte Erstellung aktivieren, indem sie das Feld max-nesting in ihrem Frontmatter festlegen. Dieser Wert überschreibt die Standard-Maximaltiefe und erlaubt es Subagents, untergeordnete Agents zu starten, solange der Baum innerhalb dieses Limits bleibt. Zum Beispiel erlaubt max-nesting: 3 die folgende Kette:
Verschachtelte Subagents können die Kosten erheblich steigern. Jede Verschachtelungsebene startet zusätzliche Agenten mit eigenen Kontextfenstern und Inferenzaufrufen. Setze diese Funktion gezielt ein.

Benutzerdefinierte Subagents

Benutzerdefinierte Subagents sind experimentell. Das Format, das Verhalten und die Konfigurationsoptionen können sich in zukünftigen Versionen ändern.
Zusätzlich zu den integrierten Profilen subagent_explore und subagent_general können Sie eigene benutzerdefinierte Subagent-Profile definieren. Mit benutzerdefinierten Subagents können Sie spezialisierte Subagents mit eigenen Systemprompts, Tooleinschränkungen, Modell-Overrides und Berechtigungen erstellen — zugeschnitten auf bestimmte Aufgaben in Ihrem Workflow. Dies ist auch die Möglichkeit, einen schreibfähigen Subagent zu erhalten, der nicht auf Ihrem (möglicherweise teuren) primären Modell läuft: Geben Sie ihm ein model: und die Tools, die er benötigt.

Einen Custom Subagent erstellen

Benutzerdefinierte Subagenten werden als AGENT.md-Dateien in einem benannten Verzeichnis unter agents/ definiert. Der Verzeichnisname wird zur Kennung des Profils.
Ebenfalls unterstützt:

AGENT.md-Format

Eine AGENT.md-Datei verwendet dasselbe YAML-Frontmatter wie Skills, gefolgt vom System-Prompt des Subagenten:

Frontmatter-Felder

Wie Custom Subagents verwendet werden

Sobald benutzerdefinierte Subagent-Profile definiert sind, erscheinen sie neben den integrierten Profilen. Der Agent sieht eine Beschreibung jedes verfügbaren Profils und wählt beim Erstellen eines Subagenten das am besten geeignete aus. Sie können den Agenten auch bitten, ein bestimmtes Profil anhand seines Namens zu verwenden (z. B. „Prüfe diesen Code mit dem Reviewer-Subagenten“). Benutzerdefinierte Subagent-Profile, deren Namen mit dem eines integrierten Profils kollidieren (z. B. subagent_explore, subagent_general), werden mit einer Warnung übersprungen.

Importieren aus anderen Tools

Benutzerdefinierte Subagenten werden auch im Agent-Format von Claude Code importiert:
Claude-Code-Agent-Dateien verwenden im frontmatter tools statt allowed-tools. Beide Formate werden automatisch unterstützt.

Beispiele

Schreibgeschützter Recherche-Agent

Agent für Testausführung