Backend

Détection — Au début de chaque invocation, avant d'effectuer une action, détermine quel backend utiliser :

1. Si l'utilisateur a passé --backend pup n'importe où dans son invocation → utilise le mode pup immédiatement, indépendamment de la présence d'outils MCP. Saute les étapes 2–4.
2. Vérifie si des outils MCP sont présents dans ta liste d'outils active. Le signal canonique est la présence d'un outil nommé get_llmobs_experiment_summary (avec ou sans le préfixe mcp__datadog-llmo-mcp__) dans tes outils disponibles.
3. Si des outils MCP sont présents → utilise le mode MCP partout. Binding de noms d'outils : note le nom exact sous lequel get_llmobs_experiment_summary apparaît dans ta liste d'outils active et utilise ce nom exact (préfixé ou non) pour chaque appel d'outil MCP durant cette invocation. Tous les autres outils d'experiment suivent la même convention de nommage.
4. Si les outils MCP sont absents → vérifie si pup est exécutable : exécute pup --version via Bash. Une réponse JSON contenant "version" confirme que pup est disponible.
5. Si pup répond → utilise le mode pup partout. Traduis chaque appel d'outil MCP en son équivalent pup en utilisant la référence des outils en fin de ce fichier.
6. Si aucun n'est disponible → arrête-toi et dis à l'utilisateur :

   « Neither the Datadog MCP server nor the pup CLI is available. Connect the MCP server (claude mcp add --scope user --transport http datadog-llmo-mcp 'https://mcp.datadoghq.com/api/unstable/mcp-server/mcp?toolsets=llmobs') or install pup. »

--backend pup est accepté n'importe où dans les arguments d'invocation et est supprimé avant de passer les arguments restants à la logique de la skill.

Règles d'invocation pup :

• Invoque via Bash : pup llm-obs <subcommand> [flags]
• pup produit toujours du JSON. Parse directement — sans unwrapping de bloc de contenu (contrairement aux résultats MCP, qui peuvent envelopper le JSON dans [{"type": "text", "text": "<json>"}]).
• Si pup retourne une erreur d'authentification, dis à l'utilisateur d'exécuter pup auth login et arrête-toi.
• Parallélisation : émets plusieurs appels Bash tool dans un seul message (une commande pup par appel).

ID d'invocation : Tout au début de chaque invocation, avant tout appel d'outil MCP, génère un ID d'invocation hexadécimal de 8 caractères (par ex. 3a9f1c2b). Garde-le constant pour l'ensemble de l'invocation.

Tagging d'intention : Sur chaque appel d'outil MCP, préfixe telemetry.intent avec skill:agent-observability-experiment-analyzer[<inv_id>] — suivi d'une description de la raison pour laquelle l'outil est appelé. Sur l'appel d'outil MCP en premier, utilise skill:agent-observability-experiment-analyzer:start[<inv_id>] — à la place (note le suffixe :start). Exemple d'appel en premier : skill:agent-observability-experiment-analyzer:start[3a9f1c2b] — Phase 1: get experiment summary to orient analysis

Unified Experiment Analyzer

Analyse une ou deux expériences LLM. Supporte quatre modes selon les entrées :

Usage

/agent-observability-experiment-analyzer <experiment_id_1> [experiment_id_2] [question text] [--output agent|file|notebook]

Arguments : $ARGUMENTS

Available Tools

Note : Les noms d'outils ci-dessous sont affichés avec un exemple de préfixe mcp__<server>__. Le préfixe réel dépend de l'environnement et du nom du serveur MCP — il peut différer ou être absent entièrement. Appelle toujours les outils en utilisant le nom exact visible dans ta liste d'outils active (voir l'étape 3 de Backend Detection).

Phase 0 — Mode & Output Resolution

Parse $ARGUMENTS :

1. Extrait une ou deux chaînes au format UUID comme IDs d'experiment (première = baseline/primary, deuxième = candidate).
2. Extrait le flag --output agent|file|notebook s'il est présent.
3. Le texte restant (après les IDs et les flags) est la question, si présente.

