> ## 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.

# Lumos

> Reference for Lumos, the Kubit AI Agent: ask about traces or product events in plain language and get reports, cohorts and investigations back.

This page covers Lumos, the Kubit AI Agent. You ask a question in plain language, and Lumos builds the report or cohort, finds existing reports, explains anomalies or investigates where your agent fails. It reads your model's metadata to map your words to events, fields and filters.

Lumos works for Agent Observability and Product Analytics. Ask about your AI agent's traces, spans and tool calls, about your users' product events, or about both together, such as users who left after talking to the agent.

Your data is never used to train models.

![Lumos home page with the sessions panel on the left (New, Recents and one session), a How can I help you? prompt box and five sample questions.](https://mintcdn.com/kubit/7Re-RwY1NQJAR2vJ/images/lumos/lumos-home.png?fit=max\&auto=format\&n=7Re-RwY1NQJAR2vJ\&q=85\&s=6bfb3fde43a3289e44b4c7c47d010e38)

## When to use

<table>
  <colgroup>
    <col width="281" />

    <col width="463" />
  </colgroup>

  <thead>
    <tr>
      <th>**Use case**</th>
      <th>**Example**</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Finding where your agent fails</td>
      <td>"Where do shopping agent traces fail over the last week?"</td>
    </tr>

    <tr>
      <td>You don't know which report fits</td>
      <td>"Where do new users drop off during onboarding?"</td>
    </tr>

    <tr>
      <td>Exploring step by step</td>
      <td>Ask for a chart, then "break that down by plan", then "only users from paid campaigns"</td>
    </tr>

    <tr>
      <td>Finding existing work</td>
      <td>"Find reports about trial conversion"</td>
    </tr>

    <tr>
      <td>Checking a spike or drop</td>
      <td>"Is there anything unusual in this report?"</td>
    </tr>

    <tr>
      <td>Explaining a change</td>
      <td>"Why did activation drop last week?"</td>
    </tr>
  </tbody>
</table>

## Open Lumos

Open Lumos from **Lumos** at the top of the left nav. Type in the prompt box, or click one of the **Sample questions** under it. Select the schema Lumos should use if your workspace has more than one.

**+ New** at the top of the sessions panel starts a new chat.

## Ask for reports and cohorts

Lumos builds a report or cohort from a question and shows the result in the chat. Follow-up prompts change the last result, such as adding a group-by or a filter.

The answer opens with a summary of the numbers, then **Suggested next steps**, then a card with the report's name, date range and interval. Click the card to open the report in the **Report** pane next to the chat. The prompt box then shows a chip with the report's name.

![Lumos answer to Checkouts by SKU category over the last week: a summary of 1,684 checkout events by category, three suggested next steps and a report card, with the bar chart open in the Report pane on the right.](https://mintcdn.com/kubit/7Re-RwY1NQJAR2vJ/images/lumos/answer-with-report.png?fit=max\&auto=format\&n=7Re-RwY1NQJAR2vJ\&q=85\&s=1eef3f7489c441692276f31dfd228a33)

A report or cohort from Lumos is the same as one built by hand:

<table>
  <colgroup>
    <col width="277" />

    <col width="368" />
  </colgroup>

  <thead>
    <tr>
      <th>**Action**</th>
      <th>**How**</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Edit it in the builder</td>
      <td>Click **Open in Explorer** in the Report pane</td>
    </tr>

    <tr>
      <td>Add it to a dashboard</td>
      <td>Open it in Explorer, then **Share report** > **Add to Dashboard**</td>
    </tr>

    <tr>
      <td>Export it</td>
      <td>**Share report** (the upload icon) in the Report pane: **Export as CSV**, **Upload to Google Drive** or **Open in Jupyter**</td>
    </tr>

    <tr>
      <td>Ask about one part of it</td>
      <td>Click **Point to ask** in the prompt box, then click anything in the report</td>
    </tr>
  </tbody>
</table>

A good prompt names what to measure, the events, the date range and any group-by or filter. Lumos fills in the rest.

### Example Prompts

> "Show me daily active users by platform for the past 2 weeks"

> "Where do shopping agent traces fail over the last week?"

> "How many users abandoned onboarding after talking to the agent last week, compared to the week before? Break that down by primary intent."

## How Lumos answers

Lumos answers each question in one run. It doesn't hand the question to a separate agent by topic. Lumos picks tools from the table below, calls as many as the question needs within the limits further down, and writes the answer from what they return.

While the run works, the chat lists each step it takes. Click **Stop** to end a run early.

### What Lumos can do

| **Capability** | **What Lumos does** |
| - | - |
| Look up your data | Reads the events, fields and subjects in your workspace. It also finds which field holds a value, such as "premium", even when the value is misspelled. |
| Build a report | Writes and runs a report, then saves it in your workspace. A report already built in the same chat isn't built again. |
| Read a report | Reads a report that already exists, such as one from earlier in the chat. Lumos runs it again only when its data is too old for the question. |
| Find reports | Searches report names, not their contents, and returns up to 10 reports with their type and last edit date. Dashboards aren't searched. |
| Build a cohort | Builds an Inspection report of the people you describe, and publishes it as a cohort only when you ask. It also finds a published cohort by its name or description. |
| Change a chart | Changes how a report in the chat is drawn. The change is saved to the report when the answer arrives, and you can undo it. |
| Publish a component | Publishes a filter, measure, virtual event, binning or cohort from a report built in the chat. Lumos publishes only when you ask. |
| Investigate a failure | Compares the traces that failed at one node of an Agent flow report with the traces that took the same path and didn't fail. It returns the span field values that differ significantly and the request themes more common in the failures. |
| Open traces at a node | Builds an Activity report for one node of an Agent flow report and returns its first 20 traces |
| Search earlier chats | Finds your questions and its answers from your earlier sessions in the workspace, from the last 30 days |
| Remember facts | Saves facts that stay true to Lumos memory. Workspace memory holds facts about the data, such as which field holds revenue, and every member's chats use it. Your own memory holds how you want results, such as a default interval. The chat shows **Saved to Lumos memory** with an undo option. |
| Read your code | Reads files, searches code and reads git history in the GitHub repositories connected to the workspace |
| Use connected apps | Calls the tools of MCP servers connected to the workspace, such as Google Drive |

Lumos runs **Investigate a failure** and **Open traces at a node** only when you ask for them. Otherwise it suggests them.

**Availability:** **Read your code** and **Use connected apps** need a GitHub or MCP connection on the workspace **Integrations** settings page. Without one, Lumos answers from your Kubit data only.&#x20;

### Limits

| **Constraint** | **Value** |
| - | - |
| Reports built or run again per answer, counting failure investigations and node trace lookups | **5** |
| Steps per answer | **60**, plus 30 for each connected repository after the first, up to **150** |
| Run length | **30 minutes** |
| Earlier chats searched | Last **30** days |
| Reports returned by a search | **10** |
| Traces returned for a node | **20** |
| Lumos memory entry | **300** characters |

### Example Prompts

> "Why did the support agent's Exception rate go up last week? Check the code in our repo."

> "Find the report I built yesterday on tool call latency and break it down by model version"

> "Investigate the failures at the search\_docs node of the Agent flow report"

## Anomalies

Kubit checks a report for anomalies every time a Query report, or a Funnel report in Conversion mode, runs. It marks them on time series charts, with or without a group-by. When a report in the chat has anomalies, Lumos receives them with the report and explains them in its answer. There are three kinds:

<table>
  <colgroup>
    <col width="112" />

    <col width="572" />
  </colgroup>

  <thead>
    <tr>
      <th>**Kind**</th>
      <th>**Means**</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Volume**</td>
      <td>Record counts outside the normal range</td>
    </tr>

    <tr>
      <td>**Distribution**</td>
      <td>Values that don't match historical patterns</td>
    </tr>

    <tr>
      <td>**Freshness**</td>
      <td>Data that's missing or late</td>
    </tr>
  </tbody>
</table>

Click an anomaly marker and choose **View Anomaly** to see its confidence, triggers and Z-score or MAD score. For daily reports, Kubit compares each point with 7, 14 and 30 day means and the same weekday's mean.&#x20;

## Answer Details

A Lumos answer opens with a summary. When the run collected evidence, such as the files it read or the numbers behind a finding, the evidence goes in a details section under the summary, collapsed. Click **Show details** to open it and **Hide details** to close it. An answer with a single fact has no details section.

Lumos reads the details of its earlier answers in the chat, so a follow-up such as "where did you see that?" gets an answer from the evidence.

## Chat Sessions and Timeline

Kubit saves each chat as a session in the sessions panel, under **Recents**, and names it from its first question. A session's menu (the three-dot icon) has **Open**, **Copy Link**, **Fork**, **Pin**, **Move to**, **Mark as unread**, **Archive**, **Rename** and **Delete**. A forked session shows a fork icon next to its name.

The folder icon at the top of the panel (**New section**) adds a section that **Move to** can file sessions into. The arrow next to it (**Collapse panel**) hides the panel.

![Lumos sessions panel with the menu of the Weekly Checkouts by SKU Category session open, listing Open, Copy Link, Fork, Pin, Move to, Mark as unread, Archive, Rename and Delete, next to the chat.](https://mintcdn.com/kubit/7Re-RwY1NQJAR2vJ/images/lumos/chat-history.png?fit=max\&auto=format\&n=7Re-RwY1NQJAR2vJ\&q=85\&s=170513380a91468f019aca02538452e4)

## Related

* [Reports overview](https://learn.kubit.ai/product-analytics/reports/overview.md): the report types Lumos builds.
* [Dashboards](https://learn.kubit.ai/product-analytics/dashboards.md): save what you find.
* [Find Missteps that return OK](https://learn.kubit.ai/agent-observability/use/find-missteps.md): prompts for finding where your agent goes wrong.
* [Agent plugin](https://learn.kubit.ai/agent-observability/integrate/agent-plugin.md): ask the same questions from Claude Code or Cursor through the [Kubit MCP server](https://learn.kubit.ai/lumos-ai/mcp-server.md).


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