Subagenten

Subagenten sind spezialisierte AI-Assistenten, an die der Cursor-Agent Aufgaben delegieren kann. Jeder Subagent arbeitet in einem eigenen Kontextfenster, übernimmt bestimmte Arten von Aufgaben und gibt sein Ergebnis an den übergeordneten Agenten zurück. Nutze Subagenten, um komplexe Aufgaben aufzuteilen, parallel zu arbeiten und den Kontext in der Hauptunterhaltung zu bewahren.

Du kannst Subagenten im Editor, in der CLI und in Cloud Agents verwenden.

So funktionieren Subagenten

Wenn Agent auf eine komplexe Aufgabe trifft, kann er automatisch einen Subagenten starten. Der Subagent erhält einen Prompt mit allen erforderlichen Kontextinformationen, arbeitet autonom und gibt abschließend eine Nachricht mit seinen Ergebnissen zurück.

Subagenten starten mit einem leeren Kontext. Der übergeordnete Agent fügt dem Prompt relevante Informationen hinzu, da Subagenten keinen Zugriff auf den bisherigen Unterhaltungsverlauf haben.

Vordergrund vs. Hintergrund

Subagenten werden in einem von zwei Modi ausgeführt:

Integrierte Subagenten

Cursor enthält drei integrierte Subagenten, die kontextintensive Vorgänge automatisch übernehmen. Diese Subagenten wurden auf Grundlage der Analyse von Agentenunterhaltungen entwickelt, in denen die Grenzen des Kontextfensters erreicht wurden.

Warum es diese Subagenten gibt

Diese drei Operationen haben gemeinsame Merkmale: Sie erzeugen umfangreiche Zwischenausgaben, profitieren von spezialisierten Prompts und Tools und können viel Kontext verbrauchen. Die Ausführung als Subagenten löst mehrere Probleme:

• Kontextisolierung — Zwischenausgaben bleiben im Subagenten. Der übergeordnete Agent sieht nur die abschließende Zusammenfassung.
• Modellflexibilität — Der Explore-Subagent verwendet standardmäßig ein schnelleres Modell. Dadurch lassen sich 10 parallele Suchen in der Zeit ausführen, die eine einzelne Suche des Hauptagenten benötigen würde.
• Spezialisierte Konfiguration — Jeder Subagent verfügt über Prompts und Tool-Zugriff, die auf seine spezifische Aufgabe abgestimmt sind.
• Kosteneffizienz — Schnellere Modelle kosten weniger. Die Auslagerung tokenintensiver Arbeit an Subagenten mit geeigneter Modellauswahl reduziert die Gesamtkosten.

Du musst diese Subagenten nicht konfigurieren. Agent verwendet sie bei Bedarf automatisch.

Wann Subagents sinnvoll sind

Schnellstart

Agent verwendet Subagents bei Bedarf automatisch. Du kannst auch einen benutzerdefinierten Subagent erstellen, indem du Agent fragst:

Für mehr Kontrolle kannst du benutzerdefinierte Subagents manuell in deinem Projekt- oder Nutzerverzeichnis erstellen.

Benutzerdefinierte Subagenten

Definieren Sie benutzerdefinierte Subagenten, um spezialisiertes Wissen zu hinterlegen, Teamstandards durchzusetzen oder wiederkehrende Workflows zu automatisieren.

Speicherorte

Bei Namenskonflikten haben Projekt-Subagents Vorrang. Wenn mehrere Speicherorte Subagents mit demselben Namen enthalten, hat .cursor/ Vorrang vor .claude/ und .codex/.

Dateiformat

Jeder Subagent ist eine Markdown-Datei mit YAML-Frontmatter:

---name: security-auditordescription: Security specialist. Use when implementing auth, payments, or handling sensitive data.model: inheritreadonly: true---You are a security expert auditing code for vulnerabilities.When invoked:1. Identify security-sensitive code paths2. Check for common vulnerabilities (injection, XSS, auth bypass)3. Verify secrets are not hardcoded4. Review input validation and sanitizationReport findings by severity:- Critical (must fix before deploy)- High (fix soon)- Medium (address when possible)

Konfigurationsfelder

Modellkonfiguration

