Gestion des compétences agents

Gestion des compétences agents : l’échec du test manuel

Non classé

Retour d'expérience RubyAvancé

Gestion des compétences agents : l'échec du test manuel

Le déploiement d’un agent autonome sans protocole de test est une bombe à retardement. Nous avons appris cette leçon à la dure lors d’une mise à jour de prompt en production.

La gestion des compétences agents est devenue impossible à piloter manuellement. Notre taux d’erreur sur l’appel des outils est passé de 4% à 22% en une seule nuit. Nous n’avions aucun indicateur de régression sur la fiabilité des appels de fonctions.

Cet article détaille l’implémentation de sivchari pour automatiser la validation et la mesure de la qualité des outils de vos LLM.

Gestion des compétences agents

🛠️ Prérequis

Environnement de développement prêt pour l’évaluation d’agents.

  • Python 3.11 ou supérieur installé.
  • Accès à une API compatible OpenAI (GPT-4o) ou un serveur local Ollama (version 0.3.0+).
  • Installation de la librairie via : pip install sivchari==0.1.2
  • Un fichier de configuration YAML pour vos tests.

📚 Comprendre Gestion des compétences agents

La gestion des compétences agents repose sur la standardisation de l’interface entre le LLM et l’action. Un agent ne possède pas seulement du texte, il possède des outils (skills).

Le framework sivchari structure ce processus en quatre étapes cycliques :

[Définition] -> (YAML/Python) : On définit l'entrée, la sortie attendue et le type d'outil.
[Création]  -> (Prompt Engineering) : On écrit le prompt qui active la compétence.
[Test]      -> (Dataset) : On injecte des requêtes réelles et attendues.
[Mesure]    -> (Metrics) : On calcule la précision, le rappel et la latence.

Contrairement à une suite de tests unitaires classique, nous ne vérifions pas une valeur exacte. Nous évaluons une conformité sémantique et structurelle. C’est une approche proche du testing de contrats en microservices, mais appliquée à l’incertitude du langage naturel.

💎 Le code — Gestion des compétences agents

Ruby
import sivchari

# Définition d'une compétence de recherche de fichiers
# On utilise le décorateur pour lier le prompt à une fonction Python
@sivchari.skill(name="file_search", description="Recherche un fichier par son nom")
def search_file_skill(query: str):
    # Simulation d'une base de données de fichiers
    files = ["config.json", "README.md", "setup.py"]
    # Logique de recherche simple
    result = [f for f following in files if query.lower() in f.lower()]
    return {"matches": result}

# Configuration du moteur d'évaluation
# On définit ici les paramètres de la gestion des compétences agents
engine = sivchari.EvaluationEngine(model="gpt-4o")

# Chargement de la configuration de test
# Le fichier contient les inputs et les outputs attendus
engine.load_test_suite("tests/skills/file_search_suite.yaml")

📖 Explication

Dans le premier snippet, le décorateur @sivchari.skill est crucial. Il ne se contente pas de documenter la fonction. Il extrait la signature Python pour générer automatiquement le schéma JSON nécessaire au LLM. C’est le principe du moindre étonnement : le développeur écrit du Python standard, et le framework s’occupe de la traduction pour l’agent.

La méthode engine.load_test_suite lit un fichier YAML. Ce fichier est le cœur de la gestion des compétences agents. Il contient des paires input/output. Pour chaque input, le framework demande au LLM d’utiliser l’outil et compare le résultat avec l’attendu.

Dans le second snippet, nous utilisons pytest. Il est important de ne pas confondre les deux. pytest teste votre code Python (la logique de recherche). sivchari teste la capacité du LLM à utiliser ce code (le prompt). L’un vérifie l’implémentation, l’autre vérifie l’orchestration.

Un piège classique : oublier de définir un expected_substring quand on teste des sorties textuelles. Si vous attendez un match exact, le moindre espace ou retour à la ligne échouera le test. Utilisez toujours des assertions de sous-chaîne ou des regex.

Documentation officielle Ruby

🔄 Second exemple

Ruby
import yaml
import pytest
from my_agent import search_file_skill

# Test de régression pour la gestion des compétences agents
@pytest.mark.parametrize("input_query, expected_substring", [
    ("config", "config.json"),
    ("readme", "README.md"),
    ("non_existent", None)
])
def test_skill_accuracy(input_query, expected_substring):
    """Vérifie que l'outil retourne bien le bon fichier"""
    # Appel de la fonction de l'agent
    response = search_file_skill(input_query)
    
    if expected_substring is None:
        # On vérore que la liste est vide si rien n'est trouvé
        assert len(response["matches"]) == 0
    else:
        # On vérifie la présence du fichier dans les résultats
        assert any(expected_substring in m for m in response["matches"])

# Note: Ce test est complémentaire à sivchari
# Il vérifie la logique Python, pas la qualité du prompt LLM

Retour d'expérience

Le 14 juin dernier, notre équipe a poussé une modification mineure sur le système de prompt global. L’objectif était d’ajouter une consigne de politesse. Nous avons utilisé une méthode de validation classique : un test de présence de mots-clés dans la réponse.

Cependant, la gestion des compétences agents a été totalement ignorée. Le nouveau prompt rendait l’agent « trop bavard ». En voulant être poli, l’agent ajoutait des phrases d’introduction avant son appel d’outil. Résultat : le parseur JSON de notre backend plantait systématiquement. L’agent envoyait : « Bonjour ! Voici le résultat : {« matches »: [« config.json »]} » au lieu du JSON pur.

