agent-observability-experiment-analyzer

后端

检测 — 每次调用开始时，在采取任何操作之前，确定要使用哪个后端：

1. 如果用户在调用参数中的任意位置传入了 --backend pup → 立即使用 pup 模式，无论是否存在 MCP 工具。跳过步骤 2–4。
2. 检查当前可用工具列表中是否存在 MCP 工具。判断依据是可用工具中是否出现名为 get_llmobs_experiment_summary（带或不带 mcp__datadog-llmo-mcp__ 前缀）的工具。
3. 如果存在 MCP 工具 → 全程使用 MCP 模式。**工具名称绑定：**记下 get_llmobs_experiment_summary 在当前可用工具列表中显示的确切名称，并在本次调用的每次 MCP 工具调用中使用该确切名称（带前缀或不带前缀）。所有其他实验工具也遵循相同的命名规则。
4. 如果不存在 MCP 工具 → 检查 pup 是否可执行：通过 Bash 运行 pup --version。包含 "version" 的 JSON 响应表示 pup 可用。
5. 如果 pup 有响应 → 全程使用 pup 模式。使用本文底部的工具参考附录，将每次 MCP 工具调用转换为对应的 pup 调用。
6. 如果两者都不可用 → 停止并告知用户：

   “Datadog MCP 服务和 pup CLI 均不可用。请连接 MCP 服务（claude mcp add --scope user --transport http datadog-llmo-mcp 'https://mcp.datadoghq.com/v1/mcp?toolsets=llmobs'）或安装 pup。”

--backend pup 可出现在调用参数中的任意位置，并会在将其余参数传递给技能逻辑之前被移除。

pup 调用规则：

• 通过 Bash 调用：pup llm-obs <subcommand> [flags]
• pup 始终输出 JSON。直接解析即可——无需拆包内容块（与 MCP 结果不同，MCP 结果可能会将 JSON 包装在 [{"type": "text", "text": "<json>"}] 中）。
• 如果 pup 返回身份验证错误，告知用户运行 pup auth login，然后停止。
• 并行执行：在一条消息中发起多个 Bash 工具调用（每次调用执行一条 pup 命令）。

**调用 ID：**每次调用开始时，在进行任何 MCP 工具调用之前，生成一个 8 位十六进制调用 ID（例如 3a9f1c2b）。在整个调用过程中保持不变。

**意图标记：**每次 MCP 工具调用时，在 telemetry.intent 前加上 skill:agent-observability-experiment-analyzer[<inv_id>] — ，后接说明调用该工具的原因。仅在第一次 MCP 工具调用时使用 skill:agent-observability-experiment-analyzer:start[<inv_id>] — （注意 :start 后缀）。首次调用示例：skill:agent-observability-experiment-analyzer:start[3a9f1c2b] — Phase 1: get experiment summary to orient analysis

统一实验分析器

分析一个或两个 LLM 实验。根据输入支持四种模式：

输入	模式
2 个 ID，无问题	对比探索
2 个 ID + 问题	对比问答
1 个 ID，无问题	单个探索
1 个 ID + 问题	单个问答

用法

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

参数：$ARGUMENTS

可用工具

**注意：**下方显示的工具名称带有示例前缀 mcp__<server>__。实际前缀取决于环境和 MCP 服务名称，可能不同，也可能完全不存在。始终使用当前活动工具列表中显示的准确名称调用工具（请参阅后端检测步骤 3）。

工具	用途
mcp__datadog-llmo-mcp__get_llmobs_experiment_summary	获取事件总数、错误数、指标统计数据和可用维度
mcp__datadog-llmo-mcp__list_llmobs_experiment_events	使用筛选条件、排序和分页查询事件
mcp__datadog-llmo-mcp__get_llmobs_experiment_event	获取完整事件详情（输入、输出、预期输出、指标）
mcp__datadog-llmo-mcp__get_llmobs_experiment_metric_values	获取整体指标统计数据，以及按维度细分的统计数据。使用 segment_by_dimension（而非 segment_dimension）进行细分；也可使用 segment_dimension_value 筛选特定值。
mcp__datadog-llmo-mcp__get_llmobs_experiment_dimension_values	列出某个维度的唯一值及其计数
mcp__datadog-mcp-core__create_datadog_notebook	将报告导出为 Datadog notebook

---

阶段 0 — 模式和输出解析

解析 $ARGUMENTS：

1. 提取一个或两个 UUID 格式的字符串作为实验 ID（第一个 = 基线/主要实验，第二个 = 候选实验）。
2. 如果存在，提取 --output agent|file|notebook 标志。
3. 剩余文本（ID 和标志之后的内容）即为问题（如果有）。

模式判定：

• 2 个 ID + 问题 → 对比问答
• 2 个 ID，无问题 → 对比探索
• 1 个 ID + 问题 → 单项问答
• 1 个 ID，无问题 → 单项探索

输出模式判定：

如果参数中提供了 --output，则使用该模式并跳过询问。

否则，继续操作前依次进行两次单独的连续 AskUserQuestion 调用——绝不能合并为一次调用：

1. 分析类型：如果参数中没有提供问题文本，询问用户是想进行探索性分析，还是有具体问题。只有当用户的意图已能从上下文明确判断时，才跳过此调用（例如，用户在 ID 旁边输入了问题）。
2. 输出位置：如果没有指定 --output，询问报告的交付位置（聊天、文件或 Datadog notebook）。始终将此项作为单独的调用提出。

输出模式：

1. **Agent（默认）：**在对话中显示完整报告。
2. **文件：**开始前，提出一个路径： evals/reports/YYYY-MM-DD-<experiment-slug>-analysis.md 将路径呈现给用户，让用户确认或调整，然后继续。
3. **Notebook：**最后使用 mcp__datadog-mcp-core__create_datadog_notebook。在 pup 模式下，改用 pup notebooks create --title "TITLE" --file /tmp/nb_cells.json（参见工具参考）。如果 MCP 和 pup 均不可用，则输出以下设置说明，而不是直接失败：

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

   然后询问：“您是否希望改用文件或 Agent 输出？” 完整的 notebook 调用详情请参阅阶段 5。

确定模式和输出后，继续阶段 1。深入分析开始前，阶段 1.5 还会进行一次额外的 AskUserQuestion 交互。

---

阶段 1 — 初步了解

对比： 对两个实验都调用 get_llmobs_experiment_summary。生成并列对比：

• 规模：各自的样本总数和错误数
• 指标：各自有哪些指标；有哪些指标是共有的
• 维度：各自有哪些维度；有哪些维度是共有的
• 明显的风险信号（存在错误、缺少指标、数据稀疏）
• 从摘要层面可以看出的明显改进或退化

当 error_count > 0 时，调用 get_llmobs_experiment_dimension_values 查询 error_type，并报告按异常类划分的明细（例如“2 个错误：asyncio.exceptions.cancellederror”）。错误表示执行器抛出了未处理的异常——这些样本不会产生评估分数。不要报告百分比；报告数量和类型。

单个实验： 对该实验调用 get_llmobs_experiment_summary。确定：

• 样本总数和错误数（若不为零，则提供 error_type 明细）
• 按摘要返回的 metric_type 对可用指标分组（score、boolean、categorical）。不要根据标签名称模式或前缀推断语义分组或类别——标签字符串并不是判断指标衡量内容的可靠依据。
• 使用摘要已返回的统计数据（均值、最小值、最大值）对每项指标进行分类。不要根据标签名称或前缀推断指标含义。在报告中引用指标时，使用阶段 1.5 中定义的分类。
• 可用于细分的维度
• 任何明显的风险信号

阶段 1.5 — 指标选择

完成阶段 1 后，在提出任何 AskUserQuestion 之前，先执行以下三个步骤。

步骤 1 — 对每个指标进行分类，仅使用汇总统计数据（不进行额外的工具调用）：

类别	条件	含义
always_zero	max == 0	功能已禁用或尚未实现——无信号
perfect	min == 1	始终通过——无诊断信号
saturated	mean ≥ 0.99 且 min < 1	极少失败——诊断价值低
struggling	mean < 0.70	失败率显著——诊断价值最高
interesting	0.70 ≤ mean < 0.99 且 min < max	部分失败——诊断价值中等

**步骤 2 — 在提问前，将完整指标表打印到聊天中。**这样用户就能完整查看所有指标——不会受选项数量限制而被截断。格式如下：

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?) |

对于任何 always_zero 指标，添加说明——例如：“有 N 个指标的得分始终为 0，似乎是已禁用的功能；这些指标不会纳入建议的分组。”

步骤 3 — 使用完全基于计算所得类别的选项调用 AskUserQuestion：

根据数据中实际存在的指标动态生成选项。不要根据标签前缀编造选项名称。

• “表现不佳的指标（N 个）— 推荐”：仅当 N ≥ 1 时显示。描述中明确列出每个指标标签及其平均值（例如，open_answer 0.33、c_permanence 0.68）。这是基于实际观测通过率、而非标签名称的合理建议。如果没有表现不佳的指标，则将此选项替换为 “表现最低的指标（N 个）”，包含平均值最低的 N 个指标。
• “有意思 + 表现不佳（N 个）”：仅当除了表现不佳的指标之外，还存在 interesting 类别的指标时显示。描述中列出这些指标及其平均值。
• “所有指标（N 个）”：始终显示。请在描述中注明，始终为 0 和始终完美的指标会增加噪声，但仍包含在内。
• “指定指标”：始终显示。描述写明：“从上方打印的表格中选择一项。”

如果用户选择“指定指标”，则再次调用 AskUserQuestion，将平均值最低的 4 个指标作为带标签的选项显示（标签 = 指标名称，描述 = mean: X.XX — 类别）。在问题文本中明确写明：“或者在‘其他’中输入上方表格里的任意指标名称。” always_zero 和 perfect 指标不得出现在这 4 个选项中（它们没有诊断价值）；仅从 struggling 和 interesting 类别中选择这 4 个指标。用户选择后，阶段 2–4 的所有分析都仅限于该单个指标。

范围限制：

• 如果用户接受“所有指标”，则继续使用所有指标（包括常量指标，但需注明其信号价值较低）。
• 如果用户选择某个分组或指定指标，则阶段 2–4 的所有分析都必须严格限定在该选择范围内。不要对范围之外的任何指标调用 get_llmobs_experiment_metric_values。

---

阶段 2 — 信号发现 + UI 链接

**比较模式：**仅使用阶段 1.5 中选定的指标（与共享指标取交集）和共享维度，识别：

• 候选实验表现优于基线的细分群体
• 候选实验表现退步的细分群体
• 仅在一方出现、在另一方很少出现的错误类型
• 分布变化或覆盖缺口
• 权衡（例如，召回率更高、精确率更低）

生成 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 个链接：主要比较、退步视图、校准视图（如适用）、最差细分群体视图（仅在受支持时 — 绝不伪造筛选条件）

**单实验模式：**仅针对阶段 1.5 中选定的指标，衡量其在所有维度上的表现。识别：

• 表现最差的细分群体（按指标 × 维度）
• 通过率异常的细分群体
• 总体通过率和方差

生成 Datadog 实验 UI 链接：

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

---

阶段 3 — 深入分析

自动执行所有必要的深入分析。不要请求批准或暂停。严格将所有深入分析限定在阶段 1.5 中选定的指标范围内 — 不要为所选范围之外的任何指标调用 get_llmobs_experiment_metric_values。

**问答模式：**围绕直接回答问题所需的信息开展深入分析。提取具体样本，按相关维度细分，并检查示例。

**探索模式：**广泛调查最有趣的信号：

• 按细分群体和类别进行变化量分析（比较模式），或通过率分析（单实验模式）
• 错误重叠与独有失败模式分析
• 对有代表性的失败进行抽样和定性检查（每个问题抽取 2–5 个）
• 聚类分析错误主题

规则：

• 优先进行成本低、信号强的分析；不要过早停止。
• 在所有输出中屏蔽或删去 PII。
• 避免破坏性操作。

