Aller au contenu
OpenCode
app.header.homeapp.header.docs

Agents

Configurez et utilisez des agents spécialisés.

Les agents sont des assistants IA spécialisés qui peuvent être configurés pour des tâches et des flux de travail spécifiques. Ils vous permettent de créer des outils ciblés avec des invites, des modèles et un accès aux outils personnalisés.

Vous pouvez basculer entre les agents au cours d’une session ou les appeler avec la mention @.

Types

Il existe deux types d’agents dans OpenCode ; agents primaires et sous-agents.

Agents primaires

Les agents principaux sont les principaux assistants avec lesquels vous interagissez directement. Vous pouvez les parcourir à l’aide de la touche Tab ou de votre combinaison de touches switch_agent configurée. Ces agents gèrent votre conversation principale. L’accès aux outils est configuré via les autorisations : par exemple, Build a tous les outils activés tandis que Plan est restreint.

OpenCode est livré avec deux agents principaux intégrés, Build et Plan. Bien regardez-les ci-dessous.

Sous-agents

Les sous-agents sont des assistants spécialisés que les agents principaux peuvent appeler pour des tâches spécifiques. Vous pouvez également les invoquer manuellement en @ les mentionnant dans vos messages.

OpenCode est livré avec deux sous-agents intégrés, Général et Explore. Nous verrons cela ci-dessous.

Intégré

OpenCode est livré avec deux agents principaux intégrés et deux sous-agents intégrés.

Utiliser Build

Mode : primary

Build est l’agent principal par défaut avec tous les outils activés. Il s’agit de l’agent standard pour les travaux de développement où vous avez besoin d’un accès complet aux opérations sur les fichiers et aux commandes système.

Utiliser Plan

Mode : primary

Un agent restreint conçu pour la planification et l’analyse. Nous utilisons un système d’autorisation pour vous donner plus de contrôle et empêcher toute modification involontaire. Par défaut, tous les éléments suivants sont définis sur ask :

  • file edits : toutes les écritures, correctifs et modifications
  • bash : toutes les commandes bash

Cet agent est utile lorsque vous souhaitez que LLM analyse le code, suggère des modifications ou crée des plans sans apporter de modifications réelles à votre base de code.

Utiliser General

Mode : subagent

Un agent polyvalent pour rechercher des questions complexes et exécuter des tâches en plusieurs étapes. Dispose d’un accès complet aux outils (sauf todo), il peut donc apporter des modifications aux fichiers en cas de besoin. Utilisez-le pour exécuter plusieurs unités de travail en parallèle.

Utiliser Explore

Mode : subagent

Un agent rapide en lecture seule pour explorer les bases de code. Impossible de modifier les fichiers. Utilisez-le lorsque vous avez besoin de rechercher rapidement des fichiers par modèles, de rechercher du code par mots-clés ou de répondre à des questions sur la base de code.

Utiliser Compaction

Mode : primary

Agent système caché qui compacte un contexte long en un résumé plus petit. Il s’exécute automatiquement en cas de besoin et n’est pas sélectionnable dans l’interface utilisateur.

Utiliser Title

Mode : primary

Agent système caché qui génère des titres de session courts. Il s’exécute automatiquement et n’est pas sélectionnable dans l’interface utilisateur.

Utiliser Summary

Mode : primary

Agent système caché qui crée des résumés de session. Il s’exécute automatiquement et n’est pas sélectionnable dans l’interface utilisateur.

Usage

  1. Pour les agents principaux, utilisez la touche Tab pour les parcourir au cours d’une session. Vous pouvez également utiliser votre raccourci clavier switch_agent configuré.

  2. Les sous-agents peuvent être invoqués :

    • Automatiquement par les agents principaux pour des tâches spécialisées en fonction de leurs descriptions.

    • Manuellement en @ mentionnant un sous-agent dans votre message. Par exemple.

      @general help me search for this function

  3. Navigation entre les sessions : lorsque les sous-agents créent leurs propres sessions enfants, vous pouvez naviguer entre la session parent et toutes les sessions enfants en utilisant :

    • <Leader>+Right (ou votre combinaison de touches session_child_cycle configurée) pour avancer via parent → enfant1 → enfant2 → … → parent
    • <Leader>+Left (ou votre combinaison de touches session_child_cycle_reverse configurée) pour revenir en arrière dans parent ← enfant1 ← enfant2 ← … ← parent