En production, cela a provoqué une cascade d’erreurs. Notre monitoring montrait une explosion des erreurs 500. Nous avons mis 4 heures à identifier que le problème ne venait pas du code Python, mais de la structure de la réponse du LLM. Le code était identique, mais la compétence d’appel d’outil était devenue invalide.

Pour corriger cela, nous avons implémenté sivchari. Nous avons créé un pipeline de validation qui exécute la suite de tests à chaque modification de prompt. Désormais, si le format de sortie change, le test de conformité échoue avant le déploiement. La gestion des compétences agents est devenue une étape bloquante dans notre GitLab CI.

Nous avons introduit une métrique de « Schema Adherence ». Si le taux de conformité JSON descend sous 99.5%, le déploiement est annulé. Cela a réduit nos régressions de production de 85% en trois mois.

▶️ Exemple d’utilisation

Exécution d’un test de compétence via la ligne de commande pour vérifier la recherche de fichiers.

$ sivchari test --skill file_search --suite tests/skills/file_search_suite.yaml

Running tests for skill: file_search
[PASS] input: "config" -> expected: ["config.json"]
[PASS] input: "readme" -> expected: ["README.md"]
[FAIL] input: "unknown" -> expected: [] (Found: ["unknown_file.txt"])

Summary:
  Passed: 2
  Failed: 1
  Accuracy: 66.6%
  Latency: 1.2s

🚀 Cas d’usage avancés

1. Détection de dérive de performance (Drift Detection) : En exécutant la gestion des compétences agents sur un échantillon de logs réels, on peut détecter quand une mise à niveau du modèle (ex: passage de GPT-4 à GPT-4o) altère la précision des outils.

2. A/B Testing de Prompts : Vous pouvez faire tourner deux versions du prompt sur la même suite de tests sivchari et comparer le score de success_rate de manière statistique. results = engine.compare("prompt_v1", "prompt_v2")

3. Génération de données de test : Utiliser le framework pour géner automatiquement des cas limites (edge cases) en injectant des inputs malformés pour tester la résilience de la gestion des compétences agents.

🐛 Erreurs courantes

⚠️ Confusion entre test de code et test d'agent

Tester la fonction Python sans tester le prompt qui l’appelle.

✗ Mauvais

pytest test_my_function()
✓ Correct

sivchari test --skill my_skill

⚠️ Format de sortie non strict

Attendre un JSON exact alors que le LLM ajoute du texte.

✗ Mauvais

assert response == '{"key": "val"}'
✓ Correct

assert json.loads(response)['key'] == 'val'

⚠️ Absence de seed pour la reproductibilité

Les tests échouent aléatoirement à cause de la température du LLM.

✗ Mauvais

temperature=1.0
✓ Correct

temperature=0.0

⚠️ Oubli de la gestion des erreurs de schéma

Le test passe si le LLM ne répond rien, mais l’agent est cassé.

✗ Mauvais

assert response is not None
✓ Correct

assert validate_schema(response, schema)

✅ Bonnes pratiques

Pour une gestion des compétences agents professionnelle, suivez ces principes :

  • Température à zéro : Pour les tests de régression, fixez toujours la température du modèle à 0.0 pour garantir la reproductibilité des résultats.
  • Versioning des compétences : Traitez vos fichiers de test YAML comme du code source. Ils doivent suivre le même cycle de vie que vos fonctions Python.
  • Isolation des environnements : Utilisez des environnements Docker pour vos tests afin d’éviter que des variables d’environnement locales n’influencent les résultats de la gestion des compétences agents.
  • Granularité des métriques : Ne vous contentez pas d’un taux de succès global. Mesurez la latence par outil et le taux de conformité au schéma JSON séparément.
  • Approche par contrat : Définissez vos outils avec des types Python stricts (Type Hinting). Cela facilite la génération de schames par sivchari.
Points clés

  • La gestion des compétences agents nécessite un cadre de test automatisé.
  • Le test manuel de prompt est une source majeure de régressions en production.
  • Sivchari permet de transformer des prompts incertains en tests structurés.
  • Il faut distinguer le test de la logique Python du test de l'appel LLM.
  • La température 0 est indispensable pour la reproductibilité des tests.
  • L'automatisation de la validation du schéma JSON empêche les plantages de parsing.
  • L'intégration dans la CI/CD est la seule garantie de stabilité à long terme.
  • Utilisez des métriques de latence pour surveiller l'impact des nouveaux prompts.

❓ Questions fréquentes

Peut-on utiliser sivchari avec des modèles locaux ?

Oui, tant que votre modèle (via Ollama ou vLLM) supporte les appels de fonctions (function calling) et une API compatible OpenAI.

Comment gérer les tests trop coûteux en API ?

Utilisez un sous-ensemble réduit de votre suite de tests (smoke tests) pour les commits rapides, et lancez la suite complète uniquement lors des merges sur la branche principale.

Est-ce que sivchari supporte le multi-agent ?

Le framework se concentre sur les compétences individuelles. Pour le multi-agent, vous devez définir des suites de tests qui évaluent l’interaction entre les compétences de différents agents.

Quel est l'impact sur la performance de l'agent ?

L’utilisation de sivchari n’impacte pas la performance de l’agent en production, car il ne sert que durant la phase de test et de validation.

📚 Sur le même blog

🔗 Le même sujet sur nos autres blogs

📝 Conclusion

La gestion des compétences agents ne doit pas être une option. Sans cadre de mesure, chaque modification de prompt est un pari risqué sur la stabilité de votre système. L’adoption de outils comme sivchari permet de transformer l’intuition en ingénierie. Pour approfondir la manipulation des types en Python, consultez la documentation officielle de Python. Un bon test est celui qui échoue quand il le faut, pas celui qui passe par chance.

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *