#
Unité Bonus 2 : Observabilité et Évaluation des Agents

Vous pouvez suivre le code dans ce notebook que vous pouvez exécuter avec *Google Colab*.

Dans ce notebook, nous apprendrons comment surveiller les étapes internes (traces) de notre agent IA et évaluer ses performances en utilisant des outils d’observabilité open source.

La capacité d’observer et d’évaluer le comportement d’un agent est essentielle pour :

- Déboguer les problèmes quand les tâches échouent ou produisent des résultats sous-optimaux
- Surveiller les coûts et performances en temps réel
- Améliorer la fiabilité et la sécurité grâce à des commentaires continus

##
Prérequis de l’exercice 🏗️

Avant d’exécuter ce notebook, assurez-vous d’avoir :

🔲 📚 Étudié Introduction aux Agents

🔲 📚 Étudié Le framework smolagents

##
Étape 0 : Installer les bibliothèques requises

Nous aurons besoin de quelques bibliothèques qui nous permettent d’exécuter, surveiller et évaluer nos agents :

    %pip install langfuse 'smolagents[telemetry]' openinference-instrumentation-smolagents datasets 'smolagents[gradio]' gradio --upgrade

##
Étape 1 : Instrumenter votre Agent

Dans ce notebook, nous utiliserons Langfuse comme notre outil d’observabilité, mais vous pouvez utiliser n’importe quel autre service compatible OpenTelemetry. Le code ci-dessous montre comment définir les variables d’environnement pour Langfuse (ou tout endpoint OTel) et comment instrumenter votre smolagent.

Note : Si vous utilisez LlamaIndex ou LangGraph, vous pouvez trouver de la documentation sur leur instrumentation ici et ici.

D’abord, configurons les credentials Langfuse comme variables d’environnement. Obtenez vos clés API Langfuse en vous inscrivant sur Langfuse Cloud ou en auto-hébergeant Langfuse.

    import os
    # Obtenez les clés pour votre projet depuis la page des paramètres du projet : https://cloud.langfuse.com
    os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
    os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
    os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" # 🇪🇺 région EU
    # os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 région US

Nous devons aussi configurer notre token Hugging Face pour les appels d’inférence.

    # Définissez votre token Hugging Face et autres tokens/secrets comme variable d'environnement
    os.environ["HF_TOKEN"] = "hf_..."

Avec les variables d’environnement définies, nous pouvons maintenant initialiser le client Langfuse. `get_client()` initialise le client Langfuse en utilisant les credentials fournis dans les variables d’environnement.

    from langfuse import get_client

    langfuse = get_client()

    # Vérifier la connexion
    if langfuse.auth_check():
        print("Le client Langfuse est authentifié et prêt !")
    else:
        print("L'authentification a échoué. Veuillez vérifier vos credentials et hôte.")

Ensuite, nous pouvons configurer le `SmolagentsInstrumentor()` pour instrumenter notre smolagent et envoyer des traces à Langfuse.

    from openinference.instrumentation.smolagents import SmolagentsInstrumentor

    SmolagentsInstrumentor().instrument()

##
Étape 2 : Tester votre instrumentation

Voici un simple CodeAgent de smolagents qui calcule `1+1`. Nous l’exécutons pour confirmer que l’instrumentation fonctionne correctement. Si tout est configuré correctement, vous verrez des logs/spans dans votre tableau de bord d’observabilité.

    from smolagents import InferenceClientModel, CodeAgent

    # Créer un agent simple pour tester l'instrumentation
    agent = CodeAgent(
        tools=[],
        model=InferenceClientModel()
    )

    agent.run("1+1=")

Vérifiez votre Tableau de bord des traces Langfuse (ou votre outil d’observabilité choisi) pour confirmer que les spans et logs ont été enregistrés.

Exemple de capture d’écran de Langfuse :

Lien vers la trace

##
Étape 3 : Observer et évaluer un agent plus complexe

