Configuration et utilisation des sous-agents dans Cursor

Les sous-agents dans Cursor vous permettent de décomposer des tâches complexes en unités plus petites et spécialisées qui peuvent s'exécuter en parallèle ou en séquence. Un agent planificateur orchestre la tâche globale tandis que les sous-agents gèrent des sous-tâches spécifiques avec leurs propres modèles, portées et limites de sécurité. Ce guide couvre tout, de la sélection des modèles à la configuration de la sécurité, pour vous aider à construire des flux de travail multi-agents robustes.

Comprendre les sous-agents

Qu'est-ce qu'un sous-agent ?

Les sous-agents sont des instances d'agent indépendantes qui opèrent sous la direction d'un agent planificateur. Chaque sous-agent peut avoir son propre :

• Modèle : Différents modèles d'IA pour différents types de tâches
• Portée : Accès restreint aux fichiers et répertoires
• Limites de sécurité : Restrictions sur les actions qu'ils peuvent entreprendre
• Contexte : Fenêtre de contexte isolée pour éviter les interférences

L'agent planificateur décompose une tâche complexe, attribue des sous-tâches aux sous-agents, collecte leurs résultats et synthétise un résultat final. Cette architecture reproduit la façon dont les équipes humaines divisent le travail entre spécialistes.

Quand utiliser les sous-agents

Les sous-agents brillent dans les scénarios où un seul agent aurait du mal avec l'ampleur ou la complexité d'une tâche :

• Refactorisation importante couvrant plusieurs modules
• Implémentation d'une fonctionnalité nécessitant des changements frontend et backend
• Exécution simultanée de tests, correction de bugs et mise à jour de documentation
• Revue de code sur plusieurs dépôts
• Génération et validation de changements de code en parallèle

astuce

Pour les tâches simples sur un seul fichier, une architecture de sous-agents ajoute de la surcharge sans bénéfice. Utilisez des sous-agents lorsque la tâche se divise naturellement en sous-tâches indépendantes ou semi-indépendantes. Si vous pouvez décrire la tâche en une phrase, vous n'avez probablement pas besoin de sous-agents.

Sélection des modèles

Choisir des modèles pour le planificateur et les sous-agents

L'une des décisions les plus importantes dans une configuration de sous-agents est le modèle à attribuer au planificateur et celui à attribuer aux sous-agents. Différents modèles ont des forces, des coûts et des caractéristiques de vitesse différents.

Modèles disponibles

Modèle	Forces	Vitesse	Coût	Idéal pour
cursor-pro	Raisonnement et vitesse équilibrés	Moyen	Moyen	Planificateur, tâches générales
cursor-fast	Itération rapide, tâches simples	Rapide	Faible	Sous-agents simples
cursor-max	Raisonnement approfondi, logique complexe	Lent	Élevé	Sous-agents complexes
cursor-think	Raisonnement étendu, architecture	Le plus lent	Le plus élevé	Planificateur pour tâches complexes

Configuration

Configurez les attributions de modèles dans vos paramètres Cursor ou la configuration du projet :

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

Configuration de modèle par sous-agent

Vous pouvez attribuer différents modèles à différents sous-agents selon leur tâche :

# .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"]

astuce

Utilisez un modèle puissant comme cursor-max pour les sous-agents qui gèrent une logique complexe ou des chemins de code critiques. Utilisez cursor-fast pour des tâches plus simples comme le formatage, la documentation ou l'exécution de commandes prédéfinies. Cela équilibre efficacement le coût et la qualité.

Bonnes pratiques de sélection de modèles

Lors du choix des attributions de modèles, considérez ces directives :

1. Le planificateur a besoin d'un raisonnement fort : Le planificateur doit comprendre la tâche complète, la décomposer et synthétiser les résultats. Utilisez cursor-pro ou cursor-think pour le planificateur.
2. Adaptation du modèle à la complexité : Les modifications de fichiers simples n'ont pas besoin de cursor-max. Réservez les modèles coûteux aux tâches nécessitant une compréhension approfondie.
3. Considération de la fenêtre de contexte : Les sous-tâches complexes peuvent nécessiter des fenêtres de contexte plus grandes. cursor-max prend en charge plus de contexte que cursor-fast.
4. Mise à l'échelle sensible au coût : Exécuter quatre sous-agents cursor-fast est moins cher qu'un agent cursor-max. Mais si la qualité compte, investissez dans de meilleurs modèles pour les sous-tâches critiques.

// Configuration optimisée pour les coûts
{
  "cursor.subagents.plannerModel": "cursor-pro",
  "cursor.subagents.models": {
    "frontend-agent": "cursor-fast",
    "backend-agent": "cursor-max",
    "test-agent": "cursor-fast",
    "docs-agent": "cursor-fast"
  }
}

// Configuration optimisée pour la qualité
{
  "cursor.subagents.plannerModel": "cursor-think",
  "cursor.subagents.models": {
    "frontend-agent": "cursor-max",
    "backend-agent": "cursor-max",
    "test-agent": "cursor-max",
    "docs-agent": "cursor-fast"
  }
}

attention

L'utilisation de modèles coûteux pour tous les sous-agents peut rapidement consommer le budget de tokens de votre plan. Surveillez votre utilisation avec la commande Cursor: Show Token Usage. Si vous approchez de votre limite, rétrogradez les sous-agents non critiques vers cursor-fast.

Contrôle de la portée

Restrictions d'accès aux fichiers

Le contrôle de la portée détermine quels fichiers et répertoires chaque sous-agent peut accéder. C'est à la fois une mesure de sécurité et une amélioration de la qualité, car cela empêche les sous-agents d'effectuer des modifications involontaires.

Configuration des portées de fichiers

# .cursor/subagents/scopes.yaml
subagents:
  - name: "auth-module-agent"
    scope:
      # Fichiers que cet agent peut lire et modifier
      files:
        include:
          - "src/auth/**"
          - "src/middleware/auth.ts"
          - "config/auth.json"
        exclude:
          - "src/auth/legacy/**"
      # Répertoires que cet agent peut lister et explorer
      directories:
        - "src/auth"
        - "src/middleware"
      # Si l'agent peut accéder aux fichiers en dehors de sa portée
      strictMode: true

Lorsque strictMode est true, le sous-agent ne peut pas lire, lister ou modifier les fichiers en dehors de sa portée déclarée. C'est le paramètre recommandé pour la plupart des cas d'utilisation.

attention

Les utilisateurs ont signalé que les agents explorent parfois des fichiers en dehors du répertoire ouvert, même lorsque des restrictions de portée sont configurées. Cela se produit généralement lorsque :

1. Le paramètre strictMode n'est pas explicitement défini sur true (il est false par défaut)
2. Le sous-agent utilise des commandes terminal pour accéder aux fichiers (contournant les vérifications de portée de fichiers)
3. La configuration de portée utilise des chemins relatifs qui se résolvent différemment de ce qui était attendu
4. Le sous-agent hérite de la portée plus large du planificateur

Pour éviter cela, définissez toujours strictMode: true et restreignez également l'accès aux outils terminal. Voir la section Limites de sécurité ci-dessous.

Modèles de portée courants

Portée basée sur les modules : Restreindre un agent à un module spécifique :

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

Portée basée sur les couches : Restreindre un agent à une couche architecturale spécifique :

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

Portée en lecture seule : Autoriser la lecture mais pas la modification des fichiers :

- name: "code-review-agent"
  scope:
    files:
      include: ["src/**"]
    tools: ["read"]  # Pas d'outils d'écriture ou d'édition
    strictMode: true

Portée de fichiers partagés : Plusieurs agents peuvent accéder aux fichiers de configuration partagés :

- name: "config-aware-agent"
  scope:
    files:
      include:
        - "src/features/feature-a/**"
        - "src/shared/config.ts"  # Fichier de configuration partagé
        - "src/shared/types.ts"   # Définitions de types partagés
    strictMode: true

Limites de sécurité

Restrictions d'outils

Chaque sous-agent peut être restreint à des outils spécifiques. Cela empêche les sous-agents d'effectuer des actions qu'ils ne devraient pas pouvoir faire.

