Présentation

Datadog fournit un ensemble de compétences Claude Code qui intègrent l’analyse Agent Observability directement dans votre workflow de développement. Plutôt que de naviguer manuellement dans les dashboards, vous pouvez invoquer ces compétences depuis une session Claude Code pour classer les sessions, diagnostiquer les échecs, comparer les expériences, générer du code d’expérience Python et initialiser des évaluateurs — le tout à partir de vos données de production réelles.

Les compétences produisent des résultats structurés et exploitables — rapports RCA avec des propositions de correctifs avant/après, code d’évaluateur généré, comparaisons d’expériences — que vous pouvez transmettre directement à un agent de codage pour appliquer des correctifs à votre application. Lorsque Claude Code a accès à votre base de code, il peut rechercher le prompt système pertinent, les définitions d’outils ou la logique de routage et proposer des diffs spécifiques sans quitter la session.

Configuration

Prérequis

• Claude Code installé et authentifié
• Au moins une application LLM instrumentée avec Agent Observability et produisant des traces
• Un backend de données : soit le Datadog MCP Server soit la pup CLI

Installer les compétences

Les compétences sont publiées dans le dépôt agent-skills. Installez-les avec la commande suivante :

npx skills add datadog-labs/agent-skills/agent-observability --full-depth -y

Les compétences sont disponibles dans toute session Claude Code après l’installation.

Datadog MCP Server

Pour utiliser l’option Datadog MCP server, connectez l’Agent Observability MCP server à votre session Claude Code :

claude mcp add --scope user --transport http datadog-llmo-mcp \
  '?toolsets=llmobs,core'

Toutes les compétences détectent automatiquement le MCP server au démarrage et l’utilisent en continu.

Option B : pup CLI

Si vous préférez ne pas utiliser le MCP server, les compétences fonctionnent également via pup, l’interface de ligne de commande interne de Datadog. Installez pup et authentifiez-vous :

pup auth login

Chaque compétence détecte au démarrage si le MCP server est disponible ; sinon, elle vérifie la présence de pup et bascule automatiquement en pup mode. Vous pouvez également forcer explicitement le pup mode en passant --backend pup à n’importe quelle invocation de compétence.

En pup mode, tous les appels à Datadog API sont effectués via des sous-commandes pup llm-obs au lieu d’outils MCP. La sortie et le workflow sont identiques.

Compétences

Classer les sessions et les traces

/agent-observability-session-classify évalue si l’intention d’un utilisateur a été satisfaite lors d’une interaction donnée. Il fonctionne selon trois modes en fonction de ce que vous fournissez :

La compétence s’appuie sur jusqu’à trois sources de signaux, et la précision s’améliore à mesure qu’elle a accès à davantage de données :

• Traces d’Agent Observability — l’arborescence complète des spans, le contenu de la conversation, les résultats des appels d’outils, et les verdicts d’évaluation judge. Toujours disponible.
• Signaux comportementaux RUM — pages vues, actions personnalisées, temps de séjour et événements de feedback explicites qui confirment ou contredisent ce que montre la trace. Disponible lorsque RUM est instrumenté pour votre application.
• Audit Trail — événements d’écriture confirmés par le serveur (dashboards créés, monitors modifiés, carnets supprimés) qui prouvent si les actions de l’assistant ont réellement abouti. Signal le plus fiable lorsque la session impliquait la création ou la modification d’actifs.

La compétence renvoie par défaut un verdict yes / partial / no compact avec une raison en une phrase. Ajoutez verbose: true pour un rapport complet au format markdown.

Exemples :

/agent-observability-session-classify session_id=abc-123
/agent-observability-session-classify trace_id=def-456
/agent-observability-session-classify ml_app=my-chatbot --timeframe now-7d

Diagnostiquer les échecs avec une analyse des causes profondes

/agent-observability-trace-rca parcourt l’arborescence des spans des traces en échec pour identifier pourquoi votre application LLM produit de mauvais résultats. Il sélectionne le meilleur mode d’analyse en fonction des signaux disponibles : verdicts d’évaluation LLM-judge (signal le plus fort), erreurs d’exécution ou anomalies structurelles telles que les valeurs aberrantes de latence et les décisions dans une boucle d’agent.

