# Analyzing conversations

A best-practice workflow for reading conversation data — measure the quantitative "what," then the qualitative "why," then watch the conversations behind the numbers.

Analyzing conversations well means reading two layers together:

- **Quantitative — the what.** How much is happening: the trend in number of conversations, number of messages, and number of action calls.
- **Qualitative — the why behind the what.** The intent breakdown (action vs. information), which questions and actions come up most, where the action gaps and knowledge gaps are, and what drives positive and negative sentiment.

The quantitative layer tells you *that* something changed. The qualitative layer tells you *why*, and what to do about it. Read them in that order, then watch a handful of the actual conversations to confirm what you concluded.

<Mermaid chart={`flowchart LR
    A["1. Quantitative<br/>the what"] --> B["2. Qualitative<br/>the why"]
    B --> C["3. Watch<br/>session replay"]
    C --> D["Act<br/>knowledge or action"]
    style A fill:#e8ecff,stroke:#1842ef,color:#0a0e1a
    style B fill:#fef3c7,stroke:#d97706,color:#0a0e1a
    style C fill:#dbe2ff,stroke:#1842ef,color:#0a0e1a
    style D fill:#d1fae5,stroke:#059669,color:#0a0e1a
`} />

## Part 1: Quantitative — the what

**Path:** Analytics → Dashboard → Conversations

Start with volume. These three numbers tell you how much work the agent is doing and how hard users are working to get it.

| Measure | Widget | What it tells you |
| :--- | :--- | :--- |
| **Number of conversations** | [Conversations](/user-guides/analytics/conversation-metrics/) | Overall engagement — how much the agent is being used. |
| **Number of messages** | [User Messages](/user-guides/analytics/conversation-metrics/) | Total volume of what users send the agent. |
| **Action calls** | [Action Calls](/user-guides/analytics/actions/) | How often the agent does real work, not just answers. |

Read them as a set, not in isolation:

- **Conversations rising** is engagement growing — but on its own it's ambiguous, because retries after a failure also raise the count. Pair it with the qualitative layer to know which.
- **Messages rising faster than conversations** means users are working harder for the same result. That usually points to a knowledge or clarity problem, not a capability one.
- **Action calls rising** is the agent resolving by *doing*. Action calls growing alongside steady engagement is the healthiest pattern on the dashboard.

Each widget supports the **time-range** selector and an **Agent** filter, so you can see whether a trend is fleet-wide or concentrated in one agent.

## Part 2: Qualitative — the why behind the what

The numbers above don't tell you *what* users are asking or *why* a conversation went well or badly. That lives in the signal tags on each conversation — surfaced in aggregate on [Signals frequency](/user-guides/analytics/signals-frequency/) and [User intent](/user-guides/analytics/user-intent/), and readable one by one in [Agent Studio → Conversations](/user-guides/conversations/), where **Agent Knowledge Gap** and **Agent Action Gap** are among the filters you can apply.

Work through the qualitative layer in this order: the intent breakdown, then the top asked questions and top-used actions, then the action gaps and knowledge gaps, then what drives positive and negative sentiment. Each step narrows the next.

:::tip[Ask the Foldspace agent]
On the [Conversations](/user-guides/conversations/) page you can also just ask the built-in Foldspace agent — for example, *"What are the action gaps in the last 30 days?"* or *"What topics get the most thumbs down?"* — and it reads the same signals for you. Use it to get oriented fast, then apply the matching filter to read the underlying conversations yourself.
:::

### Intent breakdown — action vs. information

[User intent](/user-guides/analytics/user-intent/) classifies each conversation into what the user was trying to do:

- **Information Request** — asking for information.
- **Action Request** — wanting the agent to *do* something.
- **Reported Issue** — reporting a problem.

The breakdown tells you what the agent is really *for*. A rising **Action Request** share means users increasingly want the agent to act, not just answer — which raises the value of closing action gaps. A rising **Reported Issue** line is usually a product problem worth investigating, not an agent one.

### Top asked questions

The information side first: what users ask about most. Every conversation in [Conversations](/user-guides/conversations/) carries an auto-generated **topic**, and the embedded Foldspace agent aggregates them — ask it *"What are the top questions users ask?"* or *"What are the most common topics this month?"*

The top questions are the core of what users rely on the agent to know. Keep the [Knowledge Base](/user-guides/knowledge-base/) content behind them accurate and current — a stale answer on a top question does more damage than a missing answer on a rare one. They're also the best source of [conversation starters](/user-guides/building-your-agent/), since they're what users were going to ask anyway.

