# User intents

Semantic clusters of user prompts — what your users are actually asking for, grouped automatically.

The **User Intents** page tells you *why* people are talking to your agent — not the literal prompts, but the underlying goals. Brizz groups thousands of unique phrasings into a small set of intent clusters automatically, so you can spot what's popular, what's surging, and what your product doesn't yet support well.

## What it is

A **user intent** is a semantic cluster of similar prompts. "I want to cancel," "Stop my subscription," and "Turn off auto-renew" all map to one **Cancellation** intent. Brizz discovers these clusters from your data — you don't define them upfront, and there's no manual tagging.

Intents are organized hierarchically: broad parent intents break down into more specific child intents, so you can navigate from "Account management" → "Cancellation" → "Cancel due to price."

## How it's computed

The analytics pipeline runs intent clustering on the user-side messages of every session:

1. **Embedding** — each user prompt is embedded into a vector.
2. **Clustering** — vectors are grouped by similarity; small clusters merge into broader ones, large clusters split into specific children.
3. **Labeling** — Brizz uses an LLM to write a human-readable label for each cluster from its representative prompts.
4. **Volume tracking** — clusters are sorted and re-ranked over time as new sessions arrive.

The clustering job runs as a background workflow; intents typically appear within a few hours of new traffic.

## How to read it in the dashboard

Two views, same data:

- **Tree view** — the hierarchy. Start broad, click into child clusters to drill down. Best for exploring what categories of intent exist.
- **List view** — flat ranking by volume. Best for "what are the top 20 things users want right now."

Each cluster shows:

- **Volume** — how many prompts (and sessions) fall into the cluster over the selected window.
- **Trend** — week-over-week or day-over-day change. A surging intent often signals a new use case worth supporting.
- **Examples** — click in to see the actual prompts. The label is a summary; the examples tell you what users really said.

Use the **search** bar to test whether a phrase you're worried about forms its own cluster.

## How to act on it

1. **Prioritize roadmap by volume.** The top 10 intents by volume cover most of your traffic. If a high-volume intent corresponds to a product gap, that's your next feature.
2. **Watch trend, not just volume.** A small but fast-growing intent (e.g., a new integration question) often matters more than a stable popular one.
3. **Improve docs and prompts for confusing intents.** Some intents reveal users *don't know how to ask* — that's a docs/UX fix, not a model fix.
4. **Export representative prompts for fine-tuning or eval.** A clean cluster is a ready-made eval set or training corpus for a focused fine-tune.
5. **Cross-reference with Issues.** If an intent has a matching content issue, users are asking and your agent is failing — high leverage.

## See also

- [User journeys](/docs/platform/user-journeys.md) — what people *do* with your agent, vs. what they *ask for*.
- [Issues](/docs/platform/issues.md) — quality problems on the responses to those intents.
- [Identify users](/docs/instrument/identify-users.md) — intents become more useful when you can segment by user cohort.