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

# Issues & Diagnosis

> Sentrial automatically detects issues in your agent sessions and provides AI-powered diagnosis to help you fix them fast.

## How Issue Detection Works

Sentrial analyzes every session automatically to identify problems. No manual tagging required.

<CardGroup cols={3}>
  <Card title="Automatic Scanning">
    Every session is analyzed in real-time as events stream in.
  </Card>

  <Card title="AI Analysis">
    LLM evaluates sessions for failures, confusion, errors, and inefficiencies.
  </Card>

  <Card title="Smart Grouping">
    Similar issues are grouped together so you see patterns, not noise.
  </Card>
</CardGroup>

## What We Detect

Sentrial identifies a wide range of issues across your agent sessions:

| Issue                | Description                                                              | Severity |
| -------------------- | ------------------------------------------------------------------------ | -------- |
| **Task Failures**    | Agent failed to complete the user's request                              | High     |
| **Tool Errors**      | A tool call failed, returned unexpected results, or timed out            | High     |
| **Hallucinations**   | Agent made claims not supported by context or tools                      | High     |
| **User Frustration** | Signs of user dissatisfaction, repeated questions, or negative sentiment | Medium   |
| **Confusion Loops**  | Agent appears stuck, repeating actions or asking the same questions      | Medium   |
| **Slow Responses**   | Session took significantly longer than expected                          | Low      |
| **High Cost**        | Session used more tokens/cost than typical                               | Low      |

## AI-Powered Diagnosis

When you click on an issue, Sentrial provides:

* **Root Cause Analysis** — Why did this happen? What triggered it?
* **Affected Sessions** — All sessions impacted by this issue
* **Recommended Fix** — Specific suggestions to resolve the issue
* **Code Context** — Links to relevant code if GitHub is connected

## The Signals Page

The Signals page in your dashboard is your command center for issues:

<CardGroup cols={2}>
  <Card title="Issue List">
    All detected issues sorted by severity and frequency.
  </Card>

  <Card title="Trend Charts">
    See how issue counts change over time.
  </Card>

  <Card title="Filters">
    Filter by agent, time range, severity, or issue type.
  </Card>

  <Card title="Quick Actions">
    Jump to diagnosis, affected sessions, or code fixes.
  </Card>
</CardGroup>

## Fixing Issues in Code

<Note>
  **Code Integration** — Connect your GitHub repository and fix issues directly from the diagnosis page.
  Chat with AI about the issue, get code suggestions, and create PRs — all in one flow.
  [Learn about Code Integration →](/concepts/code-integration)
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Track session outcomes">
    Always call `complete_session()` with `success=True/False` so we can identify failures.
  </Accordion>

  <Accordion title="Include failure reasons">
    When `success=False`, include `failure_reason` for better diagnosis.
  </Accordion>

  <Accordion title="Use consistent agent names">
    Group sessions by `agent_name` to see issues per agent type.
  </Accordion>

  <Accordion title="Track user IDs">
    Include `user_id` to identify user-specific issues and patterns.
  </Accordion>
</AccordionGroup>

```python theme={null}
# Good: Complete session with full context
client.complete_session(
    session_id=session_id,
    success=False,
    failure_reason="Tool 'search_kb' returned empty results for query",
    estimated_cost=0.023
)

# This gives Sentrial the context to:
# - Identify this as a tool failure issue
# - Group similar empty-result failures
# - Suggest fixes (e.g., improve search, add fallback)
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Code Integration" icon="code" href="/concepts/code-integration">
    Fix issues directly in your codebase.
  </Card>

  <Card title="Sessions & Tracking" icon="timeline" href="/concepts/sessions">
    Learn how to track sessions properly.
  </Card>
</CardGroup>