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

# Flows

> A flow is one or more agents doing one job - anchored in your code and confirmed by your traces, and the unit Glassray finds deviations against.

A **flow** is one or more agents that run together to do one job - "process a refund", "answer a support question", "enrich a lead". It can be a **single agent**, or a **chain of several agents** working together.

A flow has two anchors:

* **Code (intent)** - where the flow lives in your codebase. Glassray reads your code to learn the flow exists and what it's meant to do.
* **Traces (reality)** - the evidence the flow actually ran.

Glassray places each trace into a flow by its **shape** - which agents ran and how they're chained together in the trace - and matches that against the flows it found in your code. A flow is where the two meet: your code's intent and your traces' reality. Every trace lands in exactly one flow, or, when nothing matches, an unmatched pool.

## How traces join a flow

Glassray sorts each incoming trace into a flow by its shape - matching which agents ran, and how they're wired, against the flows it found in your code. A trace that doesn't match any flow goes into an **unmatched pool**, which Glassray can cluster into proposed new flows for you to confirm.

Every trace records *how* it joined its flow and *why*, so membership is always something you can inspect - never a black box.

## Flow states

A flow's two anchors - its place **in your code** and the **evidence** of it running in your traces - can arrive independently, which gives a flow one of three states:

<CardGroup cols={3}>
  <Card title="Confirmed" icon="circle-check">
    Defined in your code **and** seen in your traces. Real and ready to evaluate.
  </Card>

  <Card title="Waiting" icon="clock">
    Defined in your code but **not yet seen** in the traces you've synced. Never "dead" - just waiting for evidence.
  </Card>

  <Card title="Discovered" icon="lightbulb">
    Seen in your traces, but Glassray doesn't yet have a reference to where it lives in your code. Glassray proposes it so you can confirm it.
  </Card>
</CardGroup>

## Why flows matter

<CardGroup cols={2}>
  <Card title="Every trace has a home" icon="house">
    Each trace lands in exactly one flow (or the unmatched pool), so nothing falls through the cracks.
  </Card>

  <Card title="The unit of quality" icon="chart-line">
    Glassray tracks behavior and finds [deviations](/deviations) per flow - so a problem is scoped to the job it actually affects.
  </Card>

  <Card title="Cold-start value" icon="seedling">
    Because flows can be defined from your code, you see your flows and how they wire up before you've synced much trace volume.
  </Card>

  <Card title="Explainable membership" icon="list-check">
    Every trace records how and why it joined its flow - inspect it in the dashboard or over [MCP](/mcp-server).
  </Card>
</CardGroup>