Zum Hauptinhalt springen

Konfiguration und Verwendung von Subagenten in Cursor

Cursor Subagenten-Leitfaden

Subagenten in Cursor ermöglichen es Ihnen, komplexe Aufgaben in kleinere, spezialisierte Einheiten zu zerlegen, die parallel oder sequenziell ausgeführt werden können. Ein Planer-Agent orchestriert die Gesamtaufgabe, während Subagenten spezifische Teilaufgaben mit ihren eigenen Modellen, Scopes und Sicherheitsgrenzen bearbeiten. Dieser Leitfaden behandelt alles von der Modellauswahl bis zur Sicherheitskonfiguration und hilft Ihnen, robuste Multi-Agenten-Workflows zu erstellen.

Subagenten verstehen​

Was sind Subagenten?​

Subagenten sind unabhängige Agent-Instanzen, die unter der Leitung eines Planer-Agenten arbeiten. Jeder Subagent kann eigene haben:

  • Modell: Verschiedene KI-Modelle für verschiedene Aufgabentypen
  • Scope: Eingeschränkter Datei- und Verzeichniszugriff
  • Sicherheitsgrenzen: Beschränkungen, welche Aktionen sie ausführen können
  • Kontext: Isoliertes Kontextfenster zur Verhinderung von Interferenzen

Der Planer-Agent zerlegt eine komplexe Aufgabe, weist Teilaufgaben an Subagenten zu, sammelt deren Ergebnisse und synthetisiert eine finale Ausgabe. Diese Architektur spiegelt wider, wie menschliche Teams Arbeit unter Spezialisten aufteilen.

Wann Subagenten verwendet werden sollten​

Subagenten glänzen in Szenarien, in denen ein einzelner Agent mit der Breite oder Komplexität einer Aufgabe Schwierigkeiten hätte:

  • Große Refaktorierung über mehrere Module hinweg
  • Implementierung eines Features, das Frontend- und Backend-Änderungen erfordert
  • Gleichzeitiges Ausführen von Tests, Beheben von Bugs und Aktualisieren von Dokumentation
  • Code-Review über mehrere Repositories hinweg
  • Paralleles Generieren und Validieren von Codeänderungen
tipp

Für einfache Einzeldatei-Aufgaben fügt eine Subagenten-Architektur Overhead ohne Nutzen hinzu. Verwenden Sie Subagenten, wenn sich die Aufgabe natürlich in unabhängige oder halb-unabhängige Teilaufgaben zerlegen lässt. Wenn Sie die Aufgabe in einem Satz beschreiben können, benötigen Sie wahrscheinlich keine Subagenten.

Modellauswahl​

Modelle für Planer vs. Subagenten wählen​

Eine der wichtigsten Entscheidungen in einer Subagenten-Konfiguration ist, welches Modell dem Planer und welches den Subagenten zugewiesen wird. Verschiedene Modelle haben unterschiedliche Stärken, Kosten und Geschwindigkeitsmerkmale.

Verfügbare Modelle​

ModellStärkenGeschwindigkeitKostenAm besten für
cursor-proAusgewogenes Reasoning und GeschwindigkeitMittelMittelPlaner, allgemeine Aufgaben
cursor-fastSchnelle Iteration, einfache AufgabenSchnellNiedrigEinfache Subagenten
cursor-maxTiefes Reasoning, komplexe LogikLangsamHochKomplexe Subagenten
cursor-thinkErweitertes Reasoning, ArchitekturAm langsamstenAm höchstenPlaner für komplexe Aufgaben

Konfiguration​

Konfigurieren Sie Modellzuweisungen in Ihren Cursor-Einstellungen oder der Projektkonfiguration:

// In settings.json
{
  "cursor.subagents.enabled": true,
  "cursor.subagents.plannerModel": "cursor-pro",
  "cursor.subagents.defaultModel": "cursor-fast",
  "cursor.subagents.maxConcurrent": 4,
  "cursor.subagents.timeout": 300000
}

Pro-Subagent-Modellkonfiguration​

Sie können verschiedenen Subagenten basierend auf ihrer Aufgabe unterschiedliche Modelle zuweisen:

# .cursor/subagents/config.yaml
planner:
  model: cursor-pro
  description: "Orchestrates the overall task and synthesizes results"
  maxSubagents: 5

