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. Mistral Vibe vous permet de créer vos propres agents en définissant 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.

Anatomie d’un fichier agent TOML

Voici la structure complète d’un agent custom :

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

Les champs du fichier TOML

display_name et description

Le nom affiché dans la liste des agents et une description courte pour savoir quand l’utiliser. Soyez explicite — quand vous aurez dix agents custom, vous apprécierez des descriptions claires.

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

model

Le modèle Mistral à utiliser. Chaque agent peut cibler un modèle différent selon la tâche :

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

system_prompt

Le prompt système définit la personnalité et les compétences de l’agent. Utilisez les triples guillemets pour les prompts multi-lignes :

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
"""

safety

Le niveau de sécurité de l’agent — nous le détaillerons dans la prochaine leçon. Les valeurs possibles :

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

auto_approve

Détermine si les outils s’exécutent sans validation :

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

enabled_tools

La liste blanche des outils que l’agent peut utiliser. C’est votre levier de contrôle le plus précis :

# 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

Voici un exemple complet — un agent de documentation technique :

mkdir -p ~/.vibe/agents

# ~/.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 :

vibe --agent doc-writer

Bonnes pratiques de conception

Principe du moindre privilège

Donnez à chaque 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.

Un agent = une responsabilité

Évitez les agents fourre-tout. Préférez plusieurs agents spécialisés à un agent généraliste :

• security-auditor.toml — analyse de vulnérabilités
• test-writer.toml — génération de tests
• api-designer.toml — conception d’API REST

Prompts système précis

Un bon prompt système inclut :

• Le rôle exact de l’agent
• Les règles et conventions à respecter
• Le format de sortie attendu
• Les erreurs à éviter

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