Maintenant que vous avez confirmé que votre instrumentation fonctionne, essayons une requête plus complexe pour que nous puissions voir comment les métriques avancées (utilisation de tokens, latence, coûts, etc.) sont suivies.

    from smolagents import (CodeAgent, DuckDuckGoSearchTool, InferenceClientModel)

    search_tool = DuckDuckGoSearchTool()
    agent = CodeAgent(tools=[search_tool], model=InferenceClientModel())

    agent.run("Combien de Rubik's Cubes pourrait-on faire tenir dans la Cathédrale Notre-Dame ?")

###
Structure de la trace

La plupart des outils d’observabilité enregistrent une trace qui contient des spans, qui représentent chaque étape de la logique de votre agent. Ici, la trace contient l’exécution globale de l’agent et des sous-spans pour :

- Les appels d’outils (DuckDuckGoSearchTool)
- Les appels LLM (InferenceClientModel)

Vous pouvez les inspecter pour voir précisément où le temps est passé, combien de tokens sont utilisés, etc. :

Lien vers la trace

##
Évaluation en ligne

Dans la section précédente, nous avons appris la différence entre l’évaluation en ligne et hors ligne. Maintenant, nous verrons comment surveiller votre agent en production et l’évaluer en direct.

###
Métriques communes à suivre en production

1. Coûts — L’instrumentation smolagents capture l’utilisation de tokens, que vous pouvez transformer en coûts approximatifs en assignant un prix par token.
2. Latence — Observer le temps qu’il faut pour compléter chaque étape, ou l’exécution entière.
3. Commentaires utilisateur — Les utilisateurs peuvent fournir des commentaires directs (pouces levés/baissés) pour aider à raffiner ou corriger l’agent.
4. LLM-as-a-Judge — Utiliser un LLM séparé pour évaluer la sortie de votre agent en temps quasi réel (par exemple, vérifier la toxicité ou l’exactitude).

Ci-dessous, nous montrons des exemples de ces métriques.

####
1. Coûts

Ci-dessous se trouve une capture d’écran montrant l’utilisation pour les appels `Qwen2.5-Coder-32B-Instruct`. C’est utile pour voir les étapes coûteuses et optimiser votre agent.

Lien vers la trace

####
2. Latence

Nous pouvons aussi voir combien de temps il a fallu pour compléter chaque étape. Dans l’exemple ci-dessous, toute la conversation a pris 32 secondes, que vous pouvez décomposer par étape. Cela vous aide à identifier les goulots d’étranglement et optimiser votre agent.

Lien vers la trace

####
3. Attributs supplémentaires

Vous pouvez aussi passer des attributs supplémentaires à vos spans. Ceux-ci peuvent inclure `user_id`, `tags`, `session_id`, et des métadonnées personnalisées. Enrichir les traces avec ces détails est important pour l’analyse, le débogage et la surveillance du comportement de votre application à travers différents utilisateurs ou sessions.

    from smolagents import (CodeAgent, DuckDuckGoSearchTool, InferenceClientModel)

    search_tool = DuckDuckGoSearchTool()
    agent = CodeAgent(
        tools=[search_tool],
        model=InferenceClientModel()
    )

    with langfuse.start_as_current_span(
        name="Smolagent-Trace",
        ) as span:

        # Exécutez votre application ici
        response = agent.run("Quelle est la capitale de l'Allemagne ?")

        # Passez des attributs supplémentaires au span
        span.update_trace(
            input="Quelle est la capitale de l'Allemagne ?",
            output=response,
            user_id="smolagent-user-123",
            session_id="smolagent-session-123456789",
            tags=["question-ville", "test-agents"],
            metadata={"email": "user@langfuse.com"},
            )

    # Flusher les événements dans les applications de courte durée
    langfuse.flush()

####
4. Commentaires utilisateur

Si votre agent est intégré dans une interface utilisateur, vous pouvez enregistrer des commentaires utilisateur directs (comme un pouce levé/baissé dans une interface de chat). Ci-dessous se trouve un exemple utilisant Gradio pour intégrer un chat avec un mécanisme simple de commentaires.

