> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Analyzers

> 后置 badcase 检测、统计、延迟检查和 qualitative trajectory diagnosis。

Analyzers 在任务产生 `RunResult` 之后运行。它们检查 trajectory、metrics、errors、latency、model output 和 tool calls，并把诊断结果写入 `analysis_result.<AnalyzerId>`。

当 benchmark score 告诉你“失败了”，但没有告诉你“为什么失败”时，就需要 analyzers。

## Analyzers 负责什么

<CardGroup cols={2}>
  <Card title="Badcase detection" icon="badge-alert">
    标记 exception、truncation、JSON error、repetition、empty output、latency spike 和 terminal misuse。
  </Card>

  <Card title="Statistics" icon="chart-no-axes-combined">
    统计 step counts、tool-call counts、duration、token length、value counts 和 numeric summaries。
  </Card>

  <Card title="Qualitative diagnosis" icon="sparkles">
    使用 LLM-backed analyzer 标注 trajectory phase、总结行为并渲染报告。
  </Card>

  <Card title="Aggregation" icon="table">
    聚合 analyzer output 到 `analysis_summary.json` 和 `analysis_summary.md`。
  </Card>
</CardGroup>

Analyzer 不重新运行 agent，也不重新定义 benchmark correctness。它读取已经完成的 task result。

## 核心接口

| Field or method                               | 含义                                            |
| --------------------------------------------- | --------------------------------------------- |
| `id`                                          | 稳定 analyzer id，用于 config 和 `analysis_result`。 |
| `category`                                    | summary grouping 使用的 analyzer category。       |
| `datasets`                                    | 可选 benchmark allowlist；为空表示适用于所有 benchmark。   |
| `data_requirements`                           | 可选 JSONPath requirements，必须存在才运行。             |
| `distribution_fields`                         | 需要聚合为 value counts 或 numeric stats 的 fields。  |
| `analysis(task, prepared, result, req, plan)` | per-task analyzer implementation。             |

## 随 Evaluation 运行

```bash theme={null}
agentcompass run \
  terminal_bench_2 \
  terminus2 \
  your-model \
  --env <env-provider> \
  --benchmark-params '{"sample_ids":["overfull-hbox"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --enable-analysis \
  --analysis-params '{"analyzers":["ExceptionAnalyzer","TruncationAnalyzer"]}'
```

当你明确知道一次 run 要附带哪些 analyzer 时，使用这种方式。

## 对已有结果重新分析

```bash theme={null}
agentcompass analysis \
  --input results/terminal_bench_2/your-model/20260703_120000 \
  --analysis-params '{
    "analyzers": ["ExceptionAnalyzer", "QualitativeAnalyzer"],
    "QualitativeAnalyzer": {"render_mode": "file"}
  }' \
  --task_concurrency 8
```

默认情况下，`analysis` 会把输入 run 复制到新的 timestamp sibling。使用 `--output` 指定复制目标，或在明确要原地修改时使用 `--override`。

## 选择规则

| 字段                  | 含义                                                         |
| ------------------- | ---------------------------------------------------------- |
| `analyzers`         | 白名单；设置后只考虑这些 analyzer id。                                  |
| `exclude_analyzers` | 黑名单；即使兼容也会跳过。                                              |
| `<AnalyzerId>`      | 单个 analyzer 的配置，例如 threshold 或 qualitative model settings。 |
| `only_incorrect`    | 基础逻辑支持的 analyzer config，用于跳过 correct samples。              |

## 支持的 Analyzer 家族

当前 `agentcompass list analyzer` 输出包含 25 个 analyzer：

| 家族                | 示例                                                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Basic statistics  | `BasicMetricAnalyzer`, `TrajectoryTimeCostAnalyzer`, `CompletionLengthAnalyzer`                                                |
| Error detection   | `ExceptionAnalyzer`, `TerminalBench2ExceptionAnalyzer`, `TruncationAnalyzer`, `JSONErrorAnalyzer`, `EmptyContentAnalyzer`      |
| Efficiency        | `LLMInferLatencyAnalyzer`, `ToolExecutionLatencyAnalyzer`                                                                      |
| Behavior patterns | `ContentRepetitionAnalyzer`, `ReasoningRepetitionAnalyzer`, `NetworkOperationAnalyzer`, `TerminalBench2CommandRunningAnalyzer` |
| Qualitative       | `QualitativeAnalyzer`, `MultiQualitativeAnalyzer`                                                                              |

## 输出形状

per-task details 中 analyzer output 位于：

```text theme={null}
analysis_result.<AnalyzerId>
```

聚合 summary 会按 category 展示：

* analyzed task total；
* badcase count 和 badcase ratio；
* analyzer 提供时的 average score；
* value-count distributions；
* numeric min、max、mean 和 p95 stats。

## 开发者说明

当诊断可以从已完成 task details 中计算，并且应该跨 benchmark 或 run 复用时，新增 analyzer。如果逻辑会改变 correctness，应放在 benchmark evaluation；如果需要重新执行 agent，就不属于 analyzer。

## 相关页面

* [Results](/zh/key_modules/results)
* [Analyzer reference](/zh/reference/analyzers)
* [CLI 参考](/zh/reference/cli)