subagents:
  - name: "frontend-agent"
    model: cursor-max
    description: "Handles React component changes"
    scope:
      files: ["src/components/**", "src/pages/**"]
    tools: ["read", "write", "edit"]

  - name: "backend-agent"
    model: cursor-max
    description: "Handles API and server logic"
    scope:
      files: ["src/api/**", "src/server/**", "src/models/**"]
    tools: ["read", "write", "edit", "terminal"]

  - name: "test-agent"
    model: cursor-fast
    description: "Writes and runs tests"
    scope:
      files: ["test/**", "src/**/*.test.*"]
    tools: ["read", "write", "terminal"]

  - name: "docs-agent"
    model: cursor-fast
    description: "Updates documentation"
    scope:
      files: ["docs/**", "README.md", "CHANGELOG.md"]
    tools: ["read", "write"]
tipp

Verwenden Sie ein leistungsstarkes Modell wie cursor-max für Subagenten, die komplexe Logik oder kritische Codepfade behandeln. Verwenden Sie cursor-fast für einfachere Aufgaben wie Formatierung, Dokumentation oder das Ausführen vordefinierter Befehle. Dies balanciert Kosten und Qualität effektiv.

Best Practices für die Modellauswahl​

Berücksichtigen Sie bei der Entscheidung über Modellzuweisungen diese Richtlinien:

  1. Der Planer braucht starkes Reasoning: Der Planer muss die vollständige Aufgabe verstehen, sie zerlegen und Ergebnisse synthetisieren. Verwenden Sie cursor-pro oder cursor-think für den Planer.
  2. Modell an Komplexität anpassen: Einfache Dateibearbeitungen benötigen kein cursor-max. Reservieren Sie teure Modelle für Aufgaben, die tiefes Verständnis erfordern.
  3. Kontextfenster berücksichtigen: Komplexe Teilaufgaben benötigen möglicherweise größere Kontextfenster. cursor-max unterstützt mehr Kontext als cursor-fast.
  4. Kostenbewusstes Skalieren: Vier cursor-fast-Subagenten auszuführen ist günstiger als ein cursor-max-Agent. Aber wenn Qualität zählt, investieren Sie in bessere Modelle für kritische Teilaufgaben.
// Kostenoptimierte Konfiguration
{
  "cursor.subagents.plannerModel": "cursor-pro",
  "cursor.subagents.models": {
    "frontend-agent": "cursor-fast",
    "backend-agent": "cursor-max",
    "test-agent": "cursor-fast",
    "docs-agent": "cursor-fast"
  }
}

// Qualitätsoptimierte Konfiguration
{
  "cursor.subagents.plannerModel": "cursor-think",
  "cursor.subagents.models": {
    "frontend-agent": "cursor-max",
    "backend-agent": "cursor-max",
    "test-agent": "cursor-max",
    "docs-agent": "cursor-fast"
  }
}
warnung

Das Verwenden teurer Modelle für alle Subagenten kann Ihr Token-Budget schnell verbrauchen. Überwachen Sie Ihre Nutzung mit dem Befehl Cursor: Show Token Usage. Wenn Sie sich Ihrem Limit nähern, stufen Sie nicht-kritische Subagenten auf cursor-fast herab.

Scope-Kontrolle​

Dateizugriffsbeschränkungen​

Die Scope-Kontrolle bestimmt, auf welche Dateien und Verzeichnisse jeder Subagent zugreifen kann. Dies ist sowohl eine Sicherheitsmaßnahme als auch eine Qualitätsverbesserung, da es Subagenten daran hindert, unbeabsichtigte Änderungen vorzunehmen.

Datei-Scopes konfigurieren​

# .cursor/subagents/scopes.yaml
subagents:
  - name: "auth-module-agent"
    scope:
      # Dateien, die dieser Agent lesen und ändern kann
      files:
        include:
          - "src/auth/**"
          - "src/middleware/auth.ts"
          - "config/auth.json"
        exclude:
          - "src/auth/legacy/**"
      # Verzeichnisse, die dieser Agent auflisten und erkunden kann
      directories:
        - "src/auth"
        - "src/middleware"
      # Ob der Agent auf Dateien außerhalb seines Scopes zugreifen kann
      strictMode: true

