So funktionieren Subagents
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
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.
Welches Modell verwendet ein Subagent?
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
run_subagent verwendet ein Profil, kein Modell. Sie haben zwei Möglichkeiten:
- 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. - Pinnen Sie ein Modell in einem Profil für einen benutzerdefinierten Subagenten an.
model:inAGENT.mdist 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ßerdemmodel:in seinem Frontmatter festlegen, um das Modell des Profils zu überschreiben.
Enterprise-Steuerung
subagent_explore und für benutzerdefinierte Subagenten, die kein model: anpinnen — sie ändert nicht subagent_general, das immer dem Modell des übergeordneten Agenten folgt.

Subagent-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.
Tool-Berechtigungen
- 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.
Subagents überwachen
Subagent-Indikator
Subagent-Panel
Wechsel zwischen Vordergrund und Hintergrund
- 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
- Über das Subagent-Panel: Öffnen Sie das Panel und drücken Sie bei einem laufenden Subagenten x.
- Subagent im Vordergrund: Drücken Sie Ctrl+C oder Esc, um den aktuell im Vordergrund laufenden Subagenten abzubrechen.
Subagenten fortsetzen
- 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
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:
Benutzerdefinierte Subagents
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
AGENT.md-Dateien in einem benannten Verzeichnis unter agents/ definiert. Der Verzeichnisname wird zur Kennung des Profils.
- Projektspezifisch
- Global
AGENT.md-Format
AGENT.md-Datei verwendet dasselbe YAML-Frontmatter wie Skills, gefolgt vom System-Prompt des Subagenten:
Frontmatter-Felder
Wie Custom Subagents verwendet werden
subagent_explore, subagent_general), werden mit einer Warnung übersprungen.
Importieren aus anderen Tools
Claude-Code-Agent-Dateien verwenden im
frontmatter tools statt allowed-tools. Beide Formate werden automatisch unterstützt.