为每个抽样事件生成直接 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} 渲染前必须对 sp 查询参数值进行百分号编码（例如，[ → %5B，{ → %7B，" → %22，} → %7D，] → %5D）。

为每个深入分析的细分群体生成一个直接链接，以便在（候选）实验中查看这些样本： https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&filter[{dimension}]={value} 如果不确定此筛选 URL 格式是否适用于该维度，则省略筛选参数，改为链接到实验根页面。绝不伪造筛选 URL。

---

阶段 4 — 综合分析

对比探索：

• 候选方案优于基线方案的明确优势
• 候选方案引入的明确退化或风险
• 中性或未发生变化的方面
• 根因假设（1–4 条），并与证据对应
• 优先级建议：按原样发布 / 阻止发布 / 按细分群体设置门槛 / 结合不同方案的行为

对比问答：

• 直接回答问题，并给出明确结论
• 支持性证据（指标、百分比、事件示例）
• 相关背景（例如注意事项、数据局限）

单项探索：

• 整体表现评估
• 表现最差的细分群体及其根因
• 失败原因假设
• 建议开展的后续实验

单项问答：

• 直接回答问题，并给出明确结论
• 来自实验数据的支持性证据

所有模式：先用一行统计问题类型，例如“3 个 Agent 问题、1 个评估器／数据集问题、1 个不明确问题”，然后再详细列出发现。尽可能使用量化的差值／比率。对个人身份信息（PII）进行脱敏。

**无论实验有多复杂、存在多少指标，或答案显而易见的速度有多快，都必须始终输出 ## Summary & Recommendations 和 ## Synthesis 两个部分。**不要因为发现简单或明显而跳过 Summary。不要因为已在 Deep Dives 中涵盖发现而跳过 Synthesis。这两个部分是分析中最便于复用的输出——读者首先看到它们，最后也会看到它们。

---

阶段 5 — 交付输出

**Agent：**使用下方的报告格式，在对话中完整呈现报告。

**文件：**将报告写入预先确认的路径。确认时使用：“报告已保存至 <path>。”

**Notebook：**使用以下参数调用 mcp__datadog-mcp-core__create_datadog_notebook：

• name（按模式）：

  模式	名称
  对比探索	Experiment Analysis: {baseline_short} (Baseline) vs {candidate_short} (Candidate) — YYYY-MM-DD
  对比问答	Experiment Q&A: {baseline_short} vs {candidate_short} — YYYY-MM-DD
  单项探索	Experiment Analysis: {experiment_short} — YYYY-MM-DD
  单项问答	Experiment Q&A: {experiment_short} — YYYY-MM-DD
  其中 short = UUID 的前 8 个字符。

• cells：每个报告部分对应一个单元格——不得将整份报告放入单个单元格。结构如下：

  • 单元格 1 — Summary & Recommendations，包含三个 ### 子标题：Experiment（链接 + 执行摘要）、Key Findings（项目符号）、Recommendations（编号列表）——始终存在，始终位于首位，无论实验有多复杂都不得跳过
  • 单元格 2 — 概览表
  • 单元格 3 — 变更内容（仅适用于对比模式；单项模式省略）
  • 单元格 4 — 信号／问题答案
  • 单元格 5…N — 每条深入分析发现各对应一个单元格
  • 单元格 N+1 — Synthesis（问题统计、整体表现评估、表现最差的细分群体、根因假设、建议的后续实验）——始终存在，始终位于倒数第二
  • 单元格 N+2 — UI 链接

  从所有单元格中省略顶级标题 # Experiment Analysis Report——它已显示为 notebook 标题。

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

创建 notebook 后，在聊天中输出 URL：“报告已导出到 notebook：”

如果工具不可用，请遵循阶段 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]
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?

报告交付后保持活跃。使用相同的 MCP 工具回答后续问题，并参考已收集的发现。除非新问题需要，否则不要重新运行已执行过的分析。

---

报告格式

链接规则：

• 实验 ID：凡是出现完整实验 UUID，都将其渲染为指向 https://app.datadoghq.com/llm/experiments/{full_uuid} 的 Markdown 链接。
• 对比表列标题：在 Orientation 表以及之后所有包含 Baseline/Candidate 列的表格中，将整个列标题设为链接，而不只是短 ID。格式：[Baseline \{short_id}`]({baseline_url})和Candidate `{short_id}``。这样整个表头单元格都可以点击，而不仅仅是 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]

---

操作规则

• 不要对实验做任何假设（模型、任务、指标、架构、维度）。通过检查数据推断所有内容。
• 所有结论都要以具体证据为依据：事件 ID、计数、百分比。
• 展示计算过程：包含计数和比率，而不只是定性结论。
• 避免做出缺乏观察证据支持的推测性解释。
• 在所有面向用户的输出中屏蔽或隐去个人身份信息（PII）。

---

工具参考

本附录仅适用于 pup 模式。在 MCP 模式下，直接使用工作流章节中的工具名称。

实验

MCP 工具	pup 命令
get_llmobs_experiment_summary(experiment_id)	pup llm-obs experiments summary EXPERIMENT_ID
list_llmobs_experiment_events(experiment_id, ...)	pup llm-obs experiments events list EXPERIMENT_ID [--filter-metric-label L] [--sort-by-metric M] [--sort-direction asc|desc] [--limit N] — 使用前，通过 pup llm-obs experiments events list --help 确认筛选和排序标志的名称
get_llmobs_experiment_event(experiment_id, event_id)	pup llm-obs experiments events get EXPERIMENT_ID EVENT_ID
get_llmobs_experiment_metric_values(experiment_id, metric_label, ...)	pup llm-obs experiments metric-values EXPERIMENT_ID --metric-label L [--segment-by-dimension D] [--segment-dimension-value V]
get_llmobs_experiment_dimension_values(experiment_id, dimension_key)	pup llm-obs experiments dimension-values EXPERIMENT_ID --dimension-key K

Notebooks

MCP 工具	pup 命令
create_datadog_notebook(name, cells, ...)	pup notebooks create --title "TITLE" --file /tmp/nb_cells.json — 通过 pup notebooks create --help 确认准确的标志

cells 文件是一个由单元格对象组成的 JSON 数组：

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

• 不要向用户展示内部工具调用、架构或实现细节。