agentcompass analysis

执行后置错误案例检测、统计、延迟检查和定性轨迹诊断。

agentcompass analysis 对已有 AgentCompass 结果目录重新运行分析器，而不重新执行 agent：

agentcompass analysis --input <run-directory> [OPTIONS]

分析器会检查轨迹、指标、错误、延迟、model 输出和工具调用，并把结果写入 analysis_result.<analyzer-family>；字段结构见任务结果。

当 Benchmark 得分只能说明“什么失败了”而不能解释“为什么失败”时，请使用分析器。

​

分析器的作用

Badcase 检测

标记异常、截断、JSON 错误、重复、空输出、延迟异常和终端误用。

统计

计算步骤数、工具调用数、耗时、词元长度、值分布和数值摘要。

定性诊断

使用由 LLM 驱动分析器标注轨迹阶段、总结行为并生成报告。

聚合

将分析器输出聚合为 analysis_summary.json 和 analysis_summary.md。

分析器不会重新运行 agent，也不会重新判定 Benchmark 正确性；它们只读取已经完成的任务结果。

​

随评测运行

agentcompass run \
  terminal_bench_2 \
  terminus2 \
  "$MODEL_NAME" \
  --env <env-provider> \
  --benchmark-params '{"sample_ids":["<task-id>"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --enable-analysis \
  --analysis-params '{"analyzers":["ExceptionAnalyzer","TruncationAnalyzer"]}'

如果已确定评测期间应运行哪些分析器，请使用此方式。

​

重新分析已有结果

agentcompass analysis \
  --input results/terminal_bench_2/$MODEL_NAME/20260703_120000 \
  --analysis-params '{
    "analyzers": ["ExceptionAnalyzer", "QualitativeAnalyzer"],
    "QualitativeAnalyzer": {"render_mode": "file"}
  }' \
  --task_concurrency 8

默认情况下，analysis 会把输入运行复制到带有新时间戳的同级目录。使用 --output 指定复制目标；只有明确需要原地修改时才使用 --override。

​

参数

参数	作用
INPUT / --input	包含 run_info.json 和 details/ 的已有运行目录，必填。
--override	替换输入目录中的分析器字段和摘要，默认关闭。
--output <path>	将运行复制到该路径并分析副本；仅在未启用 --override 时使用。
--task_concurrency <n>	重新分析时的任务并发数；默认沿用原始运行值。
--analysis-params <json>	选择分析器并提供分析器专属配置。
--benchmark-params <json>	通过 sample_ids 限制重新分析范围；此命令不使用其他 Benchmark 字段。
--config <path>	加载额外配置覆盖，可重复传入。
--log-level <level>	设置分析操作的终端日志级别。
--progress auto|plain|none	选择分析进度渲染器。

默认复制可以避免意外修改已测量运行。只有确实希望替换已有分析数据，且没有不可变归档依赖该目录时，才使用 --override。

​

选择规则

字段	含义
analyzers	白名单；设置后只考虑列出的分析器 ID。
exclude_analyzers	黑名单；即使其他条件兼容，被排除的分析器也会跳过。
<AnalyzerId>	每个分析器的配置，例如阈值或定性 model 设置。
only_incorrect	基础逻辑支持时，只分析错误样本的分析器配置。

​

支持的分析器系列

使用 agentcompass list analyzer 查看当前版本注册的分析器。常见系列包括：

系列	示例
基础统计	BasicMetricAnalyzer、TrajectoryTimeCostAnalyzer、CompletionLengthAnalyzer
错误检测	ExceptionAnalyzer、TerminalBench2ExceptionAnalyzer、TruncationAnalyzer、JSONErrorAnalyzer、EmptyContentAnalyzer
效率	LLMInferLatencyAnalyzer、ToolExecutionLatencyAnalyzer
行为模式	ContentRepetitionAnalyzer、ReasoningRepetitionAnalyzer、NetworkOperationAnalyzer、TerminalBench2CommandRunningAnalyzer
定性分析	QualitativeAnalyzer、MultiQualitativeAnalyzer

​

输出结构

每个任务详情将分析器输出保存在：

analysis_result.<analyzer-family>

键可以是分析器自身的 ID，也可以是多个实现共用的分析器系列 ID。聚合摘要按类别和分析器系列输出：

• 分析的任务总数；
• 错误案例数量和比例；
• 分析器提供得分时的平均值；
• 值数量分布；
• 数值的数量、最小值、平均值、p50、p90、p95 和最大值。

逐任务字段见任务结果，两个分析摘要文件的完整结构见汇总与分析结果。

​

相关页面

• 汇总与分析结果
• agentcompass summary
• agentcompass list
• CLI 概览
• 配置