Mode determination :

• 2 IDs + question → Comparative Q&A
• 2 IDs, pas de question → Comparative Exploratory
• 1 ID + question → Single Q&A
• 1 ID, pas de question → Single Exploratory

Output mode determination :

Si --output était présent dans les arguments, utilise ce mode et saute la question.

Sinon, pose deux appels séquentiels séparés AskUserQuestion avant de continuer — jamais combinés en un seul appel :

1. Type d'analyse : Si aucun texte de question n'a été fourni dans les arguments, demande si l'utilisateur souhaite une analyse exploratoire ou a une question spécifique. Saute cet appel uniquement si l'intention de l'utilisateur est déjà claire d'après le contexte (par ex. il a tapé une question aux côtés des IDs).
2. Destination de sortie : Si --output n'a pas été spécifié, demande où livrer le rapport (chat, fichier ou notebook Datadog). Pose toujours cette question comme un appel autonome.

Output modes :

1. Agent (par défaut) : Affiche le rapport complet dans la conversation.
2. File : Avant de commencer, propose un chemin : evals/reports/YYYY-MM-DD-<experiment-slug>-analysis.md Présente-le à l'utilisateur et laisse-le confirmer ou ajuster. Puis procède.
3. Notebook : Utilise mcp__datadog-mcp-core__create_datadog_notebook à la fin. En mode pup, utilise pup notebooks create --title "TITLE" --file /tmp/nb_cells.json à la place (voir Tool Reference). Si ni MCP ni pup n'est disponible, produis ces instructions de configuration au lieu d'échouer :

   To enable Datadog notebook export, add the MCP server:
     claude mcp add --transport http datadog-mcp https://mcp.datadoghq.com/api/unstable/mcp-server
   See: https://docs.datadoghq.com/bits_ai/mcp_server/setup/

   Puis demande : « Would you like to fall back to file or agent output instead? » Voir Phase 5 pour les détails complets du notebook call.

Après résolution du mode et de la sortie, procède à la Phase 1. Il y aura une interaction AskUserQuestion supplémentaire à la Phase 1.5 avant que l'analyse approfondie ne commence.

Phase 1 — Orient

Comparative : Appelle get_llmobs_experiment_summary pour les deux experiments. Produis une comparaison côte à côte :

• Échelle : total d'échantillons et nombre d'erreurs pour chacun
• Métriques : quelles métriques existent dans chacun ; lesquelles sont partagées
• Dimensions : quelles dimensions existent dans chacun ; lesquelles sont partagées
• Drapeaux rouges immédiats (erreurs présentes, métriques manquantes, données éparses)
• Améliorations ou régressions évidentes visibles au niveau du résumé

Quand error_count > 0, appelle get_llmobs_experiment_dimension_values pour error_type et signale la ventilation par classe d'exception (par ex. « 2 errors: asyncio.exceptions.cancellederror »). Les erreurs signifient que l'exécuteur a levé une exception non gérée — aucun score d'eval n'a été produit pour ces échantillons. Ne signale pas de pourcentage ; signale le comptage et le(s) type(s).

Single : Appelle get_llmobs_experiment_summary pour l'experiment. Détermine :

• Total d'échantillons et nombre d'erreurs (avec ventilation error_type si non-zéro)
• Métriques disponibles groupées par metric_type comme retourné par le résumé (score, boolean, categorical). N'infère pas les groupements sémantiques ou les catégories à partir des motifs ou préfixes des noms de label — la chaîne de label n'est pas un signal fiable de ce qu'une métrique mesure.
• Classe chaque métrique en utilisant les statistiques déjà retournées par le résumé (mean, min, max). N'infère pas le sens de la métrique à partir des noms ou préfixes de label. Utilise les classifications définies en Phase 1.5 lors du référençage des métriques dans le rapport.
• Dimensions disponibles pour la segmentation
• Tout drapeau rouge immédiat

Phase 1.5 — Metrics Selection

Après avoir terminé la Phase 1, exécute les trois étapes suivantes avant tout AskUserQuestion.

