Créer un agent custom avec TOML

Au-delà des agents built-in

Les quatre agents intégrés couvrent les cas d’usage standards, mais vos projets ont des besoins spécifiques : une équipe qui travaille sur du paiement en ligne n’attend pas la même vigilance qu’une équipe qui génère de la documentation. Mistral Vibe vous permet donc de créer vos propres agents en déposant des fichiers .toml dans le répertoire ~/.vibe/agents/.

Un agent custom encapsule un comportement précis : un modèle, des permissions, un prompt système et un ensemble d’outils autorisés. C’est la brique fondamentale pour industrialiser vos workflows avec Vibe, parce qu’un comportement écrit dans un fichier se relit, se versionne et se partage — contrairement à une consigne que vous retapez à chaque session.

Anatomie d’un fichier agent TOML

Voici la structure complète d’un agent custom, ici un relecteur de code orienté sécurité :

display_name = "Code Reviewer"
description = "Agent spécialisé dans la revue de code avec focus sécurité."
safety = "safe"
auto_approve = false
model = "mistral-large-latest"

system_prompt = """
Vous êtes un expert en revue de code. Analysez le code pour :
- Les failles de sécurité (injection, XSS, CSRF)
- Les problèmes de performance
- Le non-respect des conventions du projet
Soyez précis et proposez des corrections concrètes.
"""

enabled_tools = [
  "read_file",
  "grep",
  "list_dir",
  "ask_user_question"
]

Chaque champ répond à une question différente, et il vaut la peine de les prendre dans l’ordre.

Les champs du fichier TOML

Le couple display_name / description sert à vous repérer. Le premier est le nom affiché dans la liste des agents, le second explique quand l’utiliser. Soyez explicite : quand vous aurez dix agents custom, un intitulé vague vous coûtera plus de temps qu’il n’en fait gagner.

display_name = "DB Migration Expert"
description = "Génère et valide les migrations Prisma/Drizzle avec rollback."

Le champ model désigne le modèle Mistral à utiliser, et chaque agent peut cibler un modèle différent selon la tâche. Un agent d’architecture qui raisonne sur des arbitrages profite d’un grand modèle ; un agent qui corrige des imports en série n’en a pas besoin.

# Pour les tâches complexes d'architecture
model = "mistral-large-latest"

# Pour les corrections rapides et le refactoring
model = "codestral-latest"

# Pour un modèle local (Devstral)
model = "local"

Le system_prompt définit la personnalité et les compétences de l’agent. Utilisez les triples guillemets pour les prompts multi-lignes, et écrivez-y les règles que vous répéteriez sinon à chaque conversation. Dans l’exemple ci-dessous, l’agent DevOps sait d’avance qu’il doit proposer du multi-stage et passer par trivy : vous n’aurez plus à le lui rappeler.

system_prompt = """
Vous êtes un expert DevOps spécialisé en infrastructure Docker et Kubernetes.
Règles :
1. Toujours proposer des Dockerfiles multi-stage
2. Vérifier les vulnérabilités avec trivy avant chaque suggestion
3. Privilégier les images Alpine sauf nécessité contraire
"""

Le champ safety fixe le niveau de sécurité de l’agent — nous le détaillerons dans la prochaine leçon. Retenez pour l’instant les quatre valeurs possibles :

safety = "safe"        # Lecture seule
safety = "neutral"     # Modifications contrôlées
safety = "destructive" # Peut supprimer/écraser
safety = "yolo"        # Aucune restriction

Le booléen auto_approve détermine si les outils s’exécutent sans validation. C’est le réglage qui décide si vous restez devant l’écran ou non.

auto_approve = true   # Pas de confirmation
auto_approve = false  # Demande avant chaque outil

Enfin, enabled_tools est la liste blanche des outils que l’agent peut utiliser, et c’est votre levier de contrôle le plus précis. Les trois configurations suivantes produisent trois agents radicalement différents à partir du même modèle et du même prompt.

# Agent de lecture seule
enabled_tools = ["read_file", "grep", "list_dir"]

# Agent d'édition
enabled_tools = ["read_file", "write_file", "edit_file", "grep"]

# Agent avec exécution shell
enabled_tools = ["read_file", "write_file", "bash", "grep"]

Créer votre premier agent custom

Passons à la pratique avec un agent de documentation technique. Créez d’abord le répertoire, s’il n’existe pas déjà :

mkdir -p ~/.vibe/agents

Déposez-y le fichier suivant. Notez qu’il est en neutral — il doit écrire des fichiers — mais sans bash : rédiger de la documentation ne justifie aucune commande shell.

# ~/.vibe/agents/doc-writer.toml
display_name = "Documentation Writer"
description = "Génère de la documentation technique à partir du code source."
safety = "neutral"
auto_approve = false
model = "mistral-large-latest"

system_prompt = """
Vous êtes un rédacteur technique. À partir du code source :
1. Générez des JSDoc/TSDoc pour chaque fonction publique
2. Créez un README.md structuré avec exemples
3. Documentez les variables d'environnement requises
Style : professionnel, concis, avec exemples de code.
"""

enabled_tools = [
  "read_file",
  "write_file",
  "edit_file",
  "grep",
  "list_dir",
  "ask_user_question"
]

Lancez-le ensuite, et vérifiez sur un petit module que la sortie correspond bien au style demandé avant de l’appliquer à tout un dépôt :

vibe --agent doc-writer

Bonnes pratiques de conception

Le principe du moindre privilège doit guider chaque fichier : donnez à un agent uniquement les outils dont il a besoin. Un agent d’analyse n’a pas besoin de write_file, un agent de documentation n’a pas besoin de bash. Chaque outil retiré est une catégorie entière d’erreurs qui devient impossible.

Visez ensuite un agent par responsabilité. Un fichier fourre-tout finit par produire des réponses moyennes partout : le prompt tire dans plusieurs directions et la liste d’outils devient forcément large. Trois fichiers séparés — security-auditor.toml pour l’analyse de vulnérabilités, test-writer.toml pour la génération de tests, api-designer.toml pour la conception d’API REST — se règlent et se corrigent indépendamment.

Reste le prompt système, qui fait la différence entre un agent fiable et un agent capricieux. Un bon prompt précise le rôle exact de l’agent, les règles et conventions à respecter, le format de sortie attendu et les erreurs à éviter. Si un agent vous déçoit, c’est presque toujours l’un de ces quatre points qui manque.

Points clés à retenir

• Les agents custom sont des fichiers .toml dans ~/.vibe/agents/
• Chaque agent combine un modèle, un prompt système, des outils et un niveau de sécurité
• Le champ enabled_tools contrôle précisément ce que l’agent peut faire
• Privilégiez des agents spécialisés avec le minimum de permissions nécessaire
• Le system_prompt est la clé pour un comportement fiable et prévisible