Créer un agent personnalisé en TOML
Na ovoj stranici
Leçon réécrite le 2 novembre 2026. Les exemples précédents utilisaient des clés inexistantes dans les fichiers d’agents (
model,system_prompt,auto_approve) et des outils inexistants (list_dir,edit_file). Les clés et les noms d’outils sont désormais alignés sur la documentation officielle et le code source de Vibe. Sources : Agents · Référence de configuration — Fichiers de définition d’agent · outils intégrés (dépôt mistral-vibe).
Au-delà des agents intégrés
Les agents intégrés couvrent des profils standards, mais tes projets ont des besoins uniques : une équipe paiement nécessite des garde-fous différents d’une équipe documentation. Vibe te permet de créer des agents personnalisés en plaçant un fichier .toml dans ~/.vibe/agents/ (niveau utilisateur) ou ./.vibe/agents/ (niveau projet, chargé uniquement si le dossier est de confiance). Le comportement défini dans un fichier est lisible, versionnable et partageable, contrairement à des instructions répétées à chaque session.
Le nom de l’agent correspond au nom du fichier : redteam.toml se lance avec vibe --agent redteam. Le nom main est réservé.
Clés du fichier agent
| Clé | Rôle |
|---|---|
agent_type | "agent" (par défaut, sélectionnable par l’utilisateur) ou "subagent" (lancé uniquement par délégation) |
display_name, description | Nom affiché et description ; la description est obligatoire pour un sous-agent |
instructions | Instructions en ligne ajoutées après l’invite système (pour un sous-agent, elles la remplacent) |
system_prompt_id | Nom d’un fichier Markdown dans ~/.vibe/prompts/ ou ./.vibe/prompts/, sans l’extension |
active_model | Alias du modèle à utiliser pour cet agent |
enabled_tools, disabled_tools | Liste blanche et liste noire d’outils (noms exacts, motifs glob ou expressions re:) |
[tools.<outil>] | Permissions par outil : permission = "always", "ask" ou "never", plus pour bash, allowlist et denylist de préfixes de commande |
safety | Indicateur visuel uniquement (couleur de la bordure de saisie) : safe, neutral, destructive, smart ou yolo ; cela n’impose aucune permission (Leçon 3) |
Outils que tu peux nommer
Les outils intégrés de Vibe utilisent ces noms : read_file, write_file, edit (anciennement search_replace), bash, grep, todo, task (délégation à un sous-agent), skill, ask_user_question, web_fetch et web_search. Les outils provenant d’un serveur MCP sont nommés {serveur}_{outil}, et les outils de connecteur sont connector_{connecteur}_{outil}. Un nom d’outil mal orthographié dans enabled_tools ne correspond à rien : vérifie l’orthographe avant de conclure qu’un agent « refuse » d’écrire un fichier.
Premier agent : Le Planificateur
Vibe ne possède pas d’agent plan intégré ; la documentation fournit cet exemple en lecture seule pour explorer un dépôt et proposer un plan avant toute modification :
# ~/.vibe/agents/plan.toml
display_name = "Plan"
description = "Explores the repository and proposes a plan before any modification."
safety = "safe"
disabled_tools = ["edit", "write_file"]
instructions = """
Explore the repository and propose a step-by-step implementation plan.
Do not modify any files until the user approves the plan.
"""
[tools.bash]
permission = "ask"
Lance-le avec vibe --agent plan. Une fois le plan approuvé, appuie sur Shift+Tab pour basculer sur accept-edits pour l’exécution. Note l’ordre du fichier : en TOML, toute clé écrite après un en-tête de table comme [tools.bash] appartient à cette table. Place les clés de premier niveau en premier, et les blocs [tools.*] à la fin.
Un agent de documentation
# ~/.vibe/agents/doc-writer.toml
display_name = "Technical Writer"
description = "Writes technical documentation based on source code."
safety = "neutral"
enabled_tools = ["read_file", "grep", "write_file", "edit", "ask_user_question"]
instructions = """
Based on the source code:
1. Write a docstring for every public function.
2. Maintain a structured README with examples.
3. Document required environment variables.
Style: professional, concise, supported by code examples.
"""
[tools.write_file]
permission = "ask"
Il peut lire, rechercher et écrire, mais ne peut pas exécuter de commandes : bash n’est pas dans sa liste. Chaque création de fichier nécessite ton approbation. Essaie-le sur un petit module avant de l’appliquer à un dépôt entier.
Choisir un modèle d’agent
active_model attend l’alias d’un modèle configuré. Vibe est livré avec un modèle intégré, Mistral Medium 3.5, aliasé mistral-medium-3.5. Pour un autre modèle, déclare d’abord un préréglage dans config.toml, puis référence son alias :
# ~/.vibe/config.toml
[[models]]
name = "codestral-latest"
provider = "mistral"
alias = "codestral"
# dans le fichier agent
active_model = "codestral"
Sans active_model, l’agent utilise le modèle de la session.
Rédiger des instructions
Deux voies existent. instructions contient du texte en ligne ajouté après l’invite système de Vibe : c’est l’approche la plus simple. system_prompt_id pointe vers un fichier Markdown dans le dossier prompts/, utile pour les longues invites révisées lors de revues de code. Un détail comportemental compte : l’invite d’un agent personnalisé s’applique uniquement si tu le sélectionnes avant ton premier message (via --agent ou Shift+Tab). Si tu changes d’agent en cours de session, ses outils, permissions et modèle s’appliquent immédiatement, mais son invite ne prend effet qu’après /clear.
Bonnes pratiques
Privilège minimum d’abord : donne à un agent uniquement les outils dont il a besoin. Un agent d’analyse n’a pas besoin de write_file ; un rédacteur n’a pas besoin de bash. Retirer chaque outil rend toute une catégorie d’erreurs impossible.
Un agent par responsabilité ensuite : un fichier fourre-tout produit des réponses médiocres partout. Trois fichiers ciblés valent mieux qu’un générique.
Instructions précises enfin : définis le rôle exact, les conventions du projet, le format de sortie attendu et les erreurs à éviter. Quand un agent déçoit, c’est presque toujours parce que l’un de ces quatre points manque.
Ključne točke
- Un agent personnalisé est un fichier
.tomldans~/.vibe/agents/ou./.vibe/agents/; son nom correspond au nom du fichier - Clés utiles :
display_name,description,instructionsousystem_prompt_id,active_model,enabled_tools,disabled_tools,[tools.<outil>] - Noms d’outils :
read_file,write_file,edit,bash,grep,todo,task,skill,ask_user_question,web_fetch,web_search active_modelattend un alias de préréglage de modèle (oumistral-medium-3.5, intégré)- Place les blocs
[tools.*]à la fin du fichier