> Documentation index: https://docs.beetl.io/llms.txt

# Chat and the assistant

> Where the assistant lives, what it knows, and how to work with it.

Source: https://docs.beetl.io/chat/
Last updated: 2026-11-10

The assistant answers questions about your data in plain language, builds pipelines with you, and manages automations, reports, apps and file processors.
You reach it in 2 places: the Assistant sidebar beside the page you have open, and the full-screen
AI Chat page.

## Where it lives

The **Assistant sidebar** sits at the right edge of every page except AI Chat. Close it with the X
in its header and bring it back with **Open Assistant**. On a phone, the round button in the
bottom-right corner opens it full screen. The sidebar holds one ongoing conversation per user.
**Clear** deletes that history permanently after you confirm, and you can't clear while a turn is
running. The sidebar also sees the page you have open and can edit it; see
[Building with the assistant](https://docs.beetl.io/chat/building-with-the-assistant).

**AI Chat** in the left navigation opens your most recent conversation. Point at it to see
**New Chat** and your recent chats. On a wide screen, the page lists your conversations on the
left, with a New chat button and **Delete** in each row's menu. Beetl names a conversation after its
first answer. Conversations are private to you, and the sidebar conversation isn't in this list.

A turn keeps running if you close the sidebar, move to another page or close the tab. When you come
back, the conversation shows how far it got.

## Asking about your data

Ask the way you would ask a colleague who knows SQL. The assistant can:

* find datasets and describe their columns
* write a query, run it and explain the result
* build a pipeline or change an existing one
* look at a pipeline's runs and explain why one failed
* explain an error message you got
* create, run, pause and update automations
* write a report, run it and render a PDF; see [Reports](https://docs.beetl.io/reports)
* create and run apps, and open and operate their screens; see [Apps](https://docs.beetl.io/apps)
* open a file processor, read the records it extracted and suggest or change its fields; see
  [Documents and spreadsheets](https://docs.beetl.io/sources/documents)
* show where a dataset, pipeline or report gets its data

Name the dataset if you know it, and ask to see the SQL when you want to check an answer.

### What it can and can't do

* It reads the datasets and pipelines in your tenant.
* Queries it runs can't insert, update or delete anything.
* It never writes to your connected systems.
* It can create and change pipeline drafts in Beetl. Deploying one asks you to **Allow** first.
* It can create, change, run, pause and resume automations. Deleting one asks you to **Allow** first.
* It can create, run and render reports. Reports write PDFs to your storage and don't ask first.
* It can change apps and operate app screens. Each of these asks you to **Allow** first.
* It can change file processors. Saving, analyzing and processing documents, and editing a
  processor's fields, ask you to **Allow** first. Reading does not.

For how each change is gated, see
[The agent trust boundary](https://docs.beetl.io/concepts/agent-trust-boundary).

## Mentions, results and pipelines

Type `@` in the composer to mention a dataset or a pipeline. The list shows each dataset's tier and
each pipeline's working version. A mention hands the assistant that dataset's columns or that
pipeline's current draft, so it can start without looking them up. Mentions appear as chips above
the input; select one to remove it.

On AI Chat, when a turn finishes, the last query result, pipeline, data-flow view or report it
produced opens in a pane beside the conversation. A result has the same Table and Chart views as
the Query page, a pipeline opens in the editor, a data-flow view shows what feeds a dataset,
pipeline or report and what it feeds, and a report shows its rendered PDF. Drag the divider to resize the pane, collapse it with the arrow, or
choose **Open full page**. You can reopen earlier items from the conversation. In the Assistant
sidebar and on narrow screens, they open the Query page or the pipeline editor instead.

Each reply gathers the steps it took into a collapsed row such as "4 tool calls". Expand it to see
each step and its outcome. When the assistant edits the page you have open, its reply ends with a
**Draft updated** row. See [Building with the assistant](https://docs.beetl.io/chat/building-with-the-assistant).

## What the assistant knows

In each turn, the assistant has:

* your tenant's datasets, pipelines and their schemas, which it looks up as needed
* the datasets and pipelines you mention, and the page you have open in the sidebar
* the [assistant instructions](https://docs.beetl.io/concepts/ai-settings#assistant-instructions) a TenantAdmin wrote for
  the workspace
* Beetl's platform reference, and a generated document for each deployed pipeline
* the conversation so far

TenantAdmins can read the platform reference and pipeline documents under Settings → Wiki. When the
assistant reads one, the step links to it.

It has no memory across conversations. A new chat starts without anything you said in another one,
so put conventions you want applied every time into the assistant instructions.

## Model, effort and credits

Above the composer are a model chip and a reasoning-effort chip (Default, Low, Medium or High). Each
conversation keeps its own choice, and a new chat starts from your last pick. Larger models and
higher effort use credits faster. See [AI in a tenant](https://docs.beetl.io/concepts/ai-settings) for the models and
how credits work.

If the tenant has no AI available, the composer says "AI not configured — set it up in Settings to
send messages" and New Chat is disabled. When the monthly credits run out, a notice above the
composer says "You have reached your monthly AI limit. It resets on the 1st." Admins get a link to
bring their own key, and everyone else is asked to contact an admin. A message refused before its
turn starts goes back into the composer with the reason.

## Checking its work

The **Timeline** tab in the conversation header lists everything that happened, grouped by turn:
your messages, the replies, each tool call with the purpose the assistant gave it, and any
confirmation. Rows show timings and token counts. On a wide screen, select a row to inspect its
details.

Every number the assistant quotes from a query comes with a result you can open. Click a cell to see
the expression and source tables behind it, then open the result full page to drill into the
records. See [Checking a number](https://docs.beetl.io/query/lineage#checking-a-number). Results expire after 7 days, and
an expired one shows "Result expired" with its SQL.

## Stopping, retrying and long conversations

While a turn runs, the send button becomes **Stop**. Select it or press Escape to end the turn.
Stopping doesn't undo changes the assistant already made. If a turn fails, its reply shows
**Try again**. **Copy** under each finished reply copies its text.

A single turn can work for up to 20 minutes. At that limit the assistant stops and asks you to
continue in a new message.

When a conversation nears the model's context window, the assistant summarizes the earlier turns
and carries on. The chat shows "Compacting conversation…" and then a collapsible block with the
summary. A context meter in the composer shows how much of the window is used and turns amber
above 80%. The assistant works from the summary, not the full earlier text, so start a new chat
when you change topic and repeat anything from early on that still matters.

## In this section

| Page                                                             | What it covers                                                                                         |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [Building with the assistant](https://docs.beetl.io/chat/building-with-the-assistant) | Letting the assistant edit the page you are on, build pipelines, and confirm the changes that need it. |

## Related

- [The agent trust boundary](https://docs.beetl.io/concepts/agent-trust-boundary): What the assistant can read and change, and how each change is gated.

- [AI in a tenant](https://docs.beetl.io/concepts/ai-settings): Managed AI or your own key, credits and assistant instructions.

- [MCP and programmatic access](https://docs.beetl.io/mcp): Beetl's tools from your own AI client.