Das Feld model legt fest, welches Modell ein Subagent verwendet. Es gibt zwei Optionen:

Wähle inherit, wenn der Subagent dieselbe Denkleistung wie der übergeordnete Agent benötigt. Verwende eine bestimmte Modell-ID, wenn du die Funktionen eines bestimmten Modells benötigst – unabhängig davon, welches Modell der übergeordnete Agent verwendet.

Modellparameter

Fügen Sie einer Modell-ID eckige Klammern hinzu, um modellspezifische Optionen wie Geschwindigkeit, Denkaufwand und Kontextfenster festzulegen. Geben Sie Optionen als id=value-Paare an und trennen Sie mehrere Optionen durch Kommas.

Die verfügbaren Optionen hängen vom Modell ab und verwenden dieselben id=value-Paare wie die Modellparameter des SDK's.

---name: plannerdescription: Plans complex changes before implementation.model: claude-opus-5[effort=high]---Break the task into a clear, ordered implementation plan.

Wenn das konfigurierte Modell nicht verwendet wird

Cursor verwendet das Feld model im Frontmatter deines Subagents, sofern keine der folgenden Bedingungen zutrifft:

• Einschränkungen durch Team-Admins — Der Admin deiner Organisation hat das angegebene Modell blockiert.
• Legacy-Max-Modus-Einstellung — Bei einem Legacy-anfragebasierten Plan erfordert das Modell den Max-Modus, der bei dir nicht aktiviert ist.
• Planbeschränkungen — Das Modell ist in deinem aktuellen Plan nicht verfügbar.

In diesen Fällen greift Cursor auf ein kompatibles Modell zurück. Wenn sich ein Modell unerwartet verhält, überprüfe deinen Plan und deine Modelleinstellungen.

---name: code-reviewerdescription: Reviews code for correctness and style.model: inherit---Review the code changes for bugs, style issues, and edge cases.

---name: search-agentdescription: Searches the codebase for relevant files and symbols.model: inherit---Search the codebase and return relevant file paths and code snippets.

---name: reasoning-agentdescription: Handles complex architectural decisions.model: gpt-5.6-sol---Analyze the architecture and recommend changes with detailed reasoning.

Subagents verwenden

Automatische Delegierung

Der Agent delegiert Aufgaben proaktiv anhand von:

• Komplexität und Umfang der Aufgabe
• Benutzerdefinierten Subagent-Beschreibungen in deinem Projekt
• Aktuellem Kontext und verfügbaren Tools

Füge in deinem Beschreibungsfeld Formulierungen wie „proaktiv nutzen“ oder „stets verwenden für“ hinzu, um die automatische Delegierung zu fördern.

Expliziter Aufruf

Fordere einen bestimmten Subagent an, indem du in deinem Prompt die Syntax /name verwendest:

> /verifier confirm the auth flow is complete> /debugger investigate this error> /security-auditor review the payment module

Du kannst Subagenten auch durch natürliche Erwähnung aufrufen:

> Nutze den Verifier-Subagenten, um zu bestätigen, dass der Authentifizierungsablauf abgeschlossen ist> Bitte den Debugger-Subagenten, diesen Fehler zu untersuchen> Setze den Sicherheits-Auditor-Subagenten für das Zahlungsmodul ein

Parallele Ausführung

Starte mehrere Subagenten gleichzeitig, um den Durchsatz zu maximieren:

> Prüfe die API-Änderungen und aktualisiere parallel die Dokumentation

Der Agent sendet mehrere Task-Tool-Aufrufe in einer einzigen Nachricht, sodass Subagenten gleichzeitig ausgeführt werden.

Cloud-Subagent

Aus einer lokalen Agent-Session kannst du Aufgaben an einen Cloud-Subagent delegieren, der auf einer eigenen VM und einem eigenen Branch läuft. Dein lokaler Workspace bleibt sauber und reaktionsfähig, während lang laufende oder parallele Aufgaben in der Cloud erledigt werden. Der übergeordnete Agent läuft lokal oder in der Cloud ohne Unterbrechung weiter. Cloud-Subagent werden über das Agents Window in der Cursor-Desktop-App ausgeführt.

