Chat and the assistant

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.

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
• create and run apps, and open and operate their screens; see Apps
• open a file processor, read the records it extracted and suggest or change its fields; see Documents and spreadsheets
• 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.

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.

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

Related