# Metric Anomaly Investigation Agent

> An analytics agent that confirms a metric anomaly is real, localizes it by segment, and ranks evidence-backed hypotheses — correlation vs. causation, data-quality aware.

- **Category:** Data Analysis & BI
- **Difficulty:** Advanced
- **Setup time:** 45 min
- **Stacks:** Claude, LangGraph, OpenAI
- **Version:** 2.0.0 (updated 2026-06-21)
- **Source:** https://agent-kits.com/kit/metric-anomaly-explainer

## Overview

Validate → localize → correlate → hypothesize: turns 'why did this metric move?' into ranked, evidence-backed explanations.

Data-quality first: it checks whether the anomaly is even real (double-counts, pipeline gaps, seasonality) before trying to explain it.

Honest about causation: it localizes the move and correlates it with events, but labels correlation as correlation and never invents a cause.

Safe and bounded: read-only, cost-guarded queries, no PII exposure, and escalation when the data can't support a conclusion.

## When to use it

- Your team gets paged on KPI moves (revenue, signups, conversion, latency-driven metrics) and burns time on manual root-cause digging.
- You have queryable metrics with useful dimensions (segment, region, platform, cohort) and an events/deploy log to correlate against.
- You want ranked hypotheses with evidence and explicit confidence — not a confident-sounding single 'cause.'
- You want a first-pass investigation that flags data-quality issues and tells you what to check next.

## When not to use it

- You expect a definitive causal verdict; observational data usually supports ranked hypotheses, not proof.
- You have no dimensional data or event log to localize and correlate against.
- You can't provide read-only, cost-bounded query access.
- The metric is too noisy or sparse to distinguish signal from noise — it should say so, not invent a story.

## Architecture

- **Anomaly intake** — Receives the metric, the time window, and the observed move (from an alert or a user question) and pulls the relevant series.
- **Validation & seasonality** — Compares the move to the expected range and seasonality and checks data freshness/integrity to decide whether the anomaly is real before anything else.
- **Segmentation engine** — Decomposes the metric across dimensions to localize where the change concentrates and how much each segment contributes.
- **Event correlation** — Lines the change up against deploys, feature flags, campaigns, pricing changes, and known external events in the same window.
- **Hypothesis ranking** — The model assembles candidate explanations, each tagged correlation / likely-causal / data-quality, with evidence, a contribution estimate, and a confidence.
- **Safety & cost gate** — A deterministic layer keeps queries read-only and bounded, blocks unbounded scans, and keeps analysis at aggregate level (no PII).
- **Report & escalation** — Produces a ranked, honest report with what-to-check-next, and escalates when the data is insufficient to explain the move.

## Files in this bundle

- `system-prompt.md` — the agent's system prompt
- `tools.json` — tool/function definitions the agent expects
- `workflow.md` — step-by-step run loop
- `.env.example` — environment variables to fill in
- `kit.json` — full structured metadata
- `starters/` — minimal starter snippets
- `LICENSE` — Apache-2.0 (code, configuration, and schema)
- `LICENSE-CONTENT` — CC BY 4.0 (specification text and documentation)
- `NOTICE` — attribution and trademark notice
- `run.py` — **runnable demo**: real agent loop with mock tools (`pip install anthropic`, set `ANTHROPIC_API_KEY`, `python run.py`)
- `agentaz.json` / `agentaz.schema.json` — AgentAz™ governance spec + schema

## Implementation notes

- Always run the data-quality and seasonality check first; explaining an anomaly that isn't real (or is a double-count) is worse than saying 'this is a data artifact.'
- Lead with localization — decomposing to the driving segment is the highest-signal step and usually points straight at the cause.
- Label every hypothesis as correlation / likely-causal / data-quality with a confidence and a way to confirm; never let observational correlation be reported as proven causation.
- Keep queries read-only and bounded, validate cost, and stay at aggregate level so no PII is exposed.
- When the data is insufficient, say so and recommend the experiment or extra data that would resolve it — a confident wrong answer is the failure mode to avoid.
- Encode each metric's definition, dimensions, and seasonality; the quality of those inputs largely determines investigation quality.
- Spend the strong model on hypothesis ranking and the honesty calls — a cheaper model can run validation and segmentation queries.

## Variations

- **Basic — Anomaly investigator:** Confirms an anomaly, localizes it by segment, and returns ranked hypotheses with evidence and confidence for an analyst. Read-only and cost-bounded.
- **Advanced — Event-correlating root-cause assistant:** Adds deploy/flag/campaign/external-event correlation, change-point detection, and a data-quality gate, with honest correlation-vs-causation labeling and next-check recommendations.
- **Enterprise — Governed analytics investigator:** Adds a warehouse-wide metric/semantic layer, broad event integrations, cost governance, PII-safe aggregation, and tuning of seasonality/baselines from feedback at scale.

## FAQ

**Will it tell me the definitive cause of a metric change?**

It gives ranked, evidence-backed hypotheses with explicit confidence and labels them correlation vs. likely-causal. Observational data rarely proves a single cause, so it's honest about that and tells you what would confirm each hypothesis.

**How does it avoid 'explaining' a fake anomaly?**

It checks data quality and seasonality first — pipeline gaps, double-counting, definition changes, known cycles. If the move is a data artifact, it reports that instead of inventing a behavioral explanation.

**Is it safe to run against our warehouse?**

Yes. It runs read-only, cost-bounded queries (no unbounded scans), validates query cost where possible, and works at aggregate/segment level so it doesn't surface PII.

**What does it do when nothing correlates?**

It says so. It presents any low-confidence hypotheses, declines to manufacture a single cause, and escalates with the specific data or experiment that would resolve the question.

**How does it find where the change came from?**

It decomposes the metric across your dimensions (region, platform, cohort, channel) to localize the move, then correlates the change point with deploys, feature flags, campaigns, and external events in the same window.

**How accurate is it?**

Accuracy depends heavily on good metric definitions, dimensions, and seasonality baselines — those are the biggest levers. It also shows its evidence and confidence so you can verify each hypothesis rather than trust a black box.


---

© 2026 AgentKits · www.agent-kits.com

**Open source.** Code, configuration, and the AgentAz™ schema are licensed under
**Apache-2.0**; specification text and documentation under **CC BY 4.0** (with
attribution to AgentKits, link to https://www.agent-kits.com). See LICENSE, LICENSE-CONTENT,
and NOTICE in this bundle. "AgentAz" and "AgentKits" are trademarks of AgentKits.

**Flagship reference blueprint.** View the source, AgentAz™ spec, and frozen v1.0 schema
in the public registry: https://github.com/agent-kits/agentaz
Original: https://agent-kits.com/kit/metric-anomaly-explainer
