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

# Flows

> Reference for Flows: how Kubit groups every agent run by execution path, names each step and draws all paths in one Sankey with a count per path.

Flows groups every agent run by its execution path (which tools and model calls ran, in what order) and draws all paths in one Sankey. Each path shows how many traces took it, so a failure that repeats a thousand times shows up as one path with a count of 1,000. This page covers how Flows builds a path, how it names steps and how to ask for a flow from an AI assistant.

## When to use

| **Use case** | **Example** |
| - | - |
| Tell a one-off failure from a pattern | One path with a count of 1,000 instead of 1,000 separate traces |
| Find loops | A trace that calls `search_orders` three times in a row shows three `search_orders` steps |
| See which paths end in an error | Steps named after their Exception or Misstep label |
| Compare how runs move through the agent | Every execution path in one Sankey, not only the failed ones |

## How a Path Is Built

An execution path is the ordered sequence of spans in one trace. Each span is one step, in order of span start time. Two traces that called `search_orders`, then `get_refund_policy`, then the LLM, share one execution path, even if their inputs differ.

### How it works

Flows names each step by the action Polaris annotates the span with.

| **Span** | **Step name** |
| - | - |
| LLM call | The task named from its system prompt, such as `generate_title`, or else its decision, such as `reply` or `call_<tool>` |
| Tool call | The tool name |
| Anything else | The span name |

Repeated consecutive calls stay separate steps. The **Fold Label** adjustment turns consecutive spans with one label into one step. When two runs call the same tools with different arguments, Polaris labels or custom eval scores may split them into separate paths.

## Reading the Sankey

Flows draws every execution path in one Sankey, with the number of traces that took each path.

## Agent Flow From an AI Assistant

The Kubit MCP server builds an **Agent flow** report when you ask for span labels, tool calls and model calls drawn over whole traces. [Report types](https://learn.kubit.ai/lumos-ai/tools.md#report-types) lists it with the other report types.

### Example Prompts

> "Show the agent flow across our traces over the last 14 days"

> "Show me the top 10 execution paths for the support agent in the last 7 days"

## Flows and the Path Report

Flows is the Agent Observability view of execution paths inside agent traces. The [Path report](https://learn.kubit.ai/product-analytics/reports/path.md) is the Product Analytics report of event sequences, for users or sessions, and works on clickstream events too. Never call the Path report Flow.

## Related

* [Concepts](https://learn.kubit.ai/agent-observability/concepts.md#execution-path): the definition of an execution path.
* [Polaris](https://learn.kubit.ai/agent-observability/use/polaris.md): the labels that name each step.
* [Triggers](https://learn.kubit.ai/agent-observability/use/triggers.md): what changed when a path's numbers move.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.