### Top-used actions

Next, the action side: see which capabilities carry the load. In [Reports](/user-guides/analytics/reports/), add the **Action Called** metric and break it down by **Action key** — a stacked bar of which [actions](/user-guides/analytics/actions/) are called most over time.

- The **top actions** are what users actually rely on the agent to do. Keep them healthy — a regression there hurts more than anywhere else.
- An action with **zero or near-zero usage** is either broken, undiscoverable by the agent, or solving a problem users don't have. Check its wiring before assuming the last one.

### Action gaps

The inverse of top-used actions: what users ask the agent to *do* that it can't. Every such conversation is tagged **Agent Action Gap**, ranked in aggregate on [Signals frequency](/user-guides/analytics/signals-frequency/).

A rising Action Gap share means users want capabilities that don't exist yet. Filter [Conversations](/user-guides/conversations/) by the tag, cluster the requests by *verb*, and a repeated verb is a candidate [action](/user-guides/authoring-actions/). Before building, check whether the action already exists and the agent just isn't calling it — that's an instruction fix, not a build. A repeated theme is a roadmap item; fifty one-off requests are a signal about scope, not a backlog.

### Knowledge gaps

The same pattern for questions: where the agent lacked the content to answer, the conversation is tagged **Agent Knowledge Gap**.

A rising Knowledge Gap share is a reading list for the [Knowledge Base](/user-guides/knowledge-base/) — filter Conversations by the tag, cluster the questions, and check with **View Analysis** whether the answer was missing, stale, or simply not retrieved. Missing content needs writing; stale content needs updating; unretrieved content is a retrieval problem where another article won't help — see [Knowledge validation](/user-guides/knowledge-validation/).

### What drives positive sentiment

Ask the embedded Foldspace agent on the [Conversations](/user-guides/conversations/) page to surface the topics correlated with the positive signals — *"What topics get the most thumbs up?"* or *"What topics correlate with positive sentiment?"* It reads the same tags and topics across every conversation, so the answer is measured, not anecdotal.

The topics it surfaces are the questions and tasks the agent handles well — the ground you want to protect as you change things, and the pattern to extend to adjacent topics.

### What drives negative sentiment

Ask the inverse — *"What topics get the most thumbs down?"* or *"What topics correlate with negative sentiment?"* — to get the topics dragging sentiment down.

Then read a few of the underlying conversations behind each topic. Filter by **User Feedback = thumbs down** or **User Sentiment = Negative**, and on a rated reply read the message *before* it — the rating lands on the reply, but the cause is usually the turn before. What you find routes the fix: a content problem goes to the [Knowledge Base](/user-guides/knowledge-base/), a capability problem is an action gap, and a product problem the agent reported accurately belongs on the product backlog, not in the agent.

## Part 3: Watch the conversations behind the numbers

The tags and topics tell you *what* to look at; watching the actual conversation tells you *why* it happened. For a conversation you've flagged, [Session replay](/user-guides/analytics/session-replay/) shows exactly what the user did on screen, with the conversation events overlaid as a timeline.

Reach for it when the transcript alone doesn't explain the outcome:

- A conversation that **escalated** — watch what the user was doing right before they asked, to see what the agent should have handled.
- A **thumbs-down** whose cause isn't obvious from the text — the screen often shows the real intent behind an ambiguous message.
- A **highly positive** conversation on a valuable task — worth understanding so you can extend the pattern.

## Turn it into a worklist

Every pass should end with something to ship, sorted by how often it comes up and how much it costs when it does:

- **Knowledge gaps** → add or refresh a [Knowledge Base](/user-guides/knowledge-base/) article. Usually the cheapest fix, and one good article can close a long tail of related questions.
- **Action gaps** → build or fix an [action](/user-guides/authoring-actions/). More effort, but it converts conversations the agent *can't* resolve today into ones it can.

Then re-check the tag's share next period. If it dropped, the fix worked; if it held steady, go back and read the new ones.

## Related

- [Conversational analytics overview](/user-guides/analytics/conversational-analytics/) — the widgets used in Part 1 and Part 2.
- [Conversations (HITL)](/user-guides/conversations/) — the qualitative surface for reading and filtering conversations.
- [Session replay](/user-guides/analytics/session-replay/) — watching the conversations behind the numbers.
- [Knowledge validation](/user-guides/knowledge-validation/) and [The action lifecycle](/user-guides/action-lifecycle/) — where the fixes get made.