Dans l’extrait de code ci-dessous, quand un utilisateur envoie un message de chat, nous capturons la trace dans Langfuse. Si l’utilisateur aime/n’aime pas la dernière réponse, nous attachons un score à la trace.

    import gradio as gr
    from smolagents import (CodeAgent, InferenceClientModel)
    from langfuse import get_client

    langfuse = get_client()

    model = InferenceClientModel()
    agent = CodeAgent(tools=[], model=model, add_base_tools=True)

    trace_id = None

    def respond(prompt, history):
        with langfuse.start_as_current_span(
            name="Smolagent-Trace"):

            # Exécutez votre application ici
            output = agent.run(prompt)

            global trace_id
            trace_id = langfuse.get_current_trace_id()

        history.append({"role": "assistant", "content": str(output)})
        return history

    def handle_like(data: gr.LikeData):
        # Pour la démonstration, nous mappons les commentaires utilisateur à 1 (j'aime) ou 0 (je n'aime pas)
        if data.liked:
            langfuse.create_score(
                value=1,
                name="user-feedback",
                trace_id=trace_id
            )
        else:
            langfuse.create_score(
                value=0,
                name="user-feedback",
                trace_id=trace_id
            )

    with gr.Blocks() as demo:
        chatbot = gr.Chatbot(label="Chat", type="messages")
        prompt_box = gr.Textbox(placeholder="Tapez votre message...", label="Votre message")

        # Quand l'utilisateur appuie sur 'Entrée' sur le prompt, nous exécutons 'respond'
        prompt_box.submit(
            fn=respond,
            inputs=[prompt_box, chatbot],
            outputs=chatbot
        )

        # Quand l'utilisateur clique sur un bouton 'j'aime' sur un message, nous exécutons 'handle_like'
        chatbot.like(handle_like, None, None)

    demo.launch()

Les commentaires utilisateur sont alors capturés dans votre outil d’observabilité :

####
5. LLM-as-a-Judge

LLM-as-a-Judge est une autre façon d’évaluer automatiquement la sortie de votre agent. Vous pouvez configurer un appel LLM séparé pour évaluer l’exactitude, la toxicité, le style, ou tout autre critère qui vous tient à cœur de la sortie.

Flux de travail :

1. Vous définissez un Template d’évaluation, par exemple, “Vérifiez si le texte est toxique.”
2. Chaque fois que votre agent génère une sortie, vous passez cette sortie à votre LLM “juge” avec le template.
3. Le LLM juge répond avec une note ou un label que vous loggez dans votre outil d’observabilité.

Exemple de Langfuse :

    # Exemple : Vérifier si la sortie de l'agent est toxique ou non.
    from smolagents import (CodeAgent, DuckDuckGoSearchTool, InferenceClientModel)

    search_tool = DuckDuckGoSearchTool()
    agent = CodeAgent(tools=[search_tool], model=InferenceClientModel())

    agent.run("Manger des carottes peut-il améliorer votre vision ?")

Vous pouvez voir que la réponse de cet exemple est jugée comme “non toxique”.

####
6. Aperçu des métriques d’observabilité

Toutes ces métriques peuvent être visualisées ensemble dans des tableaux de bord. Cela vous permet de voir rapidement comment votre agent performe à travers de nombreuses sessions et vous aide à suivre les métriques de qualité au fil du temps.

##
Évaluation hors ligne

L’évaluation en ligne est essentielle pour les commentaires en direct, mais vous avez aussi besoin d’évaluation hors ligne—des vérifications systématiques avant ou pendant le développement. Cela aide à maintenir la qualité et la fiabilité avant de déployer les changements en production.

###
Évaluation de jeu de données

Dans l’évaluation hors ligne, vous typiquement :

1. Avez un jeu de données de référence (avec des paires prompt et sortie attendue)
2. Exécutez votre agent sur ce jeu de données
3. Comparez les sorties aux résultats attendus ou utilisez un mécanisme de notation supplémentaire

Ci-dessous, nous démontrons cette approche avec le jeu de données GSM8K, qui contient des questions et solutions mathématiques.

    import pandas as pd
    from datasets import load_dataset

    # Récupérer GSM8K de Hugging Face
    dataset = load_dataset("openai/gsm8k", 'main', split='train')
    df = pd.DataFrame(dataset)
    print("Premières lignes du jeu de données GSM8K :")
    print(df.head())

