## Overview

Detectors answer **“why did my agent fail?”** by analyzing execution traces for failures, performing root cause analysis, and producing actionable fix recommendations. While evaluators tell you *whether* an agent performed well, detectors tell you *what went wrong and how to fix it*.

Detectors operate on `Session` objects (the same trace format used by trace-based evaluators) and use LLM-based analysis to identify semantic failures that go beyond simple error codes — hallucinations, tool misuse, reasoning breakdowns, policy violations, and more.

## Why Detectors?

Evaluators give you a score. Detectors give you a diagnosis.

**Evaluators alone:**

-   Tell you a case scored 0.3 / 1.0
-   Don’t explain which step failed or why
-   Require manual trace inspection to debug
-   Don’t suggest what to change

**Evaluators + Detectors:**

-   Score the case *and* identify the specific failing spans
-   Classify failures (hallucination, tool error, policy violation, etc.)
-   Trace causal chains between failures (primary vs. secondary)
-   Recommend concrete fixes (system prompt changes, tool description updates)

## When to Use Detectors

Use detectors when you need to:

-   **Debug failing evaluations**: Understand why specific test cases fail
-   **Identify failure patterns**: Detect recurring issues across sessions (hallucinations, tool misuse)
-   **Get fix recommendations**: Receive actionable suggestions for system prompt or tool description changes
-   **Automate root cause analysis**: Replace manual trace inspection with LLM-based diagnosis
-   **Monitor production agents**: Analyze traces from remote providers for systematic issues

## Available Detectors

### Failure Detection

**[`detect_failures`](/pr-cms-3708/docs/user-guide/evals-sdk/detectors/failure_detection/index.md)**

-   **Purpose**: Identify semantic failures in agent execution traces
-   **Output**: List of failures with span location, category, confidence, and evidence
-   **Categories**: ~20 failure types including hallucinations, execution errors, tool misuse, repetitive behavior, and orchestration errors

### Root Cause Analysis

**[`analyze_root_cause`](/pr-cms-3708/docs/user-guide/evals-sdk/detectors/root_cause_analysis/index.md)**

-   **Purpose**: Determine the fundamental cause of detected failures
-   **Output**: Causal analysis with propagation impact, fix type, and recommendation
-   **Strategy**: 3-tier fallback (direct, pruned, chunked) for handling large sessions

### Session Diagnosis

**[`diagnose_session`](/pr-cms-3708/docs/user-guide/evals-sdk/detectors/diagnosis/index.md)**

-   **Purpose**: Run failure detection and root cause analysis as a single pipeline
-   **Output**: Combined result with failures, root causes, and deduplicated recommendations
-   **Integration**: Can be wired into `Experiment` via `DiagnosisConfig` for automatic diagnosis of failing cases

## Quick Example

```python
from strands_evals.detectors import diagnose_session

# session is a Session object from a trace provider or in-memory mapper
result = diagnose_session(session)

# What failed?
for failure in result.failures:
    print(f"Span {failure.span_id}: {failure.category}")
    print(f"  Evidence: {failure.evidence}")

# Why did it fail?
for rc in result.root_causes:
    print(f"Root cause at {rc.location}: {rc.root_cause_explanation}")
    print(f"  Fix ({rc.fix_type}): {rc.fix_recommendation}")

# Deduplicated recommendations
for rec in result.recommendations:
    print(f"  - {rec}")
```

## Detectors vs Evaluators

| Aspect | Evaluators | Detectors |
| --- | --- | --- |
| **Question** | ”How well did the agent do?" | "Why did it fail?” |
| **Output** | Score + pass/fail | Failures + root causes + fix recommendations |
| **Granularity** | Per-case or per-session | Per-span |
| **Purpose** | Measure quality | Diagnose problems |
| **Use Case** | Benchmarking, regression testing | Debugging, improvement |

**Use Together:** Run evaluators to score your agent, then use detectors on failing cases to understand what went wrong and how to fix it. The `Experiment` class supports this workflow natively via `DiagnosisConfig`.

## Integration with Experiments

Detectors integrate directly into the evaluation pipeline. Pass a `DiagnosisConfig` to `Experiment` to automatically diagnose failing cases:

```python
import asyncio

from strands_evals import Experiment, Case, DiagnosisConfig
from strands_evals.evaluators import GoalSuccessRateEvaluator
from strands_evals.detectors import DiagnosisTrigger

experiment = Experiment(
    cases=test_cases,
    evaluators=[GoalSuccessRateEvaluator()],
    diagnosis_config=DiagnosisConfig(trigger=DiagnosisTrigger.ON_FAILURE),
)

async def main():
    report = await experiment.run_evaluations_async(my_task)

    # View recommendations for failing cases
    report.display(include_recommendations=True)

asyncio.run(main())
```

See the [Session Diagnosis guide](/pr-cms-3708/docs/user-guide/evals-sdk/detectors/diagnosis/index.md) for the full integration walkthrough.

## How It Works

Detectors use a two-phase analysis pipeline:

```mermaid
flowchart TD
    A[Session traces] --> B[1. Failure Detection]
    B --> C[2. Root Cause Analysis]
    C --> D[DiagnosisResult]

    B -. "span_id, category,\nconfidence, evidence" .-> B
    C -. "causality, propagation impact,\nfix recommendation" .-> C
    D -. "failures[]\nroot_causes[]\nrecommendations[]" .-> D
```

Both phases handle large sessions that exceed LLM context limits through automatic chunking with overlap and merge strategies.

## Next Steps

-   [Failure Detection](/pr-cms-3708/docs/user-guide/evals-sdk/detectors/failure_detection/index.md): Identify what went wrong in agent traces
-   [Root Cause Analysis](/pr-cms-3708/docs/user-guide/evals-sdk/detectors/root_cause_analysis/index.md): Understand why failures happened
-   [Session Diagnosis](/pr-cms-3708/docs/user-guide/evals-sdk/detectors/diagnosis/index.md): Run the full pipeline and integrate with experiments

## Related Documentation

-   [Getting Started](/pr-cms-3708/docs/user-guide/evals-sdk/quickstart/index.md): Set up your first evaluation experiment
-   [Evaluators Overview](/pr-cms-3708/docs/user-guide/evals-sdk/evaluators/index.md): Score agent performance
-   [Remote Trace Providers](/pr-cms-3708/docs/user-guide/evals-sdk/how-to/trace_providers/index.md): Fetch traces from production backends

## Related pages

- [Failure Detection](/pr-cms-3708/docs/user-guide/evals-sdk/detectors/failure_detection/index.md) (2 shared tags)
- [Root Cause Analysis](/pr-cms-3708/docs/user-guide/evals-sdk/detectors/root_cause_analysis/index.md) (2 shared tags)
- [Session Diagnosis](/pr-cms-3708/docs/user-guide/evals-sdk/detectors/diagnosis/index.md) (2 shared tags)
- [Retry Strategies](/pr-cms-3708/docs/user-guide/concepts/agents/retry-strategies/index.md) (1 shared tag)
- [Chaos Testing](/pr-cms-3708/docs/user-guide/evals-sdk/chaos_testing/index.md) (1 shared tag)
- [Operating Agents in Production](/pr-cms-3708/docs/user-guide/deploy/operating-agents-in-production/index.md) (1 shared tag)
- [Failure Communication Evaluator](/pr-cms-3708/docs/user-guide/evals-sdk/evaluators/failure_communication_evaluator/index.md) (1 shared tag)
- [Partial Completion Evaluator](/pr-cms-3708/docs/user-guide/evals-sdk/evaluators/partial_completion_evaluator/index.md) (1 shared tag)
- [Recovery Strategy Evaluator](/pr-cms-3708/docs/user-guide/evals-sdk/evaluators/recovery_strategy_evaluator/index.md) (1 shared tag)
- [Interrupts](/pr-cms-3708/docs/user-guide/concepts/interrupts/index.md) (1 shared tag)