agentcompass analysis

Post-execution failure detection, statistics, latency checks, and qualitative trajectory diagnosis.

agentcompass analysis re-runs analyzers on an existing AgentCompass result directory without re-running the agent:

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

Analyzers inspect trajectories, metrics, errors, latency, model output, and tool calls, then attach output under analysis_result.<analyzer-family>. See Task Results for the field structure.

Use analyzers when a benchmark score tells you what failed but not why it failed.

What Analyzers Do

Failure detection

Flag exceptions, truncation, JSON errors, repetition, empty outputs, latency spikes, and terminal misuse.

Statistics

Compute step counts, tool-call counts, durations, token lengths, value counts, and numeric summaries.

Qualitative diagnosis

Use LLM-backed analyzers to annotate trajectory phases, summarize behavior, and render reports.

Aggregation

Aggregate analyzer output into analysis_summary.json and analysis_summary.md.

Analyzers do not rerun agents or rescore benchmark correctness. They read completed task results.

Run With Evaluation

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"]}'

Use this path when you know which analyzers should run as part of the evaluation.

Re-run on Existing Results

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

By default, analysis copies the input run into a new timestamped sibling. Use --output to choose the copy destination or --override when you intentionally want in-place mutation.

Options

Option	Purpose
INPUT / --input	Existing run directory containing run_info.json and details/. Required.
--override	Replace analyzer fields and summaries in the input directory. Disabled by default.
--output <path>	Copy the run to this path and analyze the copy. Used only when --override is disabled.
--task_concurrency <n>	Concurrent tasks during re-analysis; defaults to the original run’s value.
--analysis-params <json>	Select analyzers and supply analyzer-specific configuration.
--benchmark-params <json>	Limit re-analysis through sample_ids; other benchmark fields are not used by this command.
--config <path>	Load an additional configuration override; repeatable.
--log-level <level>	Set console verbosity for the analysis operation.
--progress auto|plain|none	Select the analysis progress renderer.

The default copy protects the measured run from accidental mutation. Use --override only when replacing its existing analysis data is intentional and no immutable archive depends on that directory.

Selection Rules

Field	Meaning
analyzers	Whitelist. If set, only these analyzer IDs are considered.
exclude_analyzers	Blacklist. Excluded analyzers are skipped even if otherwise compatible.
<AnalyzerId>	Per-analyzer config, such as thresholds or qualitative model settings.
only_incorrect	Analyzer config option that skips correct samples when supported by base logic.

Supported Families

Use agentcompass list analyzer to inspect the analyzers registered by the installed revision. Common families include:

Family	Examples
Basic statistics	BasicMetricAnalyzer, TrajectoryTimeCostAnalyzer, CompletionLengthAnalyzer
Error detection	ExceptionAnalyzer, TerminalBench2ExceptionAnalyzer, TruncationAnalyzer, JSONErrorAnalyzer, EmptyContentAnalyzer
Efficiency	LLMInferLatencyAnalyzer, ToolExecutionLatencyAnalyzer
Behavior patterns	ContentRepetitionAnalyzer, ReasoningRepetitionAnalyzer, NetworkOperationAnalyzer, TerminalBench2CommandRunningAnalyzer
Qualitative	QualitativeAnalyzer, MultiQualitativeAnalyzer

Output Shape

Per-task details keep analyzer output under:

analysis_result.<analyzer-family>

The key may be an analyzer’s own ID or a family ID shared by several implementations. Aggregated summaries group output by category and analyzer family and render:

• total analyzed tasks;
• number and proportion of detected failures;
• average score when provided;
• value-count distributions;
• numeric count, min, mean, p50, p90, p95, and max statistics.

See Task Results for per-task fields and Summary and Analysis Results for the complete structure of both aggregate files.

Related Pages

• Summary and Analysis Results
• agentcompass summary
• agentcompass list
• CLI Overview
• Configuration