Ensuite, nous créons une entité de jeu de données dans Langfuse pour suivre les exécutions. Puis, nous ajoutons chaque élément du jeu de données au système. (Si vous n’utilisez pas Langfuse, vous pourriez simplement stocker ceux-ci dans votre propre base de données ou fichier local pour l’analyse.)

    from langfuse import get_client
    langfuse = get_client()

    langfuse_dataset_name = "gsm8k_dataset_huggingface"

    # Créer un jeu de données dans Langfuse
    langfuse.create_dataset(
        name=langfuse_dataset_name,
        description="Jeu de données de référence GSM8K téléchargé depuis Huggingface",
        metadata={
            "date": "2025-03-10",
            "type": "benchmark"
        }
    )

    for idx, row in df.iterrows():
        langfuse.create_dataset_item(
            dataset_name=langfuse_dataset_name,
            input={"text": row["question"]},
            expected_output={"text": row["answer"]},
            metadata={"source_index": idx}
        )
        if idx >= 9: # Télécharger seulement les 10 premiers éléments pour la démonstration
            break

####
Exécuter l’agent sur le jeu de données

Nous définissons une fonction helper `run_smolagent()` qui :

1. Démarre un span Langfuse
2. Exécute notre agent sur le prompt
3. Enregistre l’ID de trace dans Langfuse

Puis, nous bouclons sur chaque élément du jeu de données, exécutons l’agent, et lions la trace à l’élément du jeu de données. Nous pouvons aussi attacher un score d’évaluation rapide si désiré.

    from opentelemetry.trace import format_trace_id
    from smolagents import (CodeAgent, InferenceClientModel, LiteLLMModel)
    from langfuse import get_client

    langfuse = get_client()

    # Exemple : utiliser InferenceClientModel ou LiteLLMModel pour accéder aux modèles openai, anthropic, gemini, etc. :
    model = InferenceClientModel()

    agent = CodeAgent(
        tools=[],
        model=model,
        add_base_tools=True
    )

    dataset_name = "gsm8k_dataset_huggingface"
    current_run_name = "smolagent-notebook-run-01" # Identifie cette exécution d'évaluation spécifique

    # Supposons que 'run_smolagent' est votre fonction d'application instrumentée
    def run_smolagent(question):
        with langfuse.start_as_current_generation(name="qna-llm-call") as generation:
            # Simuler un appel LLM
            result = agent.run(question)

            # Mettre à jour la trace avec l'entrée et la sortie
            generation.update_trace(
                input= question,
                output=result,
            )

            return result

    dataset = langfuse.get_dataset(name=dataset_name) # Récupérer votre jeu de données pré-peuplé

    for item in dataset.items:

        # Utiliser le gestionnaire de contexte item.run()
        with item.run(
            run_name=current_run_name,
            run_metadata={"model_provider": "Hugging Face", "temperature_setting": 0.7},
            run_description="Exécution d'évaluation pour le jeu de données GSM8K"
        ) as root_span: # root_span est le span racine de la nouvelle trace pour cet élément et exécution.
            # Toutes les opérations langfuse suivantes dans ce bloc font partie de cette trace.

            # Appelez votre logique d'application
            generated_answer = run_smolagent(question=item.input["text"])

            print(item.input)

Vous pouvez répéter ce processus avec différents :

- Modèles (OpenAI GPT, LLM local, etc.)
- Outils (recherche vs. pas de recherche)
- Prompts (différents messages système)

Puis les comparer côte à côte dans votre outil d’observabilité :

##
Réflexions finales

Dans ce notebook, nous avons couvert comment :

1. Configurer l’observabilité en utilisant smolagents + exporteurs OpenTelemetry
2. Vérifier l’instrumentation en exécutant un agent simple
3. Capturer des métriques détaillées (coût, latence, etc.) via des outils d’observabilité
4. Collecter des commentaires utilisateur via une interface Gradio
5. Utiliser LLM-as-a-Judge pour évaluer automatiquement les sorties
6. Effectuer une évaluation hors ligne avec un jeu de données de référence

🤗 Bon codage !

< > Update on GitHub