Évaluation des agents

Le crate adk-eval fournit des outils complets pour tester et valider le comportement des agents. Contrairement aux tests logiciels traditionnels, l'évaluation des agents doit prendre en compte la nature probabiliste des LLM tout en fournissant des signaux de qualité significatifs.

Aperçu

L'évaluation des agents dans adk-rust prend en charge plusieurs stratégies d'évaluation :

• Évaluation de Trajectoire : Valider que les agents appellent les outils attendus dans la séquence correcte
• Similarité de Réponse : Comparer les réponses des agents en utilisant divers algorithmes (Jaccard, Levenshtein, ROUGE)
• Évaluation Jugée par LLM : Utiliser un autre LLM pour évaluer la similarité sémantique et la qualité
• Notation Basée sur une Grille : Évaluer selon des critères personnalisés avec une notation pondérée

Démarrage Rapide

use adk_eval::{Evaluator, EvaluationConfig, EvaluationCriteria};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Créer votre agent
    let agent = create_my_agent()?;

    // Configurer l'évaluateur avec des critères
    let config = EvaluationConfig::with_criteria(
        EvaluationCriteria::exact_tools()
            .with_response_similarity(0.8)
    );

    let evaluator = Evaluator::new(config);

    // Exécuter l'évaluation contre le fichier de test
    let report = evaluator
        .evaluate_file(agent, "tests/my_agent.test.json")
        .await?;

    // Vérifier les résultats
    if report.all_passed() {
        println!("All {} tests passed!", report.summary.total);
    } else {
        println!("{}", report.format_summary());
    }

    Ok(())
}

Format du Fichier de Test

Les cas de test sont définis dans des fichiers JSON avec l'extension .test.json :

{
  "eval_set_id": "weather_agent_tests",
  "name": "Weather Agent Tests",
  "description": "Test weather agent functionality",
  "eval_cases": [
    {
      "eval_id": "test_current_weather",
      "conversation": [
        {
          "invocation_id": "inv_001",
          "user_content": {
            "parts": [{"text": "What's the weather in NYC?"}],
            "role": "user"
          },
          "final_response": {
            "parts": [{"text": "The weather in NYC is 65°F and sunny."}],
            "role": "model"
          },
          "intermediate_data": {
            "tool_uses": [
              {
                "name": "get_weather",
                "args": {"location": "NYC"}
              }
            ]
          }
        }
      ]
    }
  ]
}

Critères d'évaluation

Correspondance de la Trajectoire d'Outil

Valide que les agents appellent les outils attendus dans le bon ordre :

let criteria = EvaluationCriteria {
    tool_trajectory_score: Some(1.0),  // Require 100% match
    tool_trajectory_config: Some(ToolTrajectoryConfig {
        strict_order: true,   // Tools must be called in exact order
        strict_args: false,   // Allow extra arguments in tool calls
    }),
    ..Default::default()
};

Options :

• strict_order : Exige une correspondance exacte de la séquence
• strict_args : Exige une correspondance exacte des arguments (aucun argument supplémentaire autorisé)
• Correspondance partielle avec des seuils configurables

Similarité de la Réponse

Compare le texte de la réponse en utilisant divers algorithmes :

let criteria = EvaluationCriteria {
    response_similarity: Some(0.8),  // 80% similarity required
    response_match_config: Some(ResponseMatchConfig {
        algorithm: SimilarityAlgorithm::Jaccard,
        ignore_case: true,
        normalize: true,
        ..Default::default()
    }),
    ..Default::default()
};

Algorithmes disponibles :

Correspondance Sémantique Jugée par LLM

Utilise un LLM pour évaluer l'équivalence sémantique :

use adk_eval::{Evaluator, EvaluationConfig, EvaluationCriteria, LlmJudge};
use adk_model::GeminiModel;

// Create evaluator with LLM judge
let judge_model = Arc::new(GeminiModel::new(&api_key, "gemini-2.0-flash")?);
let config = EvaluationConfig::with_criteria(
    EvaluationCriteria::semantic_match(0.85)
);
let evaluator = Evaluator::with_llm_judge(config, judge_model);