# .cursor/subagents/security.yaml
subagents:
  - name: "read-only-analyzer"
    description: "Analyzes code without modifying anything"
    tools:
      - read
    # Pas d'outils d'écriture, d'édition ou de terminal
    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
    # Pas d'accès au terminal
    scope:
      files:
        include: ["src/**"]
      strictMode: true

astuce

Les paramètres allowedCommands et blockedCommands pour l'accès au terminal fournissent une double couche de sécurité. Même si un sous-agent obtient d'une manière ou d'une autre l'accès au terminal, il ne peut exécuter que des commandes explicitement approuvées. Ceci est particulièrement important lors de l'exécution d'agents dans des pipelines CI/CD ou des environnements automatisés.

Prévention des interférences entre sous-agents

Les sous-agents doivent fonctionner indépendamment. Pour les empêcher de s'interférer mutuellement :

1. Portées de fichiers non chevauchantes : S'assurer que les sous-agents n'ont pas d'accès en écriture qui se chevauche vers les mêmes fichiers
2. Branches séparées : Envisager de faire travailler chaque sous-agent sur une branche Git séparée
3. Exécution par étapes : Utiliser l'exécution séquentielle lorsque les sous-agents dépendent de la sortie des autres

# Exemple : Exécution séquentielle avec dépendance
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"]

attention

Si deux sous-agents écrivent dans le même fichier simultanément, vous obtiendrez des conflits de fusion que le planificateur ne peut pas résoudre automatiquement. Vérifiez toujours que les portées de fichiers ne se chevauchent pas pour les sous-agents capables d'écrire. Utilisez la commande Cursor: Validate Subagent Scopes pour vérifier les chevauchements avant l'exécution.

Accès aux variables d'environnement

Contrôlez les variables d'environnement auxquelles chaque sous-agent peut accéder :

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

Cela garantit que les secrets sensibles ne sont pas exposés aux sous-agents qui n'en ont pas besoin.

Exécution parallèle d'agents

Configuration de l'exécution parallèle

L'exécution parallèle permet à plusieurs sous-agents de s'exécuter simultanément, réduisant considérablement le temps total d'achèvement de la tâche.

// Dans settings.json
{
  "cursor.subagents.execution": {
    "strategy": "parallel",
    "maxConcurrent": 4,
    "staggerDelay": 1000
  }
}

• maxConcurrent : Nombre maximum de sous-agents s'exécutant en même temps
• staggerDelay : Millisecondes d'attente entre le démarrage de chaque sous-agent (évite les pics de ressources)

Exemple d'exécution parallèle

# .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"]