La compétence échantillonne les spans en échec, les regroupe dans une taxonomie d’échecs et compile un rapport RCA structuré avec des catégories de causes profondes, des preuves à l’appui et des propositions de correction concrètes. Chaque correction inclut le texte ou le code réel de la trace — extraits de prompt système, formes d’arguments d’outils, logique de routage — avec un BEFORE / AFTER montrant exactement ce qu’il faut changer.

Lorsque Claude Code a accès à votre base de code, la compétence recherche les fichiers sources pertinents et propose des diffs que vous pouvez appliquer immédiatement. Pour les lacunes du prompt système, le mauvais usage des outils ou les erreurs de routage, cela signifie passer du diagnostic à une pull request sans quitter la session.

Exemples :

/agent-observability-trace-rca ml_app=my-chatbot
/agent-observability-trace-rca ml_app=my-chatbot eval_name=faithfulness --timeframe now-24h

Analyser et comparer des expériences

/agent-observability-experiment-analyzer récupère les résultats d’expériences et met en évidence ce qui a changé entre un candidat et une baseline. Cela fonctionne pour une seule expérience (analyse exploratoire) ou une paire (analyse comparative).

La compétence met en évidence les métriques qui se sont améliorées ou ont régressé, les catégories d’événements qui ont changé et les points où le candidat a sous-performé — afin que vous puissiez prendre une décision de promotion en toute confiance.

Exemples

/agent-observability-experiment-analyzer experiment_id=exp-123
/agent-observability-experiment-analyzer experiment_id=exp-456 baseline_id=exp-123

Générer du code d’expérience avec le SDK Python

/agent-observability-experiment-py-bootstrap émet un script .py autonome ou un notebook Jupyter .ipynb qui utilise le SDK ddtrace.llmobs et correspond aux notebooks de référence.

Le jeu de données peut être un fichier DatasetRecordRaw[] JSON local (intégré au fichier), un CSV (chargé à l’exécution via LLMObs.create_dataset_from_csv), un jeu de données Datadog existant par son nom (LLMObs.pull_dataset), ou — par défaut — un petit échantillon en ligne de 3 enregistrements.

Tous les flags ci-dessous sont facultatifs. Appelez /agent-observability-experiment-py-bootstrap sans argument et la compétence vous demandera ce dont elle a besoin et émettra un fichier exécutable basé sur l’échantillon par défaut de 3 enregistrements.

Exemples

/agent-observability-experiment-py-bootstrap --purpose "validate output accuracy"
/agent-observability-experiment-py-bootstrap --purpose "test tool selection on ambiguous queries" --dataset ./data/qa.json
/agent-observability-experiment-py-bootstrap --dataset-name qa_v3 --project-name customer-qa
/agent-observability-experiment-py-bootstrap --task-source mymodule.handlers:respond --evaluator-style remote
/agent-observability-experiment-py-bootstrap --placeholder-task --format ipynb

Bootstrap des évaluateurs à partir des données de trace

/agent-observability-eval-bootstrap analyse les traces de production d’une ml_app (ou d’un rapport RCA déjà en contexte) et propose une suite d’évaluateurs qui détecteraient les modes de défaillance observés. Il génère l’un des quatre artefacts suivants :

Les trois premiers modes partagent le même workflow de proposition d’évaluateur et ne diffèrent que par la manière dont la suite est matérialisée. Le quatrième mode (--emit-dataset) est indépendant — il échantillonne les spans racines pour le ml_app (filtré sur @status:ok), extrait input_data et expected_output par enregistrement, exécute un nettoyage des PII sur les valeurs de chaîne, et écrit un fichier JSON que vous pouvez publier sur Datadog en tant que jeu de données, puis utiliser pour exécuter une expérience. Les tags par enregistrement sont normalisés automatiquement (les chaînes brutes sont encapsulées sous forme de tag:<value>) afin que Dataset.append() ne rejette pas l’enregistrement. Le champ expected_output est documenté comme la baseline du comportement en production, et non comme une vérité absolue — utile pour les expériences de type régression (mon refactoring modifie-t-il les sorties observées ?) avant d’être promu vers un labelled gold set.

Exemples

/agent-observability-eval-bootstrap ml_app=my-chatbot
/agent-observability-eval-bootstrap ml_app=my-chatbot --publish
/agent-observability-eval-bootstrap ml_app=my-chatbot --data-only
/agent-observability-eval-bootstrap ml_app=my-chatbot --emit-dataset ./datasets/my_chatbot_seed.json --trace-limit 25

Exécutez le pipeline de bout en bout

/agent-observability-eval-pipeline enchaîne les sous-compétences d’observabilité des agents en un workflow supervisé et narré unique qui va des traces de production aux évaluateurs, jeux de données, expériences et analyses. Chaque phase possède la même enveloppe — une bannière qui nomme l’entité produite, un bloc pédagogique expliquant son objectif, l’action (un appel de sous-compétence ou une petite étape exécutable) et un point de contrôle qui attend votre confirmation. C’est le point de départ recommandé lorsque vous n’avez pas d’évaluateurs ou d’expériences existants et que vous souhaitez une procédure pas à pas déterministe.

Phase 1: Classify ml_app traces      → agent-observability-session-classify (ml_app mode)
Phase 2: Root cause analysis         → agent-observability-trace-rca
Phase 3: Bootstrap evaluators        → agent-observability-eval-bootstrap
Phase 4: Create + publish dataset    → agent-observability-eval-bootstrap --emit-dataset + LLMObs.create_dataset(records=...)
Phase 5: Generate + run experiment   → agent-observability-experiment-py-bootstrap + python <generated_file>
                                       (with an in-phase review beat between codegen and run)
Phase 6: Analyze experiment          → agent-observability-experiment-analyzer

Chaque phase possède un nom court canonique — la même valeur acceptée par --start-at et --stop-after. Utilisez ces noms chaque fois que vous devez faire référence à une seule phase sans ambiguïté (par exemple dans des scripts, dans une discussion avec des coéquipiers ou dans des tickets de support) :

Les phases 4 et 5 sont les deux seules qui exécutent du code sur votre machine ; les autres sont en lecture seule ou écrivent des fichiers générés dans --output-dir. Le comportement classique du pipeline d’évaluation en trois phases (classification → RCA → bootstrap des évaluateurs uniquement) est préservé en transmettant --stop-after eval-bootstrap. La phase 5 marque une pause entre la génération de code et l’exécution afin que vous puissiez examiner le fichier d’expérience généré avant que des jetons de fournisseur ne soient consommés — tapez run pour exécuter, edit pour mettre en pause et ajuster, ou stop pour quitter proprement.

Entrez et sortez à n’importe quelle phase. Le pipeline enregistre la sortie principale de chaque phase (résumé de classification, rapport RCA, suite d’évaluateurs, jeu de données, nom du jeu de données publié, fichier d’expérience, exécution d’expérience, rapport d’analyse) dans <output-dir>/state/0N-<name>.{md, json} avant que chaque point de contrôle ne soit rendu. Cela signifie :

• stop à n’importe quel point de contrôle (ou --stop-after <phase> depuis le début) termine l’exécution proprement, laissant un artefact qui permet de reprendre l’exécution ultérieurement.
• --start-at <phase> charge le fichier d’état de chaque phase précédente (ou accepte un indicateur de remplacement si vous en avez fourni un) et passe directement à la phase nommée. Vous pouvez reprendre des heures ou des jours plus tard, ou passer directement à « réanalyser simplement cette expérience » sans réexécuter quoi que ce soit auparavant.

Vocabulaire des points de contrôle à chaque phase : continue avance, stop quitte proprement, redo réexécute la phase actuelle (avec des notes d’ajustement facultatives ajoutées), back recule d’une phase. Toute autre entrée est traitée comme un ajustement.

Seul <ml_app> est requis. Chaque flag ci-dessous est facultatif — la compétence choisit des valeurs par défaut raisonnables pour chacun d’eux. L’invocation minimale est /agent-observability-eval-pipeline <ml_app> ; le reste du tableau sert lorsque vous souhaitez remplacer une valeur par défaut, reprendre en cours de route ou épingler un emplacement de sortie spécifique.

Exemples

# Full six-phase walkthrough for a brand new ml_app
/agent-observability-eval-pipeline my-chatbot --project-name my-chatbot

# Organize the dataset and experiment under a specific Datadog project
# (the project is created lazily — no need to pre-create it in the UI)
/agent-observability-eval-pipeline my-chatbot --project-name customer-qa-eval

# Classic three-phase eval-pipeline behavior — preserves backward compatibility
/agent-observability-eval-pipeline my-chatbot --stop-after eval-bootstrap

# Resume from where a previous run stopped
/agent-observability-eval-pipeline my-chatbot --start-at experiment

# Re-analyze a previous experiment run without re-running it
/agent-observability-eval-pipeline my-chatbot --start-at analyze --experiment-id <UUID>

# Run a single phase in isolation
/agent-observability-eval-pipeline my-chatbot --start-at dataset --stop-after dataset

Nom du projet — si --project-name est omis, la compétence le déduit automatiquement de votre base de code (dans l’ordre : pyproject.toml → setup.cfg → setup.py → package.json → nom de base du répertoire de travail), avec experiment-sdk-default comme solution de repli. Le nom résolu est affiché dans la sortie de la pré-vérification avant l’exécution de toute phase, afin que vous puissiez le confirmer ou le remplacer sans avoir à relancer. Le projet Datadog lui-même est créé de manière différée par LLMObs.enable(project_name=...) lorsque la Phase 4 publie le jeu de données — vous n’avez jamais besoin de le créer au préalable dans l’interface utilisateur.

Workflow typique

Si vous débutez dans l’évaluation d’une application LLM, le flux recommandé est le suivant :

1. Exécutez le pipeline pour passer des traces de production aux évaluateurs, à un jeu de données initial, à une expérience et à l’analyse :

   /agent-observability-eval-pipeline <ml_app> --project-name <project>
   

   Pour vous arrêter à la sortie classique de l’évaluateur uniquement (sans jeu de données ni expérience), passez --stop-after eval-bootstrap. Pour reprendre une exécution précédente, passez --start-at <phase> — le pipeline recharge l’état antérieur depuis <output-dir>/state/ et continue à partir de là.

2. Appliquez les correctifs. Le rapport RCA produit lors de la Phase 2 inclut des propositions de correctifs avant/après spécifiques fondées sur des preuves de traces. Transmettez le rapport à un agent de codage (ou agissez directement dessus) pour corriger les invites système, les définitions d’outils ou la logique de routage dans votre base de code.

3. Exécutez une expérience hors ligne en utilisant les évaluateurs générés sur un jeu de données étiqueté pour valider leur qualité avant de les activer en production. Consultez le Guide du développeur d’évaluation.

4. Publiez les évaluateurs en ligne une fois que les évaluateurs sont validés. L’exécution de /agent-observability-eval-bootstrap avec --publish crée des évaluateurs LLM-judge en ligne dans Datadog qui s’exécutent automatiquement sur vos traces de production en temps réel — aucune modification de code n’est requise :

   /agent-observability-eval-bootstrap <ml_app> --publish
   

5. Surveillez et itérez. À mesure que votre application évolue, réexécutez /agent-observability-trace-rca et /agent-observability-eval-bootstrap pour détecter les nouveaux modes de défaillance et maintenir votre suite d’évaluateurs à jour.

Documentation, liens et articles supplémentaires utiles:

Évaluations d'Agent ObservabilityDOCUMENTATION Expériences LLMDOCUMENTATION Guide du développeur pour l'évaluation : Créer des évaluateurs personnalisésGUIDE Améliorez la qualité de l'agent d'IA avec Bits EvalsBLOG datadog-labs/agent-skillsGITHUB