Compétence Agent Eval
Un outil CLI léger pour comparer les agents de codage face-à-face sur des tâches reproductibles. Chaque comparaison du type « quel agent de codage est le meilleur ? » repose sur des impressions — cet outil la systématise.
Quand l'activer
- Comparer des agents de codage (Claude Code, Aider, Codex, etc.) sur votre propre codebase
- Mesurer les performances d'un agent avant d'adopter un nouvel outil ou modèle
- Effectuer des tests de régression lorsqu'un agent met à jour son modèle ou son outillage
- Produire des décisions de sélection d'agent basées sur des données pour une équipe
Installation
Remarque : Installez agent-eval depuis son dépôt après avoir examiné le code source.
Concepts de base
Définitions de tâches en YAML
Définissez les tâches de manière déclarative. Chaque tâche spécifie quoi faire, quels fichiers modifier et comment juger la réussite :
name: add-retry-logic
description: Ajouter une logique de réessai avec backoff exponentiel au client HTTP
repo: ./my-project
files:
- src/http_client.py
prompt: |
Ajoutez une logique de réessai avec backoff exponentiel à toutes les requêtes HTTP.
Maximum 3 tentatives. Délai initial 1s, délai max 30s.
judge:
- type: pytest
command: pytest tests/test_http_client.py -v
- type: grep
pattern: "exponential_backoff|retry"
files: src/http_client.py
commit: "abc1234" # épingler à un commit spécifique pour la reproductibilité
Isolation par Git Worktree
Chaque exécution d'agent obtient son propre worktree git — aucun Docker requis. Cela fournit une isolation de reproductibilité afin que les agents n'interfèrent pas entre eux ni ne corrompent le dépôt de base.
Métriques collectées
| Métrique | Ce qu'elle mesure |
|---|---|
| Taux de réussite | L'agent a-t-il produit du code qui satisfait le juge ? |
| Coût | Dépenses API par tâche (lorsque disponible) |
| Temps | Secondes (temps réel) jusqu'à la fin |
| Cohérence | Taux de réussite sur plusieurs exécutions (ex. 3/3 = 100 %) |
Flux de travail
1. Définir les tâches
Créez un répertoire tasks/ avec des fichiers YAML, un par tâche :
mkdir tasks
# Écrire les définitions de tâches (voir le modèle ci-dessus)
2. Exécuter les agents
Lancez les agents sur vos tâches :
agent-eval run --task tasks/add-retry-logic.yaml --agent claude-code --agent aider --runs 3
Chaque exécution :
- Crée un nouveau worktree git à partir du commit spécifié
- Soumet le prompt à l'agent
- Exécute les critères du juge
- Enregistre succès/échec, coût et temps
3. Comparer les résultats
Générez un rapport de comparaison :
agent-eval report --format table
Tâche : add-retry-logic (3 exécutions chacune)
┌──────────────┬───────────┬────────┬────────┬─────────────┐
│ Agent │ Taux réussite │ Coût │ Temps │ Cohérence │
├──────────────┼───────────┼────────┼────────┼─────────────┤
│ claude-code │ 3/3 │ $0.12 │ 45s │ 100% │
│ aider │ 2/3 │ $0.08 │ 38s │ 67% │
└──────────────┴───────────┴────────┴────────┴─────────────┘
Types de juges
Basé sur le code (déterministe)
judge:
- type: pytest
command: pytest tests/ -v
- type: command
command: npm run build
Basé sur un motif
judge:
- type: grep
pattern: "class.*Retry"
files: src/**/*.py
Basé sur un modèle (LLM comme juge)
judge:
- type: llm
prompt: |
Cette implémentation gère-t-elle correctement le backoff exponentiel ?
Vérifiez : nombre max de tentatives, délais croissants, gigue.
Bonnes pratiques
- Commencez par 3 à 5 tâches qui représentent votre charge de travail réelle, pas des exemples jouets
- Effectuez au moins 3 essais par agent pour capturer la variance — les agents sont non déterministes
- Épinglez le commit dans votre YAML de tâche afin que les résultats soient reproductibles sur plusieurs jours/semaines
- Incluez au moins un juge déterministe (tests, build) par tâche — les juges LLM ajoutent du bruit
- Suivez le coût en parallèle du taux de réussite — un agent à 95 % pour 10 fois le coût peut ne pas être le bon choix
- Versionnez vos définitions de tâches — ce sont des fixtures de test, traitez-les comme du code