Le juge LLM évalue :

• L'équivalence sémantique (même signification, mots différents)
• L'exactitude factuelle
• L'exhaustivité de la réponse

Évaluation Basée sur une Grille

Évalue selon des critères personnalisés avec une pondération des scores :

use adk_eval::{Rubric, EvaluationCriteria};

let criteria = EvaluationCriteria::default()
    .with_rubrics(0.7, vec![
        Rubric::new("Accuracy", "Response is factually correct")
            .with_weight(0.5),
        Rubric::new("Helpfulness", "Response addresses user's needs")
            .with_weight(0.3),
        Rubric::new("Clarity", "Response is clear and well-organized")
            .with_weight(0.2),
    ]);

Chaque rubrique est notée de 0 à 1 par le juge LLM, puis combinée à l'aide de pondérations.

Détection de Sécurité et d'Hallucinations

Vérifie les réponses pour les problèmes de sécurité et les hallucinations :

let criteria = EvaluationCriteria {
    safety_score: Some(0.95),        // Require high safety score
    hallucination_score: Some(0.9),  // Require low hallucination rate
    ..Default::default()
};

Rapport de Résultats

Le rapport d'évaluation fournit des résultats détaillés :

let report = evaluator.evaluate_file(agent, "tests/agent.test.json").await?;

// Summary statistics
println!("Total: {}", report.summary.total);
println!("Passed: {}", report.summary.passed);
println!("Failed: {}", report.summary.failed);
println!("Pass Rate: {:.1}%", report.summary.pass_rate * 100.0);

// Detailed failures
for result in report.failures() {
    println!("Failed: {}", result.eval_id);
    for failure in &result.failures {
        println!("  - {}: {} (expected: {}, actual: {})",
            failure.criterion,
            failure.message,
            failure.expected,
            failure.actual
        );
    }
}

// Export to JSON for CI/CD
let json = report.to_json()?;
std::fs::write("eval_results.json", json)?;

Évaluation par lots

Évaluation Parallèle

Évalue plusieurs cas de test simultanément :

let results = evaluator
    .evaluate_cases_parallel(agent, &cases, 4)  // 4 concurrent evaluations
    .await;

Évaluation de Répertoire

Évalue tous les fichiers de test dans un répertoire :

let reports = evaluator
    .evaluate_directory(agent, "tests/eval_cases")
    .await?;

for (file, report) in reports {
    println!("{}: {} passed, {} failed",
        file,
        report.summary.passed,
        report.summary.failed
    );
}

Intégration avec cargo test

Utilise l'évaluation dans les tests Rust standards :

#[tokio::test]
async fn test_weather_agent() {
    let agent = create_weather_agent().unwrap();
    let evaluator = Evaluator::new(EvaluationConfig::with_criteria(
        EvaluationCriteria::exact_tools()
    ));

    let report = evaluator
        .evaluate_file(agent, "tests/weather_agent.test.json")
        .await
        .unwrap();

    assert!(report.all_passed(), "{}", report.format_summary());
}

Exemples

# Basic evaluation
cargo run --example eval_basic

# Trajectory validation
cargo run --example eval_trajectory

# LLM-judged semantic matching
cargo run --example eval_semantic

# Rubric-based scoring
cargo run --example eval_rubric

# Response similarity algorithms
cargo run --example eval_similarity

# Report generation
cargo run --example eval_report

Bonnes Pratiques

1. Commencez Simple : Commencez par la validation de la trajectoire avant d'ajouter des vérifications sémantiques
2. Utilisez des Cas Représentatifs : Les fichiers de test doivent couvrir les cas limites et les scénarios courants
3. Calibrez les Seuils : Commencez avec des seuils indulgents et resserrez-les à mesure que l'Agent s'améliore
4. Combinez les Critères : Utilisez plusieurs critères pour une évaluation complète
5. Versionnez les Fichiers de Test : Conservez les fichiers de test sous contrôle de version avec le code de l'Agent
6. Intégration CI/CD : Exécutez les évaluations en CI pour détecter les régressions

---

Précédent : ← A2A Protocol | Suivant : Access Control →