Step 1 — Classe chaque métrique en utilisant seulement les statistiques du résumé (aucun appel d'outil supplémentaire) :

Step 2 — Affiche la table complète des métriques dans le chat avant de poser une question. Cela donne à l'utilisateur une visibilité complète — jamais tronquée par les limites d'options. Format :

Found N metrics. Full breakdown:

| Metric | Mean | Class |
|--------|------|-------|
| <label> | <mean> | ⚠️ Struggling |
| <label> | <mean> | Interesting |
| <label> | <mean> | Saturated |
| <label> | 1.000 | Perfect (no signal) |
| <label> | 0.000 | Always zero (disabled?) |

Signale toute métrique always_zero avec une note — par ex. « N metrics always score 0 and appear to be disabled features; they will be excluded from suggested groupings. »

Step 3 — AskUserQuestion avec options construites entièrement à partir des classes calculées :

Génère les options dynamiquement basé sur ce qui est réellement présent dans les données. N'invente PAS de noms d'options à partir des préfixes de label.

• « Struggling metrics (N) — Recommended » : affiché seulement si N ≥ 1. Description énumère explicitement chaque label de métrique et sa mean (par ex. « open_answer 0.33, c_permanence 0.68 »). C'est la suggestion fondée — basée sur les taux de réussite observés, pas les noms de label. S'il n'y a pas de métriques struggling, remplace cette option par « Lowest-performing metrics (N) » couvrant les N inférieures par mean.
• « Interesting + struggling (N) » : affiché seulement s'il y a des métriques de classe interesting en addition aux struggling. Description les énumère avec les means.
• « All metrics (N) » : toujours affiché. Note dans la description que les métriques always-zero et perfect ajoutent du bruit mais sont incluses.
• « A specific metric » : toujours affiché. Description dit : « Choose one from the table printed above. »

Si l'utilisateur sélectionne « A specific metric », pose une deuxième AskUserQuestion qui affiche les 4 métriques avec la plus faible mean comme options étiquetées (label = nom de métrique, description = mean: X.XX — class). Dans le texte de la question, dis explicitement : « Or type any metric name from the table above into 'Other'. » Les métriques always_zero et perfect ne doivent pas apparaître dans les 4 options (elles n'ont pas de valeur diagnostique) ; restreins les 4 aux classes struggling et interesting uniquement. Après que l'utilisateur sélectionne une, restreins toute analyse en Phases 2–4 à cette seule métrique uniquement.

Scope enforcement :

• Si l'utilisateur accepte « all », procède avec toutes les métriques (y compris les métriques constantes, mais note leur faible valeur de signal).
• Si l'utilisateur sélectionne un groupement ou une métrique spécifique, restreins toute analyse en Phases 2–4 strictement à cette sélection. N'appelle pas get_llmobs_experiment_metric_values pour aucune métrique en dehors de la sélection.

Phase 2 — Signal Discovery + UI Links

Comparative : En utilisant seulement les métriques sélectionnées en Phase 1.5 (intersectées avec les métriques partagées) et les dimensions partagées, identifie :

• Les segments où la candidate surpasse la baseline
• Les segments où la candidate régresse
• Les types d'erreurs présents dans l'une mais rares dans l'autre
• Les décalages de distribution ou les lacunes de couverture
• Les compromis (par ex., rappel plus élevé, précision plus faible)

Génère les liens de l'UI de comparaison Datadog :

• URL de base : https://app.datadoghq.com/llm/experiment-comparison
• Paramètres requis : baselineExperimentId, experimentIds (candidate%2Cbaseline), tableView=all
• Optionnel (inclus si découvrable) : project, compareDatasetId, selectedEvaluation
• Priorité selectedEvaluation : overall/overall_score/rubric metric → métrique primaire → première métrique partagée
• Génère 2–4 liens : comparaison primaire, vue de régression, vue d'étalonnage (si applicable), vue de pire segment (seulement si supporté — jamais inventer de filtres)

Single : Mesure la performance par métrique à travers toutes les dimensions pour seulement les métriques sélectionnées en Phase 1.5. Identifie :

• Pires segments de performance (par métrique × dimension)
• Tout segment avec taux de réussite surprenant
• Taux de réussite globaux et variance

Génère le lien de l'UI d'experiment Datadog :

• https://app.datadoghq.com/llm/experiments/{experiment_id}

Phase 3 — Deep Dives

Exécute tous les deep dives nécessaires automatiquement. Ne demande pas d'approbation ni de pause. Scopes tous les deep dives strictement aux métriques sélectionnées en Phase 1.5 — n'appelle pas get_llmobs_experiment_metric_values pour aucune métrique en dehors de la sélection.

Q&A modes : Focalise les deep dives sur ce qui est nécessaire pour répondre directement à la question. Tire des échantillons spécifiques, segmente par les dimensions pertinentes, inspecte les exemples.

Exploratory modes : Enquête sur les signaux les plus intéressants largement :

• Analyse delta par segment et par classe (comparative) ou analyse de taux de réussite (single)
• Analyse du chevauchement d'erreurs vs. analyse du mode d'échec unique
• Échantillonnage et inspection qualitative de représentants d'échecs (2–5 par problème)
• Analyse de thème d'erreur en cluster

Règles :

• Préfère les analyses bon marché et à haut signal en premier ; n'arrête pas tôt.
• Masque ou redacte les PII dans tous les résultats.
• Évite les actions destructrices.

Pour chaque événement échantillonné, génère un lien direct de span : https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&sp=[{"p":{"experimentId":"{experiment_id}","spanId":"{span_id}"},"i":"experiment-details"}]&spanId={span_id} La valeur du paramètre de requête sp doit être encodée en pourcentage avant d'être rendue (par ex. [ → %5B, { → %7B, " → %22, } → %7D, ] → %5D).

Pour chaque segment de Deep Dive, génère un lien direct pour voir ces échantillons dans l'experiment (candidate) : https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&filter[{dimension}]={value} Si tu n'es pas sûr que le format URL du filtre fonctionne pour cette dimension, omets les paramètres de filtre et lie à la racine de l'experiment à la place. N'invente jamais des URLs de filtre.

Phase 4 — Synthesis

Comparative Exploratory :

• Les gains clairs où la candidate améliore la baseline
• Les régressions claires ou les risques que la candidate introduit
• Les zones neutres ou inchangées
• Les hypothèses de cause racine (1–4), liées à la preuve
• Les recommandations priorisées : ship as-is / block / gate by segment / combine behaviors

Comparative Q&A :