Cela vous permet de basculer en toute transparence entre la conversation principale et le travail spécialisé des sous-agents.

Configurer

Vous pouvez personnaliser les agents intégrés ou créer les vôtres via la configuration. Les agents peuvent être configurés de deux manières :

JSON

Configurez les agents dans votre fichier de configuration opencode.json :

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

Vous pouvez également définir des agents à l’aide de fichiers markdown. Placez-les dans :

  • Global : ~/.config/opencode/agents/
  • Par projet : .opencode/agents/
~/.config/opencode/agents/review.md
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---


You are in code review mode. Focus on:


- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations


Provide constructive feedback without making direct changes.

Le nom du fichier Markdown devient le nom de l’agent. Par exemple, review.md crée un agent review.

Options

Examinons ces options de configuration en détail.

Description

Utilisez l’option description pour fournir une brève description de ce que fait l’agent et quand l’utiliser.

opencode.json
{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

Il s’agit d’une option de configuration obligatoire.

Température

Contrôlez le caractère aléatoire et la créativité des réponses du LLM avec la configuration temperature.

Des valeurs faibles rendent les réponses plus ciblées et déterministes, tandis que des valeurs plus élevées augmentent la créativité et la variabilité.

opencode.json
{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Les valeurs de température varient généralement de 0,0 à 1,0 :

  • 0,0-0,2 : réponses très ciblées et déterministes, idéales pour l’analyse et la planification du code
  • 0,3-0,5 : réponses équilibrées avec une certaine créativité, idéales pour les tâches de développement générales
  • 0,6-1,0 : réponses plus créatives et variées, utiles pour le brainstorming et l’exploration
opencode.json
{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

Si aucune température n’est spécifiée, OpenCode utilise les valeurs par défaut spécifiques au modèle ; généralement 0 pour la plupart des modèles, 0,55 pour les modèles Qwen.

Pas maximum

Contrôlez le nombre maximum d’itérations agents qu’un agent peut effectuer avant d’être obligé de répondre avec du texte uniquement. Cela permet aux utilisateurs qui souhaitent contrôler les coûts de fixer une limite aux actions agents.

Si cela n’est pas défini, l’agent continuera à itérer jusqu’à ce que le modèle choisisse de s’arrêter ou que l’utilisateur interrompe la session.

opencode.json
{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

Lorsque la limite est atteinte, l’agent reçoit une invite système spéciale lui demandant de répondre avec un résumé de son travail et des tâches restantes recommandées.

Désactiver

Définissez sur true pour désactiver l’agent.

opencode.json
{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

Spécifiez un fichier d’invite système personnalisé pour cet agent avec la configuration prompt. Le fichier d’invite doit contenir des instructions spécifiques à l’objectif de l’agent.

opencode.json
{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

Ce chemin est relatif à l’emplacement du fichier de configuration. Cela fonctionne donc à la fois pour la configuration globale OpenCode et pour la configuration spécifique au projet.

Modèle

Utilisez la configuration model pour remplacer le modèle de cet agent. Utile pour utiliser différents modèles optimisés pour différentes tâches. Par exemple, un modèle de planification plus rapide, un modèle de mise en œuvre plus performant.

opencode.json
{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

L’ID de modèle dans votre configuration OpenCode utilise le format provider/model-id. Par exemple, si vous utilisez OpenCode Zen, vous utiliserez opencode/gpt-5.1-codex pour GPT 5.1 Codex.

Outils

Contrôlez quels outils sont disponibles dans cet agent avec la configuration tools. Vous pouvez activer ou désactiver des outils spécifiques en les définissant sur true ou false.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

Vous pouvez également utiliser des caractères génériques pour contrôler plusieurs outils à la fois. Par exemple, pour désactiver tous les outils d’un serveur MCP :

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

En savoir plus sur les outils.

Autorisations

Vous pouvez configurer des autorisations pour gérer les actions qu’un agent peut effectuer. Actuellement, les autorisations pour les outils edit, bash et webfetch peuvent être configurées pour :

  • "ask" — Demander l’approbation avant d’exécuter l’outil
  • "allow" — Autoriser toutes les opérations sans approbation
  • "deny" – Désactiver l’outil
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

Vous pouvez remplacer ces autorisations par agent.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

Vous pouvez également définir des autorisations dans les agents Markdown.

~/.config/opencode/agents/review.md
---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---


Only analyze code and suggest changes.

Vous pouvez définir des autorisations pour des commandes bash spécifiques.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

Cela peut prendre un modèle global.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

Et vous pouvez également utiliser le caractère générique * pour gérer les autorisations pour toutes les commandes. Puisque la dernière règle correspondante est prioritaire, placez le caractère générique * en premier et les règles spécifiques après.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

En savoir plus sur les autorisations.

Mode

Contrôlez le mode de l’agent avec la configuration mode. L’option mode est utilisée pour déterminer comment l’agent peut être utilisé.

opencode.json
{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

L’option mode peut être définie sur primary, subagent ou all. Si aucun mode n’est spécifié, la valeur par défaut est all.

Caché

Masquez un sous-agent du menu de saisie semi-automatique @ avec hidden: true. Utile pour les sous-agents internes qui ne doivent être invoqués que par programme par d’autres agents via l’outil Tâche.

opencode.json
{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

Cela affecte uniquement la visibilité de l’utilisateur dans le menu de saisie semi-automatique. Les agents masqués peuvent toujours être invoqués par le modèle via l’outil Tâche si les autorisations le permettent.

Autorisations de tâches

Contrôlez quels sous-agents un agent peut appeler via l’outil Tâche avec permission.task. Utilise des modèles globaux pour une correspondance flexible.

opencode.json
{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

Lorsqu’il est défini sur deny, le sous-agent est entièrement supprimé de la description de l’outil Tâche, de sorte que le modèle ne tentera pas de l’invoquer.

Couleur

Personnalisez l’apparence visuelle de l’agent dans l’interface utilisateur avec l’option color. Cela affecte la façon dont l’agent apparaît dans l’interface.

Utilisez une couleur hexadécimale valide (par exemple, #FF5733) ou une couleur de thème : primary, secondary, accent, success, warning, error, info.

opencode.json
{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

Top P

Contrôlez la diversité des réponses avec l’option top_p. Alternative à la température pour contrôler le caractère aléatoire.

opencode.json
{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

Les valeurs vont de 0,0 à 1,0. Les valeurs inférieures sont plus ciblées, les valeurs élevées plus diversifiées.

Supplémentaire

Toutes les autres options que vous spécifiez dans la configuration de votre agent seront transmises directement au fournisseur en tant qu’options de modèle. Cela vous permet d’utiliser des fonctionnalités et des paramètres spécifiques au fournisseur.

Par exemple, avec les modèles de raisonnement de OpenAI, vous pouvez contrôler l’effort de raisonnement :

opencode.json
{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

Ces options supplémentaires sont spécifiques au modèle et au fournisseur. Consultez la documentation de votre fournisseur pour connaître les paramètres disponibles.

Créer des agents

Vous pouvez créer de nouveaux agents à l’aide de la commande suivante :

Fenêtre de terminal
opencode agent create

Cette commande interactive va :

  1. Demandez où enregistrer l’agent ; global ou spécifique à un projet.
  2. Description de ce que l’agent doit faire.
  3. Générez une invite système et un identifiant appropriés.
  4. Vous permet de sélectionner les outils auxquels l’agent peut accéder.
  5. Enfin, créez un fichier markdown avec la configuration de l’agent.

Cas d’utilisation

Voici quelques cas d’utilisation courants pour différents agents.

  • Agent de build : travail de développement complet avec tous les outils activés
  • Agent de plan : analyse et planification sans apporter de modifications
  • Agent de révision : révision de code avec accès en lecture seule et outils de documentation
  • Agent de débogage : axé sur l’investigation avec les outils bash et read activés
  • Agent Docs : écriture de documentation avec des opérations sur les fichiers mais pas de commandes système

Exemples

Voici quelques exemples d’agents qui pourraient vous être utiles.

Agent de documentation

~/.config/opencode/agents/docs-writer.md
---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---


You are a technical writer. Create clear, comprehensive documentation.


Focus on:


- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Auditeur de sécurité

~/.config/opencode/agents/security-auditor.md
---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---


You are a security expert. Focus on identifying potential security issues.


Look for:


- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues