experiment-analyzer

統合実験アナライザー

1 件または 2 件の LLM 実験を分析します。入力に応じて、次の 4 つのモードに対応します。

入力	モード
ID 2 件、質問なし	比較探索
ID 2 件＋質問	比較 Q&A
ID 1 件、質問なし	単一探索
ID 1 件＋質問	単一 Q&A

使用方法

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

引数：$ARGUMENTS

利用可能なツール

ツール	目的
mcp__datadog-llmo-mcp__get_llmobs_experiment_summary	イベント総数、エラー数、メトリクス統計、利用可能なディメンションを取得します
mcp__datadog-llmo-mcp__list_llmobs_experiment_events	フィルター、並べ替え、ページネーションを指定してイベントをクエリします
mcp__datadog-llmo-mcp__get_llmobs_experiment_event	イベントの詳細（input、output、expected_output、metrics）を取得します
mcp__datadog-llmo-mcp__get_llmobs_experiment_metric_values	全体およびディメンション別のメトリクス統計を取得します
mcp__datadog-llmo-mcp__get_llmobs_experiment_dimension_values	件数付きで、ディメンションの一意な値を一覧表示します
mcp__datadog-mcp-core__create_datadog_notebook	レポートを Datadog ノートブックとしてエクスポートします

---

フェーズ 0 — モードと出力先の決定

$ARGUMENTS を解析します。

1. UUID 形式の文字列を 1 つまたは 2 つ抽出し、実験 ID とします（1 つ目＝ベースライン／プライマリ、2 つ目＝候補）。
2. --output agent|file|notebook フラグがあれば抽出します。
3. ID とフラグを除いた残りのテキストを、質問があればその質問とします。

モードの決定：

• ID 2 件＋質問 → 比較 Q&A
• ID 2 件、質問なし → 比較探索
• ID 1 件＋質問 → 単一 Q&A
• ID 1 件、質問なし → 単一探索

出力モードの決定：

引数に --output が指定されている場合は、そのモードを使用し、確認を省略します。

指定されていない場合は、続行する前に確認事項をまとめたメッセージを 1 件だけ送ります。本当に不明な点に限って確認してください。

• モードが曖昧な場合（例：周辺のコンテキストで質問しているように見えるものの、ID しか指定されていない場合）は、平易な言葉で「具体的な質問がありますか？それとも探索的な分析を希望しますか？」と尋ねます。
• 出力先が指定されていない場合は、必ず「ファイルに保存するか、Datadog ノートブックにエクスポートするか、このチャットに表示するか、どれをご希望ですか？」と尋ねます。

確認を複数回に分けて尋ねてはいけません。未解決の事項は 1 件のメッセージですべて確認します。

出力モード：

1. エージェント（デフォルト）： レポート全体を会話に表示します。
2. ファイル： 開始前に、次のパスを提案します。 evals/reports/YYYY-MM-DD-<experiment-slug>-analysis.md ユーザーに提示して、確認または変更してもらってから続行します。
3. ノートブック： 最後に mcp__datadog-mcp-core__create_datadog_notebook を使用します。 ツールを利用できない場合は、失敗として終了せず、代わりに次のセットアップ手順を出力します。

   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/
   

   その後、「代わりにファイル出力またはエージェント出力に切り替えますか？」と尋ねます。 ノートブックの呼び出しの詳細は、フェーズ 5 を参照してください。

モードと出力先が決まったら、それ以降はユーザーとのやり取りを挟まず、フェーズ 1～5 を最後まで自動的に進めます。

---

フェーズ 1 — 全体像の把握

比較： 両方の実験について get_llmobs_experiment_summary を呼び出します。次の項目を左右に並べて比較します。

• 規模：各実験のイベント総数とエラー率
• メトリクス：それぞれに存在するメトリクスと、共通するメトリクス
• ディメンション：それぞれに存在するディメンションと、共通するディメンション
• すぐに把握できる懸念点（高いエラー率、メトリクスの欠落、データの少なさ）
• サマリーレベルで見える明らかな改善点または悪化点

単一： 実験について get_llmobs_experiment_summary を呼び出します。次の項目を確認します。

• イベント総数、エラー数、エラー率
• 利用可能なメトリクス（完全一致型とルーブリック／品質型に分類）
• セグメント分析に利用できるディメンション
• すぐに把握できる懸念点

---

フェーズ 2 — シグナルの発見と UI リンク

比較: 共通のメトリクスとディメンションのみを使用して、以下を特定します。

• 候補がベースラインを上回るセグメント
• 候補のパフォーマンスが低下するセグメント
• 一方では見られるものの、もう一方ではまれなエラータイプ
• 分布の変化またはカバレッジの不足
• トレードオフ（例：再現率が高く、適合率が低い）

Datadog の比較 UI リンクを生成します。

• ベース URL：https://app.datadoghq.com/llm/experiment-comparison
• 必須パラメーター：baselineExperimentId、experimentIds（candidate%2Cbaseline）、tableView=all
• 任意（特定できる場合に含める）：project、compareDatasetId、selectedEvaluation
• selectedEvaluation の優先順位：overall/overall_score/rubric メトリクス → 主要メトリクス → 最初の共通メトリクス
• リンクを 2～4 件生成します：主要な比較、リグレッションビュー、キャリブレーションビュー（該当する場合）、最悪のセグメントのビュー（サポートされている場合のみ。フィルターを決して捏造しないでください）

単一: すべてのディメンションにわたるメトリクスごとのパフォーマンスを測定します。以下を特定します。

• パフォーマンスが最も低いセグメント（メトリクス × ディメンション別）
• 合格率が予想外のセグメント
• 全体の合格率と分散

Datadog の実験 UI リンクを生成します。

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

---

フェーズ 3 — 詳細分析

必要な詳細分析をすべて自動的に実行します。承認を求めたり、作業を中断したりしないでください。

Q&A モード: 質問に直接答えるために必要な内容に、詳細分析を絞ります。特定のイベントを取得し、関連するディメンションでセグメント化して、例を調べます。

探索モード: 特に興味深いシグナルを幅広く調査します。

• セグメント別およびクラス別の差分分析（比較）、または合格率分析（単一）
• エラーの重複と固有の失敗モードの分析
• 代表的な失敗例のサンプリングと定性的な調査（問題ごとに 2～5 件）
• エラーのテーマのクラスタリング分析

ルール：

• まず、低コストでシグナルの強い分析を優先し、早期に打ち切らないでください。
• すべての出力で PII をマスキングまたは編集してください。
• 破壊的な操作は避けてください。

サンプリングした各イベントについて、直接アクセスできるスパンリンクを生成します。 https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&sp=[{"p":{"experimentId":"{experiment_id}","spanId":"{span_id}"},"i":"experiment-details"}]&spanId={span_id}

詳細分析の各セグメントについて、（候補の）実験で該当イベントを表示するための直接リンクを生成します。 https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&filter[{dimension}]={value} このディメンションでフィルター URL 形式が機能するか確信が持てない場合は、フィルターパラメーターを省略し、代わりに実験のルートにリンクしてください。フィルター URL を決して捏造しないでください。

---

フェーズ 4 — 統合

比較探索モード：

• 候補がベースラインを改善する明確な利点
• 候補がもたらす明確なリグレッションやリスク
• 中立的または変化のない領域
• 根本原因の仮説（1～4 件、根拠と関連付ける）
• 優先順位を付けた推奨事項：そのままリリース／ブロック／セグメントごとに制限／動作を組み合わせる

比較 Q&A モード：

• 明確な判定を添えた、質問への直接的な回答
• 裏付けとなるエビデンス（メトリクス、割合、イベントの例）
• 関連する背景情報（例：注意点、データの制限）

単一探索モード：

• 全体的なパフォーマンス評価
• パフォーマンスが最も低いセグメントと根本原因
• 失敗が起きる理由の仮説
• 次に推奨する実験

単一 Q&A モード：

• 明確な判定を添えた、質問への直接的な回答
• 実験データに基づく裏付けとなるエビデンス

すべてのモードで、可能な限り定量的な差分や率を使用します。PII を編集してください。

---

フェーズ 5 — 出力の提供

エージェント： 以下のレポート形式を使用して、会話内に完全なレポートを提示します。

ファイル： 事前に確認したパスにレポートを書き込みます。次のように確認します：「レポートを <path> に保存しました。」

ノートブック： 次のパラメーターを指定して mcp__datadog-mcp-core__create_datadog_notebook を呼び出します。

• name（モード別）：

  モード	名前
  比較探索	Experiment Analysis: {baseline_short} (Baseline) vs {candidate_short} (Candidate) — YYYY-MM-DD
  比較Q&A	Experiment Q&A: {baseline_short} vs {candidate_short} — YYYY-MM-DD
  単一探索	Experiment Analysis: {experiment_short} — YYYY-MM-DD
  単一Q&A	Experiment Q&A: {experiment_short} — YYYY-MM-DD
  ここで short は UUID の先頭 8 文字です。

• cells：レポート全体を単一の Markdown セルとして指定します — [{ "type": "markdown", "text": "<full report markdown>" }]。セルの内容から # Experiment Analysis Report のトップレベル見出しを省略してください。これはすでにノートブックのタイトルとして表示されています。

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

ノートブックの作成後、チャットに URL を出力します：「ノートブックにレポートをエクスポートしました：」

ツールを使用できない場合は、フェーズ 0 のフォールバック手順に従います。

---

フェーズ 6 — 会話でのフォローアップ

レポートを提供した後、フォローアップセクションを追加します。

---
## 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]

Do you have any other questions about this analysis?

レポートの提供後も対応を継続します。すでに収集した調査結果を参照し、同じ MCP ツールを使用してフォローアップの質問に回答します。新しい質問で必要とされない限り、実施済みの分析を再実行しないでください。

---

レポート形式

リンクのルール：

• 実験 ID：完全な実験 UUID が現れる箇所では、https://app.datadoghq.com/llm/experiments/{full_uuid} への Markdown リンクとして表示します。
• 比較表の列見出し：オリエンテーション表、および Baseline／Candidate 列を含む後続のすべての表では、列見出し全体をリンクにします。短い ID のみをリンクにしないでください。形式：[Baseline \{short_id}`]({baseline_url})およびCandidate `{short_id}``。これにより、列見出し全体がクリック可能になります。

# Experiment Analysis Report

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

## Summary & Recommendations

[Comparative: **Baseline**: [`{baseline_short}`]({baseline_url}) | **Candidate**: [`{candidate_short}`]({candidate_url}) | **Compare**: [`{baseline_short}-{candidate_short}`](https://app.datadoghq.com/llm/experiment-comparison?baselineExperimentId={baseline_id}&experimentIds={candidate_id}%2C{baseline_id}&tableView=all&selectedEvaluation=pass) — Single: **Experiment**: [`{experiment_short}`]({experiment_url}). Always the first line of this section.]

[2–3 sentence executive summary directly below the links line. 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 key finding with specific numbers.]

[If the report uses opaque dimension values (e.g. category labels like b1/b2/b3/bx), add a `### Dataset Categories` subsection here. Include: one sentence explaining where the categories come from (i.e. labels from the evaluation dataset grouping questions by required tools/data sources), then a bullet per value with its name bolded and a brief description. Infer descriptions from input question patterns, capability tags, and expected tool calls. Omit this subsection if all dimension values are self-explanatory.]

[Wins, regressions, neutral areas, prioritized actions. For Q&A: verdict + rationale.]

## Orientation

[Side-by-side table for comparative; summary table for single. Include: events, error rate, 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 events | **Severity**: metric pass rate = X% | [View events](https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&filter[{dimension}]={value})

**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]

## UI Links

[All generated Datadog UI links with labels]

---

運用ルール

• 実験について（モデル、タスク、メトリクス、スキーマ、ディメンションなど）何も決めつけないでください。データを調べてすべて推定してください。
• すべての結論を、イベント ID、件数、割合などの具体的な証拠に基づけてください。
• 定性的な主張だけでなく、件数と割合を含め、計算過程を示してください。
• 観測された証拠に裏付けられていない推測は避けてください。
• ユーザーに表示するすべての出力で個人を特定できる情報（PII）をマスキングまたは削除してください。
• 内部のツール呼び出し、スキーマ、実装の詳細をユーザーに決して表示しないでください。
• MCP 結果の解析に関する安全性： MCP ツールの結果のフィールドを反復処理または参照するスクリプト（Python、jq など）を書く前に、まず生の構造を確認してください。type(result)、トップレベルのキー、ペイロードがコンテンツブロック内にネストされているかどうか（例：[{'type': 'text', 'text': '<json>'}]）を確認します。必要に応じて内部ペイロードを取り出し、json.loads() で解析してから処理してください。MCP の結果がそのまま dict または list であると決めつけないでください。