Dans cette configuration, les quatre sous-agents démarrent simultanément (avec un décalage d'une seconde) et travaillent sur leurs domaines respectifs en parallèle.

Traitement des résultats d'exécution parallèle

Le planificateur collecte les résultats de tous les sous-agents parallèles et les synthétise :

// Configuration de synthèse du planificateur
{
  "cursor.subagents.planner": {
    "synthesisStrategy": "merge",
    "conflictResolution": "planner-decides",
    "generateSummary": true,
    "summaryFormat": "markdown"
  }
}

astuce

Si les sous-agents parallèles produisent des changements conflictuels, le planificateur peut les résoudre en choisissant une approche plutôt qu'une autre. Activez generateSummary pour que le planificateur explique ses décisions de résolution de conflits dans un format lisible par l'humain. Revoyez ce résumé avant d'accepter les changements.

Orchestration des sous-agents

Stratégies d'orchestration

Le planificateur peut utiliser différentes stratégies pour orchestrer les sous-agents :

Stratégie 1 : Fan-out / Fan-in

Le planificateur décompose la tâche, attribue des sous-tâches à des sous-agents parallèles, collecte tous les résultats et les synthétise.

execution:
  strategy: parallel
  synthesis:
    type: "merge"
    order: "completion"  # Collecter les résultats au fur et à mesure de leur achèvement

Stratégie 2 : Pipeline

Les sous-agents s'exécutent en séquence, chacun consommant la sortie du précédent.

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"

Stratégie 3 : Adaptative

Le planificateur décide dynamiquement d'exécuter les sous-agents en parallèle ou séquentiellement selon les dépendances des tâches.

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

Création dynamique de sous-agents

Le planificateur peut créer des sous-agents dynamiquement en fonction de ce qu'il découvre pendant l'exécution de la tâche :

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

Avec la création dynamique activée, le planificateur peut générer de nouveaux sous-agents au besoin. Par exemple, si le planificateur découvre que la tâche implique à la fois des fichiers Python et TypeScript, il peut créer un sous-agent spécifique à Python et un sous-agent spécifique à TypeScript à la volée.

attention

La création dynamique de sous-agents peut entraîner une prolifération incontrôlée d'agents si le planificateur surestime le besoin de parallélisme. Définissez toujours dynamicMaxAgents à une limite raisonnable (4-8) et surveillez l'utilisation totale des tokens. Si le planificateur crée trop de sous-agents, il peut épuiser le budget de tokens avant la fin de la tâche.

Orchestration avec points de contrôle

Ajoutez des points de contrôle entre les exécutions de sous-agents pour permettre une révision humaine ou une validation automatisée :

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"

astuce

Les points de contrôle sont particulièrement précieux dans les intégrations CI/CD où vous souhaitez valider les résultats intermédiaires avant de continuer. Un point de contrôle validate exécute une commande et ne procède que si elle se termine avec succès, tandis qu'un point de contrôle review s'arrête pour une entrée humaine.

Surveillance et débogage

Affichage du statut des sous-agents

Surveillez tous les sous-agents en cours d'exécution depuis la barre latérale de Cursor :

# Palette de commandes : Cursor: Show Subagent Dashboard

Le tableau de bord affiche :

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

Débogage des violations de portée

Si un sous-agent tente d'accéder à des fichiers en dehors de sa portée, la tentative est journalisée :

# Afficher le journal des violations de portée
# Palette de commandes : 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

astuce

Si vous voyez des violations de portée répétées du même sous-agent, sa portée est peut-être trop restrictive. Revoyez la tâche et envisagez d'élargir la portée pour inclure les fichiers qu'il essaie constamment d'accéder. Un sous-agent frustré qui ne peut pas accéder aux fichiers nécessaires gaspillera des tokens sur des tentatives échouées.

Bonnes pratiques

• Utilisez cursor-pro ou mieux pour le planificateur, des modèles moins chers pour les sous-agents simples
• Définissez toujours strictMode: true pour les portées de fichiers afin de prévenir les accès non souhaités
• Configurez allowedCommands pour tout sous-agent avec accès au terminal
• Assurez-vous que les portées d'écriture ne se chevauchent pas entre les sous-agents parallèles
• Définissez une limite maxConcurrent pour contrôler l'utilisation des ressources
• Utilisez des points de contrôle pour les tâches critiques nécessitant une validation
• Surveillez l'utilisation des tokens pour tous les sous-agents afin d'éviter l'épuisement du budget
• Commencez par l'exécution séquentielle et passez au parallèle une fois les portées vérifiées
• Revoyez le résumé de synthèse du planificateur avant d'accepter les résultats parallèles
• Versionnez votre configuration de sous-agents pour la cohérence de l'équipe

attention

Les sous-agents héritent du système de prompt du planificateur par défaut. Si votre prompt système contient des informations sensibles, envisagez d'utiliser des prompts spécifiques aux sous-agents qui excluent le contexte inutile. Configurez cela avec le paramètre cursor.subagents.inheritPlannerPrompt défini sur false.

Conclusion

Les sous-agents dans Cursor offrent un moyen puissant de décomposer des tâches complexes en unités spécialisées et gérables. En sélectionnant soigneusement les modèles, en configurant des portées de fichiers strictes, en configurant des limites de sécurité et en choisissant la bonne stratégie d'orchestration, vous pouvez construire des flux de travail multi-agents à la fois efficaces et sûrs.

Les considérations les plus importantes sont : adapter le modèle à la complexité de la tâche, utiliser l'application stricte de la portée pour prévenir les problèmes d'accès aux fichiers, et commencer par l'exécution séquentielle avant de passer au parallèle. Avec ces pratiques, les sous-agents deviennent un outil fiable pour gérer des tâches de développement à grande échelle qui seraient écrasantes pour un seul agent.