Einen Cloud-Subagent mit /in-cloud starten

Gib /in-cloud ein. Die nächste Aufgabe, die du übermittelst, wird als Cloud-Subagent ausgeführt. Er startet eine eigene VM und einen eigenen Branch, um die Aufgabe zu bearbeiten.

Das ist nützlich, um lang laufende oder parallele Aufgaben zu isolieren, etwa zum Beheben von CI-Problemen, zum Untersuchen eines Issues oder zum Erkunden einer Codebasis, während du lokal weiterarbeitest.

Eine PR mit /babysit betreuen

Bitte einen Cloud-Subagenten mit /babysit oder per Klick auf die Schnellaktions-Schaltfläche, einen Pull Request zu betreuen. Der Cloud-Agent arbeitet remote iterativ daran, die PR für den Merge vorzubereiten, ohne deine lokale Session zu blockieren.

Cloud-Subagenten verwenden die für dein Repo konfigurierte Umgebung und befolgen dieselben Modell- und Funktionsregeln wie andere Cloud Agents. Da sie auf einer Cloud-VM laufen, stammen ihre MCP-Server aus der Konfiguration deines Teams unter cursor.com/agents und nicht aus deiner lokalen Session.

Subagents fortsetzen

Subagents lassen sich fortsetzen, um frühere Unterhaltungen weiterzuführen. Das ist nützlich für lang laufende Aufgaben, die mehrere Aufrufe umfassen.

Jede Ausführung eines Subagents gibt eine Agent-ID zurück. Übergeben Sie diese ID, um den Subagent mit vollständig erhaltenem Kontext fortzusetzen:

> Setze Agent abc123 fort und analysiere die verbleibenden Testfehler

Häufige Muster

Verifizierungsagent

Ein Verifizierungsagent prüft unabhängig, ob behauptete Arbeit tatsächlich abgeschlossen wurde. Dies behebt ein häufiges Issue, bei dem AI Aufgaben als erledigt markiert, die Implementierung jedoch unvollständig oder fehlerhaft ist.

---name: verifierdescription: Validates completed work. Use after tasks are marked done to confirm implementations are functional.---You are a skeptical validator. Your job is to verify that work claimed as complete actually works.When invoked:1. Identify what was claimed to be completed2. Check that the implementation exists and is functional3. Run relevant tests or verification steps4. Look for edge cases that may have been missedBe thorough and skeptical. Report:- What was verified and passed- What was claimed but incomplete or broken- Specific issues that need to be addressedDo not accept claims at face value. Test everything.

Dieses Muster eignet sich für:

• Die End-to-End-Validierung von Features vor dem Abschließen von Tickets
• Das Erkennen unvollständig implementierter Funktionalität
• Sicherzustellen, dass Tests tatsächlich erfolgreich durchlaufen (nicht nur, dass Testdateien vorhanden sind)

Orchestrator-Muster

Bei komplexen Workflows kann ein übergeordneter Agent mehrere spezialisierte Subagenten nacheinander koordinieren:

1. Planer analysiert die Anforderungen und erstellt einen technischen Plan
2. Implementierer setzt das Feature anhand des Plans um
3. Prüfer stellt sicher, dass die Implementierung den Anforderungen entspricht

Jede Übergabe enthält strukturierte Ergebnisse, damit der nächste Agent über einen klaren Kontext verfügt.

Beispiel-Subagents

Debugger

---name: debuggerdescription: Spezialist für Debugging von Fehlern und fehlgeschlagenen Tests. Bei Issues verwenden.---Du bist ein erfahrener Debugger mit Spezialisierung auf Ursachenanalyse.Bei Aufruf:1. Fehlermeldung und Stacktrace erfassen2. Schritte zur Reproduktion ermitteln3. Fehlerstelle eingrenzen4. Minimalen Fix implementieren5. Überprüfen, ob die Lösung funktioniertFür jedes Issue bereitstellen:- Erklärung der Fehlerursache- Belege für die Diagnose- Konkreter Code-Fix- TestansatzKonzentriere dich darauf, das zugrunde liegende Issue zu beheben, nicht nur die Symptome.

Test-Runner

---name: test-runnerdescription: Experte für Testautomatisierung. Führe proaktiv Tests aus und behebe Fehler.---Du bist ein Experte für Testautomatisierung.Wenn du Codeänderungen siehst, führe proaktiv geeignete Tests aus.Wenn Tests fehlschlagen:1. Analysiere die Fehlerausgabe2. Ermittle die zugrunde liegende Ursache3. Behebe das Problem unter Wahrung der Testabsicht4. Führe die Tests erneut aus, um dies zu verifizierenBerichte zu den Testergebnissen:- Anzahl der bestandenen/fehlgeschlagenen Tests- Zusammenfassung etwaiger Fehler- Änderungen zur Behebung der Probleme

Best Practices

• Erstelle fokussierte Subagents — Jeder Subagent sollte eine einzige, klar abgegrenzte Aufgabe haben. Vermeide allgemeine „Helfer“-Agenten.
• Investiere in Beschreibungen — Das Feld description bestimmt, wann Agent an deinen Subagent delegiert. Nimm dir Zeit, es zu optimieren. Teste dies mit Prompts und überprüfe, ob der richtige Subagent ausgelöst wird.
• Halte Prompts prägnant — Lange, ausschweifende Prompts verwässern den Fokus. Sei spezifisch und direkt.
• Nimm Subagents in die Versionskontrolle auf — Checke .cursor/agents/ in dein Repository ein, damit das Team davon profitiert.
• Beginne mit von Agent generierten Agents — Lass Agent dir beim Entwurf der ersten Konfiguration helfen und passe sie anschließend an.
• Verwende Hooks für die Dateiausgabe — Wenn Subagents strukturierte Ausgabedateien erzeugen sollen, erwäge Hooks, um ihre Ergebnisse konsistent zu verarbeiten und zu speichern.

Anti-Patterns, die du vermeiden solltest

• Vage Beschreibungen — „Für allgemeine Aufgaben verwenden“ gibt dem Agent keine Hinweise darauf, wann er delegieren soll. Sei konkret: „Verwenden, wenn Authentifizierungsabläufe mit OAuth-Providern implementiert werden.“
• Übermäßig lange Prompts — Ein Prompt mit 2.000 Wörtern macht einen Subagent nicht intelligenter. Er macht ihn langsamer und schwerer wartbar.
• Slash-Befehle duplizieren — Wenn eine Aufgabe nur einem Zweck dient und keine Kontextisolierung benötigt, verwende stattdessen einen Skill oder Befehl.
• Zu viele Subagents — Beginne mit 2–3 fokussierten Subagents. Füge weitere nur hinzu, wenn du klare, unterschiedliche Anwendungsfälle hast.

Subagents verwalten

Subagents erstellen

Am einfachsten erstellst du einen Subagent, indem du Agent darum bittest:

Du kannst Subagents auch manuell erstellen, indem du Markdown-Dateien zu .cursor/agents/ (Projekt) oder ~/.cursor/agents/ (Nutzer) hinzufügst.

Subagents anzeigen

Agent enthält alle benutzerdefinierten Subagents in den verfügbaren Tools. Welche Subagents konfiguriert sind, siehst du im Verzeichnis .cursor/agents/ deines Projekts.

Leistung und Kosten

Subagenten haben Vor- und Nachteile. Wenn du sie verstehst, kannst du entscheiden, wann du sie einsetzen solltest.

Überlegungen zu Tokens und Kosten

• Subagents verbrauchen Tokens unabhängig voneinander — Jeder Subagent hat sein eigenes Kontextfenster und seinen eigenen Tokenverbrauch. Die parallele Ausführung von fünf Subagents verbraucht etwa fünfmal so viele Tokens wie ein einzelner Agent.
• Mehraufwand abwägen — Bei schnellen, einfachen Aufgaben ist der Hauptagent oft schneller. Subagents sind besonders bei komplexen, lang laufenden oder parallelen Aufgaben sinnvoll.
• Subagents können langsamer sein — Der Vorteil ist Kontextisolation, nicht Geschwindigkeit. Ein Subagent, der eine einfache Aufgabe erledigt, kann langsamer sein als der Hauptagent, weil er ohne Kontext startet.

FAQ