Wenn strictMode true ist, kann der Subagent keine Dateien außerhalb seines deklarierten Scopes lesen, auflisten oder ändern. Dies ist die empfohlene Einstellung für die meisten Anwendungsfälle.

warnung

Benutzer haben berichtet, dass Agents manchmal Dateien außerhalb des geöffneten Verzeichnisses erkunden, selbst wenn Scope-Beschränkungen konfiguriert sind. Dies passiert typischerweise, wenn:

  1. Die strictMode-Einstellung nicht explizit auf true gesetzt ist (Standard ist false)
  2. Der Subagent Terminal-Befehle verwendet, um auf Dateien zuzugreifen (Umgehung der Datei-Scope-Prüfungen)
  3. Die Scope-Konfiguration relative Pfade verwendet, die anders als erwartet aufgelöst werden
  4. Der Subagent den breiteren Scope des Planers erbt

Um dies zu verhindern, setzen Sie immer strictMode: true und beschränken Sie auch den Terminal-Tool-Zugriff. Siehe den Abschnitt Sicherheitsgrenzen unten.

Häufige Scope-Muster​

Modulbasierter Scope: Einen Agenten auf ein spezifisches Modul beschränken:

- name: "user-module-agent"
  scope:
    files:
      include: ["src/modules/user/**"]
    strictMode: true

Schichtbasierter Scope: Einen Agenten auf eine spezifische Architekturschicht beschränken:

- name: "api-layer-agent"
  scope:
    files:
      include:
        - "src/api/routes/**"
        - "src/api/controllers/**"
        - "src/api/middleware/**"
    strictMode: true

Nur-Lese-Scope: Lesen, aber nicht Ändern von Dateien erlauben:

- name: "code-review-agent"
  scope:
    files:
      include: ["src/**"]
    tools: ["read"]  # Keine Schreib- oder Bearbeitungstools
    strictMode: true

Geteilter Datei-Scope: Mehrere Agents können auf geteilte Konfigurationsdateien zugreifen:

- name: "config-aware-agent"
  scope:
    files:
      include:
        - "src/features/feature-a/**"
        - "src/shared/config.ts"  # Geteilte Konfigurationsdatei
        - "src/shared/types.ts"   # Geteilte Typdefinitionen
    strictMode: true

Sicherheitsgrenzen​

Tool-Beschränkungen​

Jeder Subagent kann auf spezifische Tools beschränkt werden. Dies verhindert, dass Subagenten Aktionen ausführen, die sie nicht ausführen sollten.

# .cursor/subagents/security.yaml
subagents:
  - name: "read-only-analyzer"
    description: "Analyzes code without modifying anything"
    tools:
      - read
    # Keine Schreib-, Bearbeitungs- oder Terminal-Tools
    scope:
      files:
        include: ["src/**"]
      strictMode: true

  - name: "test-runner"
    description: "Runs tests and reports results"
    tools:
      - read
      - terminal
    scope:
      files:
        include: ["test/**", "src/**"]
      strictMode: true
    terminal:
      allowedCommands:
        - "npm test"
        - "npm run test:unit"
        - "npm run test:integration"
      blockedCommands:
        - "rm"
        - "git push"
        - "npm publish"

  - name: "file-editor"
    description: "Edits source files only"
    tools:
      - read
      - write
      - edit
    # Kein Terminal-Zugriff
    scope:
      files:
        include: ["src/**"]
      strictMode: true
tipp

Die allowedCommands- und blockedCommands-Einstellungen für Terminal-Zugriff bieten eine doppelte Sicherheitsschicht. Selbst wenn ein Subagent irgendwie Terminal-Zugriff erhält, kann er nur explizit genehmigte Befehle ausführen. Dies ist besonders wichtig beim Ausführen von Agents in CI/CD-Pipelines oder automatisierten Umgebungen.

Verhinderung von Interferenzen zwischen Subagenten​

Subagenten sollten unabhängig arbeiten. Um zu verhindern, dass sie sich gegenseitig stören:

  1. Nicht-überlappende Datei-Scopes: Sicherstellen, dass Subagenten keine überlappenden Schreibzugriffe auf dieselben Dateien haben
  2. Getrennte Branches: In Betracht ziehen, jeden Subagenten auf einem separaten Git-Branch arbeiten zu lassen
  3. Gestaffelte Ausführung: Sequentielle Ausführung verwenden, wenn Subagenten voneinander abhängen
# Beispiel: Sequentielle Ausführung mit Abhängigkeit
execution:
  strategy: sequential
  steps:
    - agent: "schema-agent"
      description: "Generate database schema first"
      scope:
        files:
          include: ["src/models/**", "migrations/**"]
      tools: ["read", "write", "edit"]

    - agent: "api-agent"
      description: "Build API endpoints based on schema"
      dependsOn: "schema-agent"
      scope:
        files:
          include: ["src/api/**"]
      tools: ["read", "write", "edit"]

    - agent: "test-agent"
      description: "Write tests for the new API"
      dependsOn: "api-agent"
      scope:
        files:
          include: ["test/**"]
      tools: ["read", "write", "terminal"]
warnung

Wenn zwei Subagenten gleichzeitig in dieselbe Datei schreiben, erhalten Sie Merge-Konflikte, die der Planer nicht automatisch lösen kann. Verifizieren Sie immer, dass Datei-Scopes für schreibfähige Subagenten nicht überlappen. Verwenden Sie den Befehl Cursor: Validate Subagent Scopes, um vor der Ausführung auf Überlappungen zu prüfen.

Umgebungsvariablen-Zugriff​

Steuern Sie, welche Umgebungsvariablen jeder Subagent zugreifen kann:

- name: "deploy-agent"
  scope:
    env:
      allow:
        - "DEPLOY_TARGET"
        - "CI_COMMIT_SHA"
      deny:
        - "AWS_SECRET_ACCESS_KEY"
        - "DATABASE_PASSWORD"

Dies stellt sicher, dass sensible Secrets nicht Subagenten ausgesetzt werden, die sie nicht benötigen.

Parallele Agent-Ausführung​

Parallele Ausführung konfigurieren​

Die parallele Ausführung lässt mehrere Subagenten gleichzeitig laufen, was die Gesamt-Aufgabenabschlusszeit erheblich reduziert.

// In settings.json
{
  "cursor.subagents.execution": {
    "strategy": "parallel",
    "maxConcurrent": 4,
    "staggerDelay": 1000
  }
}
  • maxConcurrent: Maximale Anzahl gleichzeitig laufender Subagenten
  • staggerDelay: Millisekunden Wartezeit zwischen dem Start jedes Subagenten (verhindert Ressourcenspitzen)

Beispiel für parallele Ausführung​

# .cursor/subagents/parallel-config.yaml
planner:
  model: cursor-pro
  description: "Refactor the authentication system across frontend and backend"

execution:
  strategy: parallel

subagents:
  - name: "frontend-auth"
    model: cursor-max
    description: "Refactor React authentication components to use new auth context"
    scope:
      files:
        include: ["src/components/auth/**", "src/contexts/AuthContext.tsx"]
      strictMode: true
    tools: ["read", "write", "edit"]

  - name: "backend-auth"
    model: cursor-max
    description: "Refactor backend authentication middleware and JWT handling"
    scope:
      files:
        include: ["src/api/middleware/auth.ts", "src/utils/jwt.ts"]
      strictMode: true
    tools: ["read", "write", "edit"]

  - name: "auth-tests"
    model: cursor-fast
    description: "Update authentication tests for the new structure"
    scope:
      files:
        include: ["test/auth/**"]
      strictMode: true
    tools: ["read", "write", "terminal"]

  - name: "auth-docs"
    model: cursor-fast
    description: "Update authentication documentation"
    scope:
      files:
        include: ["docs/auth/**", "README.md"]
      strictMode: true
    tools: ["read", "write"]

In dieser Konfiguration starten alle vier Subagenten gleichzeitig (mit 1-Sekunden-Versatz) und arbeiten parallel an ihren jeweiligen Bereichen.

Behandlung paralleler Ausführungsergebnisse​

Der Planer sammelt Ergebnisse von allen parallelen Subagenten und synthetisiert sie:

// Planer-Synthese-Konfiguration
{
  "cursor.subagents.planner": {
    "synthesisStrategy": "merge",
    "conflictResolution": "planner-decides",
    "generateSummary": true,
    "summaryFormat": "markdown"
  }
}
tipp

