Créer un agent personnalisé en TOML

Leçon réécrite le 2 novembre 2026. Les exemples précédents utilisaient des clés qui n’existent pas dans les fichiers d’agent (model, system_prompt, auto_approve) et des outils inexistants (list_dir, edit_file). Les clés et les noms d’outils viennent désormais de la référence officielle et du code source de Vibe. Sources : Agents · Configuration reference — Agent definition files · outils intégrés (dépôt mistral-vibe).

Au-delà des agents intégrés

Les agents intégrés couvrent les postures standard, mais vos projets ont des besoins propres : une équipe qui travaille sur le paiement n’attend pas la même vigilance qu’une équipe qui rédige de la documentation. Vibe vous laisse créer vos agents en déposant un fichier .toml dans ~/.vibe/agents/ (pour vous) ou dans ./.vibe/agents/ (pour le projet, chargé seulement si le dossier est de confiance). Un comportement écrit dans un fichier se relit, se versionne et se partage, contrairement à une consigne répétée à chaque session.

Le nom de l’agent est celui du fichier : redteam.toml se lance avec vibe --agent redteam. Le nom main est réservé.

Les clés d’un fichier d’agent

Les outils que vous pouvez nommer

Les outils intégrés de Vibe portent ces noms : read_file, write_file, edit (anciennement search_replace), bash, grep, todo, task (la délégation à un subagent), skill, ask_user_question, web_fetch et web_search. Les outils d’un serveur MCP se nomment {serveur}_{outil}, ceux d’un connecteur connector_{connecteur}_{outil}. Un nom d’outil mal orthographié dans enabled_tools ne correspond à rien : vérifiez-le avant de conclure qu’un agent « ne veut pas » écrire un fichier.

Un premier agent : le planificateur

Vibe n’a pas d’agent plan intégré ; la documentation donne celui-ci, en lecture seule, pour explorer un dépôt et proposer un plan avant toute modification :

# ~/.vibe/agents/plan.toml
display_name = "Plan"
description = "Explore le dépôt et propose un plan avant toute modification."
safety = "safe"
disabled_tools = ["edit", "write_file"]
instructions = """
Explore le dépôt et propose un plan de mise en œuvre étape par étape.
Ne modifie aucun fichier avant que l'utilisateur ait approuvé le plan.
"""

[tools.bash]
permission = "ask"

Lancez-le avec vibe --agent plan. Une fois le plan validé, Shift+Tab vous fait passer sur accept-edits pour l’exécuter. Notez l’ordre du fichier : en TOML, toute clé écrite après un en-tête de table comme [tools.bash] appartient à cette table. Placez donc les clés de premier niveau d’abord, les blocs [tools.*] à la fin.

Un agent de documentation

# ~/.vibe/agents/doc-writer.toml
display_name = "Rédacteur technique"
description = "Rédige la documentation technique à partir du code source."
safety = "neutral"
enabled_tools = ["read_file", "grep", "write_file", "edit", "ask_user_question"]
instructions = """
À partir du code source :
1. Écris une docstring pour chaque fonction publique.
2. Tiens à jour un README structuré, avec des exemples.
3. Documente les variables d'environnement requises.
Style : professionnel, concis, exemples de code à l'appui.
"""

[tools.write_file]
permission = "ask"

Il peut lire, chercher et écrire, mais pas lancer de commande : bash n’est pas dans sa liste. Et chaque création de fichier vous est soumise. Essayez-le sur un petit module avant de l’appliquer à tout un dépôt.

Choisir le modèle d’un agent

active_model attend l’alias d’un modèle configuré. Vibe embarque un modèle intégré, Mistral Medium 3.5, d’alias mistral-medium-3.5. Pour un autre modèle, déclarez d’abord un préréglage dans config.toml, puis référencez son alias :

# ~/.vibe/config.toml
[[models]]
name = "codestral-latest"
provider = "mistral"
alias = "codestral"

# dans le fichier d'agent
active_model = "codestral"

Sans active_model, l’agent utilise le modèle de la session.

Écrire les consignes

Deux voies. instructions contient le texte en ligne, ajouté après le prompt système de Vibe : c’est le plus simple. system_prompt_id désigne un fichier Markdown du dossier prompts/, utile pour un prompt long, relu en revue de code. Un détail de comportement mérite d’être connu : le prompt d’un agent personnalisé ne s’applique que si vous le choisissez avant votre premier message (avec --agent ou Shift+Tab). Si vous changez d’agent en cours de route, ses outils, ses permissions et son modèle s’appliquent tout de suite, mais son prompt seulement après /clear.

Bonnes pratiques

Le moindre privilège d’abord : donnez à un agent les seuls 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. Chaque outil retiré rend impossible une catégorie entière d’erreurs.

Un agent par responsabilité ensuite : un fichier fourre-tout produit des réponses moyennes partout. Trois fichiers ciblés valent mieux qu’un seul.

Des consignes précises enfin : 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 l’un de ces quatre points qui manque.

Points clés à retenir

• Un agent personnalisé est un fichier .toml dans ~/.vibe/agents/ ou ./.vibe/agents/ ; son nom est celui du fichier
• Clés utiles : display_name, description, instructions ou system_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_model attend l’alias d’un préréglage de modèle (ou mistral-medium-3.5, intégré)
• Placez les blocs [tools.*] à la fin du fichier