• Réponse directe à la question avec un verdict clair
• Preuve supportant (métriques, pourcentages, exemples d'événements)
• Contexte pertinent (par ex., mises en garde, limites des données)

Single Exploratory :

• Évaluation de la performance globale
• Pires segments de performance et causes racines
• Hypothèses de pourquoi les échecs surviennent
• Recommandations pour les expériences suivantes

Single Q&A :

• Réponse directe à la question avec un verdict clair
• Preuve supportant à partir des données d'experiment

Tous les modes : ouvre avec un comptage de type d'problème d'une seule ligne — par ex. « 3 agent issues, 1 evaluator/dataset issue, 1 ambiguous » — avant les résultats détaillés. Utilise les deltas quantifiés/taux partout où possible. Redacte les PII.

Produis toujours les deux sections ## Summary & Recommendations et ## Synthesis indépendamment de la complexité de l'experiment, de combien de métriques existent, ou de la vitesse avec laquelle la réponse est apparente. Ne saute pas Summary parce que les résultats sont simples ou évidentes. Ne saute pas Synthesis parce que tu as déjà couverts les résultats dans Deep Dives. Ces deux sections sont la production la plus portable de l'analyse — elles sont ce qu'un lecteur rencontre en premier et en dernier.

Phase 5 — Output Delivery

Agent : Présente le rapport complet dans la conversation en utilisant le format de rapport ci-dessous.

File : Écris le rapport dans le chemin pré-confirmé. Confirme avec : « Report saved to <path>. »

Notebook : Appelle mcp__datadog-mcp-core__create_datadog_notebook avec les paramètres suivants :

• name (par mode) : | Mode | Name | |------|------| | Comparative Exploratory | Experiment Analysis: {baseline_short} (Baseline) vs {candidate_short} (Candidate) — YYYY-MM-DD | | Comparative Q&A | Experiment Q&A: {baseline_short} vs {candidate_short} — YYYY-MM-DD | | Single Exploratory | Experiment Analysis: {experiment_short} — YYYY-MM-DD | | Single Q&A | Experiment Q&A: {experiment_short} — YYYY-MM-DD | où short = premiers 8 caractères de l'UUID.

• cells : une cellule par section de rapport — NE MET PAS le rapport entier dans une seule cellule. Structure :

  • Cell 1 — Summary & Recommendations contenant trois sous-entêtes ### : Experiment (lien + résumé exécutif), Key Findings (puces), Recommendations (liste numérotée) — toujours présente, toujours en premier, jamais sautée indépendamment de la complexité de l'experiment
  • Cell 2 — Table d'orientation
  • Cell 3 — What Changed (modes comparatifs seulement ; omis pour single)
  • Cell 4 — Signals / Answer to Question
  • Cells 5…N — une cellule par Deep Dive Finding
  • Cell N+1 — Synthesis (comptage d'issue, Overall Performance Assessment, Worst-Performing Segments, Root Cause Hypothesis, Recommended Next Experiments) — toujours présente, toujours penultième
  • Cell N+2 — UI Links

  Omets l'entête # Experiment Analysis Report de haut niveau de toutes les cellules — il est déjà affiché comme titre du notebook.

• time : { "live_span": "1h" }

Après la création du notebook, produis l'URL dans le chat : "Report exported to notebook: <url>"

Si l'outil n'est pas disponible, suis les instructions de fallback en Phase 0.

Phase 6 — Conversational Follow-up

Après avoir livré le rapport, ajoute une section de suivi :

---
## Want to explore further?

Here are a few directions based on the findings:

1. [Specific question derived from actual findings — e.g., "Want me to dig deeper into why the SQL scenarios regressed in the candidate?"]
2. [Another specific follow-up — e.g., "Should I compare error patterns between the two failing clusters?"]
3. [A third option if relevant]
4. [If failures or regressions were found: "To investigate production failures driving these results, run `/agent-observability-trace-rca` on the same ml_app."]

Do you have any other questions about this analysis?

Reste actif après le rapport. Réponds aux questions de suivi en utilisant les mêmes outils MCP, en référençant les résultats déjà rassemblés. Ne ré-exécute pas les analyses que tu as déjà effectuées sauf si de nouvelles questions le requièrent.

Report Format

Règles de lien :

• Experiment IDs : Partout où un UUID complet d'experiment apparaît, rends-le comme lien Markdown vers https://app.datadoghq.com/llm/experiments/{full_uuid}.
• En-têtes de colonne de table comparative : Dans la table d'orientation et dans chaque table subséquente qui a des colonnes Baseline/Candidate, enveloppe l'entier en-tête de colonne comme lien — pas seulement l'ID court. Format : [Baseline \{short_id}`]({baseline_url})etCandidate `{short_id}``. Cela rend la cellule d'en-tête entière cliquable, pas juste la portion ID.

# Experiment Analysis Report

> **Question:** {original question text}
> _(Q&A modes only — omit for Exploratory modes)_

## Summary & Recommendations

### Experiment

[Comparative: [`{baseline_short}`]({baseline_url}) (Baseline) vs [`{candidate_short}`]({candidate_url}) (Candidate) — [Compare]({compare_url}) — Single: [`{experiment_short}`]({experiment_url})]

[2–3 sentence executive summary. Open with "This is a **{Mode}** analysis..." where {Mode} is one of: Comparative Exploratory, Comparative Q&A, Single Exploratory, Single Q&A. Include experiment(s) purpose, scale, and the headline finding with specific numbers.]

[If the report uses opaque dimension values (e.g. category labels like b1/b2/b3/bx), add a `#### Dataset Categories` sub-subsection here — one bullet per value with name bolded and a brief description. Omit if all dimension values are self-explanatory.]

### Key Findings

- **{Finding 1}**: one-line description with numbers (e.g. "+4.2pp on `tool_accuracy` across all segments")
- **{Finding 2}**: one-line description
- **{Finding 3}** (if present): one-line description
[For Q&A modes: one-line verdict bullet + one-line rationale bullet]

### Recommendations

1. **{Recommendation 1}**: specific, actionable next step tied to a finding
2. **{Recommendation 2}**: specific, actionable next step
3. **{Recommendation 3}** (if present): specific, actionable next step
[Omit this subsection for Q&A modes unless a clear action follows from the answer.]

## Orientation

[Side-by-side table for comparative; summary table for single. Include: samples, errors (count + `error_type` breakdown if non-zero, otherwise "none"), metrics, dimensions. Experiment IDs in column headers must be Markdown links.]


## What Changed

[Comparative modes only. Table of differences between baseline and candidate: model, toolset/skill profile,
dataset, evaluator schema, and any other metadata differences detectable from the summary data.
If no differences are detectable, write: "No configuration differences detected between experiments."]

## [Signals | Answer to Question]

[For exploratory: ranked table of signals/segments with metric deltas and impact counts.]
[For Q&A: direct answer with verdict, then supporting evidence.]

## Deep Dive Findings

### [Issue/Finding Title]

**Segment**: `[dimension=value]` | **Impact**: N samples | **Severity**: metric pass rate = X% | [View samples](https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&filter[{dimension}]={value})

**Issue type**: `Agent` — the evaluator is sound; the agent output is the problem. | `Evaluator/Dataset` — the agent output may be correct; the rubric, ground truth labels, or scoring logic is suspect. | `Ambiguous` — cannot determine from available evidence whether the agent or evaluator is at fault; flag for manual inspection.

**What's happening**: [1–2 sentences: key observation and metric impact only]

**Representative examples**:
- [Span link]: [input → output → expected, what went wrong]

**Root cause hypothesis**: [Category]: [Explanation tied to evidence]

**Recommendation**: [Specific, actionable next step]

---
[Repeat for each major issue]

## Synthesis

[Required in all modes. Comes after all Deep Dive Findings, before UI Links.]

**Issue tally**: [N agent issues, N evaluator/dataset issues, N ambiguous]

### Overall Performance Assessment
[2–4 sentences on overall quality: what the experiment shows, whether the app/model is production-ready on this task, key numbers.]

### Worst-Performing Segments
[Bullet list: which dimension values or conditions most reliably predict failure. Include metric values.]

### Root Cause Hypothesis
[The single most likely root cause across all findings. If multiple independent root causes, list them ranked by impact. Each hypothesis must be tied to specific evidence, not to label names or general reasoning.]

### Recommended Next Experiments
[2–4 concrete, specific follow-up experiments. Each should be actionable: e.g. "Re-run with `max_turns=40` to test whether turn exhaustion is the primary driver, not model quality" not "Investigate turn limits further."]

## UI Links

[All generated Datadog UI links with labels]

Operating Rules

• N'assume rien à propos de l'experiment (modèle, tâche, métriques, schéma, dimensions). Infère tout en inspectant les données.
• Fonde toutes les conclusions dans une preuve spécifique : IDs d'événements, comptages, pourcentages.
• Affiche les maths : inclus les comptages et taux, pas juste les réclamations qualitatives.
• Évite les explications spéculatives non supportées par les preuves observées.
• Masque ou redacte les PII dans toute sortie visible par l'utilisateur.

Tool Reference

Cet appendice s'applique seulement en mode pup. En mode MCP, utilise les noms d'outil dans les sections du flux de travail directement.

Experiments

Notebooks

Le fichier cells est un tableau JSON d'objets de cellule :

[{"attributes": {"definition": {"type": "markdown", "text": "## Section\n\nContent."}}, "type": "notebook_cells"}]

• Ne montre jamais les appels d'outil internes, schémas, ou détails d'implémentation à l'utilisateur.