Wenn parallele Subagenten konfliktäre Änderungen produzieren, kann der Planer diese lösen, indem er einen Ansatz gegenüber einem anderen wählt. Aktivieren Sie generateSummary, damit der Planer seine Konfliktlösungsentscheidungen in einem menschenlesbaren Format erklärt. Überprüfen Sie diese Zusammenfassung, bevor Sie die Änderungen akzeptieren.

Subagenten-Orchestrierung​

Orchestrierungsstrategien​

Der Planer kann verschiedene Strategien verwenden, um Subagenten zu orchestrieren:

Strategie 1: Fan-Out / Fan-In

Der Planer zerlegt die Aufgabe, weist Teilaufgaben an parallele Subagenten zu, sammelt alle Ergebnisse und synthetisiert sie.

execution:
  strategy: parallel
  synthesis:
    type: "merge"
    order: "completion"  # Ergebnisse bei Fertigstellung sammeln

Strategie 2: Pipeline

Subagenten werden sequenziell ausgeführt, jeder verarbeitet die Ausgabe des vorherigen.

execution:
  strategy: sequential
  pipeline:
    - agent: "schema-generator"
      output: "schema_result"
    - agent: "api-builder"
      input: "schema_result"
      output: "api_result"
    - agent: "test-writer"
      input: "api_result"
      output: "test_result"

Strategie 3: Adaptiv

Der Planer entscheidet dynamisch, ob Subagenten parallel oder sequenziell ausgeführt werden, basierend auf Aufgabenabhängigkeiten.

execution:
  strategy: adaptive
  rules:
    - condition: "no_dependencies"
      action: "parallel"
    - condition: "has_dependencies"
      action: "sequential"
    - condition: "partial_dependencies"
      action: "mixed"

Dynamische Subagenten-Erstellung​

Der Planer kann Subagenten dynamisch erstellen, basierend auf dem, was er während der Aufgabenausführung entdeckt:

// In settings.json
{
  "cursor.subagents.dynamicCreation": true,
  "cursor.subagents.dynamicMaxAgents": 8,
  "cursor.subagents.dynamicTemplate": {
    "model": "cursor-fast",
    "tools": ["read", "write", "edit"],
    "scope": {
      "strictMode": true
    }
  }
}

Mit aktivierter dynamischer Erstellung kann der Planer nach Bedarf neue Subagenten erzeugen. Wenn der Planer beispielsweise entdeckt, dass die Aufgabe sowohl Python- als auch TypeScript-Dateien umfasst, kann er spontan einen Python-spezifischen Subagenten und einen TypeScript-spezifischen Subagenten erstellen.

warnung

Die dynamische Subagenten-Erstellung kann zu unkontrolliertem Agent-Spawning führen, wenn der Planer den Bedarf an Parallelität überschätzt. Setzen Sie immer dynamicMaxAgents auf ein vernünftiges Limit (4-8) und überwachen Sie die gesamte Token-Nutzung. Wenn der Planer zu viele Subagenten erstellt, kann er das Token-Budget vor Abschluss der Aufgabe erschöpfen.

Orchestrierung mit Kontrollpunkten​

Fügen Sie Kontrollpunkte zwischen Subagenten-Ausführungen hinzu, um menschliche Überprüfung oder automatisierte Validierung zu ermöglichen:

execution:
  strategy: sequential
  checkpoints:
    - after: "schema-generator"
      action: "validate"
      validator: "npm run typecheck"
      onFail: "retry"
      maxRetries: 2

    - after: "api-builder"
      action: "review"
      reviewer: "human"
      timeout: 300000
      onTimeout: "proceed"
tipp

Kontrollpunkte sind besonders wertvoll in CI/CD-Integrationen, wo Sie Zwischenergebnisse validieren möchten, bevor Sie fortfahren. Ein validate-Kontrollpunkt führt einen Befehl aus und fährt nur fort, wenn er erfolgreich beendet wird, während ein review-Kontrollpunkt für menschliche Eingabe pausiert.

Überwachung und Debugging​

Subagenten-Status anzeigen​

Überwachen Sie alle laufenden Subagenten über die Cursor-Seitenleiste:

# Befehlspalette: Cursor: Show Subagent Dashboard

Das Dashboard zeigt:

Subagent Dashboard
==================
Planner: [running] cursor-pro
  Task: "Refactor authentication system"
  Steps: 3/5

Subagents:
  [completed] frontend-auth (cursor-max)
    Files changed: 4
    Tokens used: 12,400

  [running] backend-auth (cursor-max)
    Current file: src/api/middleware/auth.ts
    Tokens used: 8,200

  [running] auth-tests (cursor-fast)
    Current file: test/auth/login.test.ts
    Tokens used: 3,100

  [queued] auth-docs (cursor-fast)
    Waiting for: backend-auth to complete

Total tokens: 23,700 / 100,000

Scope-Verletzungen debuggen​

Wenn ein Subagent versucht, auf Dateien außerhalb seines Scopes zuzugreifen, wird der Versuch protokolliert:

# Scope-Verletzungsprotokoll anzeigen
# Befehlspalette: Cursor: Show Subagent Logs
[WARN] Subagent "frontend-auth" attempted to read src/api/routes.ts
       Access denied: file is outside the agent's scope
       Scope includes: src/components/auth/**, src/contexts/AuthContext.tsx

[WARN] Subagent "backend-auth" attempted to run terminal command: npm install
       Command blocked: not in allowedCommands list
       Allowed commands: npm test, npx tsc, git status
tipp

Wenn Sie wiederholte Scope-Verletzungen desselben Subagenten sehen, ist sein Scope möglicherweise zu restriktiv. Überprüfen Sie die Aufgabe und erwägen Sie, den Scope zu erweitern, um die Dateien einzuschließen, auf die er ständig zuzugreifen versucht. Ein frustrierter Subagent, der nicht auf benötigte Dateien zugreifen kann, verschwendet Tokens an fehlgeschlagenen Versuchen.

Best Practices​

  • Verwenden Sie cursor-pro oder besser für den Planer, günstigere Modelle für einfache Subagenten
  • Setzen Sie immer strictMode: true für Datei-Scopes, um unerwünschten Zugriff zu verhindern
  • Konfigurieren Sie allowedCommands für jeden Subagenten mit Terminal-Zugriff
  • Stellen Sie sicher, dass Schreib-Scopes sich nicht zwischen parallelen Subagenten überlappen
  • Setzen Sie ein maxConcurrent-Limit zur Kontrolle der Ressourcennutzung
  • Verwenden Sie Kontrollpunkte für kritische Aufgaben, die Validierung erfordern
  • Überwachen Sie die Token-Nutzung über alle Subagenten, um Budget-Erschöpfung zu vermeiden
  • Beginnen Sie mit sequenzieller Ausführung und wechseln Sie zu parallel, sobald Scopes verifiziert sind
  • Überprüfen Sie die Synthese-Zusammenfassung des Planers, bevor Sie parallele Ergebnisse akzeptieren
  • Versionieren Sie Ihre Subagenten-Konfiguration für Team-Konsistenz
warnung

Subagenten erben standardmäßig den System-Prompt des Planers. Wenn Ihr System-Prompt sensible Informationen enthält, erwägen Sie die Verwendung von Subagenten-spezifischen Prompts, die unnötigen Kontext ausschließen. Konfigurieren Sie dies mit der Einstellung cursor.subagents.inheritPlannerPrompt auf false.

Fazit​

Subagenten in Cursor bieten eine leistungsstarke Möglichkeit, komplexe Aufgaben in handhabbare, spezialisierte Einheiten zu zerlegen. Durch sorgfältige Auswahl von Modellen, Konfiguration strenger Datei-Scopes, Einrichtung von Sicherheitsgrenzen und Wahl der richtigen Orchestrierungsstrategie können Sie Multi-Agenten-Workflows erstellen, die sowohl effizient als auch sicher sind.

Die wichtigsten Überlegungen sind: Passen Sie das Modell an die Aufgabenkomplexität an, verwenden Sie strikte Scope-Durchsetzung, um Dateizugriffsprobleme zu verhindern, und beginnen Sie mit sequenzieller Ausführung, bevor Sie zu parallel wechseln. Mit diesen Praktiken werden Subagenten zu einem zuverlässigen Werkzeug für die Bewältigung groß angelegter Entwicklungsaufgaben, die für einen einzelnen Agenten überwältigend wären.