> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komodor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Insights

> Failures across your agents, grouped and ranked, each with the evidence behind it and an agent-produced next step.

**Insights** answers the question you have right after agents start failing: what is failing, why,
and what to do about it. The Komodor Agentic Operation Platform (KAOP) groups related failures into
ranked issues, shows the reason each one reported verbatim, and attaches a recommendation produced
by a real agent investigating your account.

Find it under **Improve → Insights**.

## What the page tells you

The header figures cover the last 30 days of account activity:

| Card             | What it reports                                                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **30-day runs**  | Total runs, with the succeeded count beneath.                                                                                    |
| **Failures**     | Failed runs, broken down by the top failure categories.                                                                          |
| **Success Rate** | Outcome rate over the last 100 terminal runs.                                                                                    |
| **Known Cost**   | Usage that carried a cost figure. Full attribution lives on [Agent spend](/manage-your-agents/optimize/agent-spend-attribution). |

Below that, a 30-day activity heatmap plots run volume and failures day by day, so a bad day is a
visible block rather than an averaged-away dip. Five charts break the same window
down further:

* **Run trend** — recent volume.
* **Run status** — the current outcome distribution across `Queued`, `Claimed`, `Running`,
  `Succeeded`, `Failed`, and `Cancelled`.
* **Agent activity** — runs by agent, each row split into succeeded, failed, and active.
* **Model breakdown** — the run mix by model.
* **Failure causes** — failures by category, using the categories below.

<Note>
  Insights is fixed to a 30-day window. If you need a shorter or longer period for reliability, the
  [Fleet health](/manage-your-agents/optimize/fleet-health) Analytics tab offers Today, 7 days, and 30
  days.
</Note>

## How failures are categorized

This is the part worth understanding, because it is what makes the rest trustworthy. KAOP segments a
failing or stuck run **only from structural signals it can prove** — the run's status, the shape of
its span tree, and the agent's presence. It never guesses a cause by matching substrings in an error
message.

| Category                 | The structural proof behind it                                                       |
| ------------------------ | ------------------------------------------------------------------------------------ |
| **Agent run failed**     | The run failed *with* an agent span that ended in error. The handler ran and raised. |
| **Worker unreachable**   | The run failed with *no agent span at all*. The agent never started.                 |
| **Tool call failed**     | A tool span ended with an error status.                                              |
| **Stuck unclaimed**      | The run sat queued past its lease window with no worker claiming it.                 |
| **Worker offline**       | Work is queued or claimed while the agent's presence is down.                        |
| **Unclassified failure** | The run failed with no structural proof of a cause.                                  |

<Info>
  **Why prose matching is refused.** An error string is written by whatever failed, in whatever
  wording it chose, and it changes without warning. A classifier built on it produces confident labels
  that are sometimes wrong, and a wrong label is worse than no label — you go and check the thing it
  named instead of the thing that broke. So a run KAOP cannot prove stays **Unclassified failure**,
  with its real error text attached, rather than being forced into a plausible bucket.
</Info>

### The reason is shown verbatim

Instead of re-labelling what a run reported, KAOP shows the failure reason exactly as it arrived —
`Missing Datadog credentials. Set DD_API_KEY and DD_APP_KEY…` reads as that sentence, not as
"configuration error". The category tells you *where* to look; the verbatim reason tells you *what*
happened. Grouping uses the category together with the normalized reason, so identical failures
collapse into one issue instead of a hundred rows.

## Needs attention

The **Needs attention** panel is the ranked list of issues — "ranked failure clusters with an
agent-backed recommended fix". Each card carries:

* The **category** badge and a **confidence** badge (**High**, **Medium**, or **Low confidence**).
* A **Growing** marker when the issue is getting worse rather than sitting still.
* The issue title and why it happened.
* The scale: how many runs, how many agents, and when it was last seen.
* The recommendation, once produced.

Ranking is by severity first, then by how many runs an issue affects. Severity is derived, not
assigned: an issue is high severity when it is growing or affects at least five runs, medium when it
was last seen inside the window, and low otherwise. High-severity issues are treated as incidents.

An issue carries a lifecycle you can read on it — **open**, **investigating**, or **resolved** —
which moves as an investigation starts and finishes.

## Recommendations come from a real agent run

A recommendation is not a lookup in a table of canned advice. When you ask for one, KAOP starts a
run on a chat-capable agent, which investigates the issue **using your account's own tools** and
returns two things: a one- or two-sentence tagline for the card, and a full root-cause write-up
behind **Details**.

<Steps>
  <Step title="Pick who recommends">
    The **Recommendations by** control selects which chat-capable agent investigates. Your choice is
    remembered, so the agent that knows your environment best stays selected.
  </Step>

  <Step title="Ask for a recommendation">
    Press **Recommend**. The card shows *Investigating…* while the agent works.
  </Step>

  <Step title="Read the tagline, then the detail">
    The tagline is the answer in one line. **Details** expands the full root-cause analysis, with
    the evidence the agent used.
  </Step>

  <Step title="Continue interactively">
    **Chat** — or **Continue in chat** from inside the details — takes you into the same session,
    prefilled with the failure context. You are continuing the investigation, not restarting it.
  </Step>
</Steps>

<Tip>
  Because a recommendation is a run, it has an evidence trail like any other run. If a recommendation
  looks wrong, you can read exactly which tools the investigating agent called and what they returned
  — which is the difference between an opinion and a traceable conclusion.
</Tip>

## Acting on each category

The category tells you where the fix lives, and each issue links to the right place.

| Category                 | Where to go                                                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| **Agent run failed**     | The failing run's evidence. The spans and logs show what the agent was doing when it raised.                               |
| **Worker unreachable**   | [Fleet health](/manage-your-agents/optimize/fleet-health) — confirm the worker is running and can reach the control plane. |
| **Tool call failed**     | The integration behind the failing tool — check its connection and health.                                                 |
| **Stuck unclaimed**      | Fleet health — usually there is no online worker for that agent.                                                           |
| **Worker offline**       | Fleet health — bring the fleet back or scale it up.                                                                        |
| **Unclassified failure** | The run's evidence. The verbatim reason and the logs are the whole lead.                                                   |

<Warning>
  KAOP recommends and never remediates on its own here. There are no automatic retries, restarts,
  credential rotations, or scale-ups behind an issue. Every fix is yours to make, which is why the
  recommendation names the place to make it.
</Warning>

## Where else issues appear

The account **Overview** carries a compact form of the same panel — the top reliability issues
from the last 30 days, with a **View insights** link. It is deliberately read-only: it never starts
a recommendation run, so opening your home page costs nothing.

## Next steps

<CardGroup cols={2}>
  <Card title="Fleet health" href="/manage-your-agents/optimize/fleet-health">
    Live presence, capacity, and the per-agent reliability ranking.
  </Card>

  <Card title="Runs & evidence" href="/manage-your-agents/run/runs-evidence">
    The span tree the categories are proved from.
  </Card>

  <Card title="Troubleshooting" href="/reference/troubleshooting">
    The fixes for each of these categories, step by step.
  </Card>

  <Card title="Evaluations" href="/manage-your-agents/optimize/evaluations">
    A run that succeeded can still be wrong. This is how you find out.
  </Card>
</CardGroup>


## Related topics

- [Optimize — how it works](/manage-your-agents/optimize/how-it-works.md)
- [Limits & quotas](/reference/limits-quotas.md)
- [Proactive reliability optimization](/modules-and-workflows/sre/reliability-optimization.md)
- [Troubleshooting](/reference/troubleshooting.md)
- [Fleet health](/manage-your-agents/optimize/fleet-health.md)