From c364c1b2d0ee78e3bbeca5d02ef60d6ac4a85e82 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 17 Jul 2026 00:43:18 +0000 Subject: [PATCH 1/2] docs: add Deep Research mode guide for the AI agent composer --- docs.json | 1 + guides/ai-agents/deep-research.mdx | 111 +++++++++++++++++++++++++++++ 2 files changed, 112 insertions(+) create mode 100644 guides/ai-agents/deep-research.mdx diff --git a/docs.json b/docs.json index b8f20585..13fd9674 100644 --- a/docs.json +++ b/docs.json @@ -153,6 +153,7 @@ "guides/ai-agents", "guides/ai-agents/getting-started", "guides/ai-agents/using-ai-agents", + "guides/ai-agents/deep-research", "guides/ai-agents/visibility", "guides/ai-agents/ai-router", "guides/ai-agents/agent-memory", diff --git a/guides/ai-agents/deep-research.mdx b/guides/ai-agents/deep-research.mdx new file mode 100644 index 00000000..a2ac1352 --- /dev/null +++ b/guides/ai-agents/deep-research.mdx @@ -0,0 +1,111 @@ +--- +title: "Deep research" +sidebarTitle: "Deep research" +description: "Ask an AI agent a high-stakes question and get back an evidence-backed report — with sources, findings, methodology, and limitations." +--- + + + **Availability:** Deep research is a **Beta** feature available on **Enterprise** plans. It is gated by the `ai-deep-research` feature flag (the same flag used by the Deep Research API). Contact Lightdash to enable it for your organization. + + +Deep research is a mode of the AI agent composer for questions that need more than a single-turn answer. Instead of returning one chart or a short summary, the agent plans an investigation, gathers evidence from multiple sources, and writes a structured report with numbered citations you can trace back to the underlying queries and documents. + +Deep research is the in-product counterpart to the Deep Research API — the same effort tiers and evidence model, exposed as a UI you can drive from an agent thread. + +## When to use it + +Reach for deep research when the question is worth a report, not a reply: + +- *"Which product categories are trending down this quarter, and why?"* +- *"What's driving the drop in returning-customer revenue over the last 90 days?"* +- *"Compare paid-vs-organic acquisition quality across our top three regions."* + +For a quick lookup or a single chart, stay in the default **Ask** mode — deep research is optimized for multi-step investigations, not for one-off queries. + +## Turning it on in the composer + +The agent composer has an inline **Deep research** switch next to the message input. **Ask** is the default and behaves exactly as documented in [Using AI agents](/guides/ai-agents/using-ai-agents) — turning deep research on does not change normal Ask behavior. + +Deep research is available only on **new** agent conversations. To start one, open the agent and click **New thread**, then toggle **Deep research** before you send your first message. + +## Preflight and depth tiers + +When deep research is on, a preflight panel appears above the composer. It lets you pick the **research depth** and shows which evidence sources the agent will search. + +Depths map to the same effort budgets used by the Deep Research API: + +| Depth | API effort | Duration | Warehouse queries | When to use | +| ----------- | ---------- | ----------------- | ----------------- | ----------- | +| **Low** | `low` | Up to 15 minutes | Up to 10 | A focused check of the strongest available evidence. | +| **Medium** | `medium` | Up to 30 minutes | Up to 25 | A balanced investigation with validation and alternatives. | +| **High** | `high` | Up to 45 minutes | Up to 50 | A broad investigation with more competing explanations. | +| **Extra High** | `xhigh` | Up to 55 minutes | Up to 100 | The widest evidence review for high-stakes questions. | + +Duration and query counts are ceilings — many runs finish sooner. Warehouse-query allowances count executed queries against your project's semantic layer or SQL, so heavier tiers do more validation and consider more alternative explanations. + +The preflight also lists the **evidence sources** the current service supports (for example, project data and the public web). Sources that aren't wired up for your deployment are hidden, so you always see the actual research surface for your workspace. + +## The run card + +Submitting a deep research question registers a durable **run card** in the thread immediately. Your question is never lost, even if the network hiccups or you close the tab. + +The card walks through these states: + +- **Queued** — the run has been accepted and is waiting to start. +- **Running** — the agent is planning, gathering evidence, and validating findings. The card shows the current phase (planning, gathering context, testing explanations, reviewing evidence, writing the report) and the last few progress events. +- **Complete** — the report is ready. The card expands into the [report view](#report-view). +- **Partially complete** — the run hit a limit or a soft failure but produced a usable report from the evidence it did gather. +- **Cancelled** — you (or someone else on your team) stopped the run. The card shows sanitized recovery copy so you can retry with a new question. +- **Failed** — the run couldn't finish. The card explains what to try next without leaking internal errors. + +You can safely leave the thread while a run is in progress. State is polled from durable storage, so the card stays accurate across page reloads, other browsers, and other devices signed in to the same account. Reopening the thread restores whatever state the run has reached. + +### Cancelling a run + +While a run is queued or running, the card exposes a **Cancel** action. Cancellation is best-effort and asynchronous — the card moves to a "cancellation requested" state, then to **Cancelled** once the backend confirms. + +## Report view + +A completed (or partially complete) run expands into a linear report inside the agent workspace. The report has a stable structure so you know where to look: + +- **Executive answer** — the headline finding in a paragraph or two. +- **Findings** — the evidence-backed claims that support the answer, each with its own confidence badge (`low` / `medium` / `high`). The report's overall confidence is the lowest confidence across findings. +- **Alternatives and contradictions** — competing explanations the agent considered, and evidence that pushes against the executive answer. +- **Definitions and methodology** — the scope and approach the agent used: the metrics it relied on, how it framed the question, and any assumptions. +- **Limitations** — caveats about data coverage, freshness, or gaps in the semantic layer. +- **Next questions** — suggested follow-ups the agent couldn't resolve in this run. + +### Numbered evidence rail + +Every claim in the report is tagged with a numbered marker. Clicking a marker jumps to the matching entry on the **evidence rail**: + +- On desktop, the rail is anchored beside the report. +- On mobile, evidence opens in a bottom drawer. + +Each evidence entry links back to the source that supports the claim. Lightdash and warehouse evidence link to the exact query result, so you can rerun or inspect the query. Repository and document evidence link to the source file or page. Web evidence links to the fetched URL. Links are validated before they're rendered — only `https://` sources and internal Lightdash paths are shown, so the rail is safe to click through. + +## Follow-up actions + +From a completed run card, you can: + +- **Challenge** — push the agent to reconsider a finding you think is wrong. +- **Rerun deeper** — resubmit the same question at a higher depth tier. +- **Share** — send a link to the thread so a teammate can read the report. +- **View activity** — inspect the ordered timeline of what the agent did during the run. +- **Cancel** — available while a run is still in progress. + +Actions that don't have a backend-supported operation for the current run are hidden, so what you see on a card is what you can actually do with it. + +## Frequently asked questions + +**Can I use deep research on an existing thread?** +No. Deep research runs must be started from a new thread. This keeps the composer mode, the depth, and the run history tied to a single conversation. + +**Does deep research use my project's data access settings?** +Yes. Deep research honors the same [data access](/guides/ai-agents/data-access) rules as normal Ask mode, including dbt-tag scoping and any organization-level restrictions. + +**Do I have to keep the tab open?** +No. Runs execute server-side. You can close the tab, switch projects, or come back the next day — the run card in the thread will reflect the current state. + +**How does deep research relate to the Deep Research API?** +They share the same backend, effort tiers, and evidence model. Use the API when you want to trigger runs programmatically or fetch reports from another system; use the composer when a human is doing the investigation from within Lightdash. From d9c91a443adf41dc7e3a7bb0710a04e19cd94b31 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 18 Jul 2026 00:42:11 +0000 Subject: [PATCH 2/2] docs: update Deep Research guide for markdown report and chart snapshots --- guides/ai-agents/deep-research.mdx | 39 ++++++++++++++++++------------ 1 file changed, 23 insertions(+), 16 deletions(-) diff --git a/guides/ai-agents/deep-research.mdx b/guides/ai-agents/deep-research.mdx index a2ac1352..952a7892 100644 --- a/guides/ai-agents/deep-research.mdx +++ b/guides/ai-agents/deep-research.mdx @@ -1,14 +1,14 @@ --- title: "Deep research" sidebarTitle: "Deep research" -description: "Ask an AI agent a high-stakes question and get back an evidence-backed report — with sources, findings, methodology, and limitations." +description: "Ask an AI agent a high-stakes question and get back an evidence-backed report — an authored narrative with confidence-tagged findings, callouts, and live charts inline." --- **Availability:** Deep research is a **Beta** feature available on **Enterprise** plans. It is gated by the `ai-deep-research` feature flag (the same flag used by the Deep Research API). Contact Lightdash to enable it for your organization. -Deep research is a mode of the AI agent composer for questions that need more than a single-turn answer. Instead of returning one chart or a short summary, the agent plans an investigation, gathers evidence from multiple sources, and writes a structured report with numbered citations you can trace back to the underlying queries and documents. +Deep research is a mode of the AI agent composer for questions that need more than a single-turn answer. Instead of returning one chart or a short summary, the agent plans an investigation, gathers evidence from multiple sources, and writes a report as a single markdown document — an authored narrative with confidence-tagged findings, callouts, and charts interleaved in the order the agent chose to present them. Deep research is the in-product counterpart to the Deep Research API — the same effort tiers and evidence model, exposed as a UI you can drive from an agent thread. @@ -58,7 +58,7 @@ The card walks through these states: - **Cancelled** — you (or someone else on your team) stopped the run. The card shows sanitized recovery copy so you can retry with a new question. - **Failed** — the run couldn't finish. The card explains what to try next without leaking internal errors. -You can safely leave the thread while a run is in progress. State is polled from durable storage, so the card stays accurate across page reloads, other browsers, and other devices signed in to the same account. Reopening the thread restores whatever state the run has reached. +Each run is persisted server-side and linked to the thread and the prompt that started it, so the run card is available to you on any browser or device — not just the one you started the run from. Reopening the thread restores whatever state the run has reached, and closing the tab while a run is in progress is safe: runs execute on the server, and the card updates by polling. ### Cancelling a run @@ -66,23 +66,27 @@ While a run is queued or running, the card exposes a **Cancel** action. Cancella ## Report view -A completed (or partially complete) run expands into a linear report inside the agent workspace. The report has a stable structure so you know where to look: +A completed (or partially complete) run expands into a single linear report inside the agent workspace. The agent authors the report as one markdown document, so prose, findings, callouts, and charts appear together in the order the agent chose — rather than being split into fixed panels. -- **Executive answer** — the headline finding in a paragraph or two. -- **Findings** — the evidence-backed claims that support the answer, each with its own confidence badge (`low` / `medium` / `high`). The report's overall confidence is the lowest confidence across findings. -- **Alternatives and contradictions** — competing explanations the agent considered, and evidence that pushes against the executive answer. -- **Definitions and methodology** — the scope and approach the agent used: the metrics it relied on, how it framed the question, and any assumptions. -- **Limitations** — caveats about data coverage, freshness, or gaps in the semantic layer. -- **Next questions** — suggested follow-ups the agent couldn't resolve in this run. +A typical report includes: -### Numbered evidence rail +- An **intro** framing the question and the scope of the investigation. +- One or more **finding sections**, each with a heading and a confidence badge (`low` / `medium` / `high`) that may carry a short inline caveat. +- **Callouts** for important context — notes, tips, information, and warnings — inline with the prose that references them. +- A **conclusion** with the headline answer and bullet-pointed next steps or unresolved questions. -Every claim in the report is tagged with a numbered marker. Clicking a marker jumps to the matching entry on the **evidence rail**: +The report's overall confidence is the lowest confidence across its findings, so a single low-confidence finding pulls the overall badge down to `low`. -- On desktop, the rail is anchored beside the report. -- On mobile, evidence opens in a bottom drawer. +### Charts inline with the narrative -Each evidence entry links back to the source that supports the claim. Lightdash and warehouse evidence link to the exact query result, so you can rerun or inspect the query. Repository and document evidence link to the source file or page. Web evidence links to the fetched URL. Links are validated before they're rendered — only `https://` sources and internal Lightdash paths are shown, so the rail is safe to click through. +Findings that need a chart embed it directly in the report where the prose calls it out — at most one chart per finding, so the surrounding text is always the narrative that explains it. + +Each chart is a **snapshot** taken when the report was published, so opening the report months later shows exactly the numbers the agent saw. The chart tile is labelled with the snapshot date, and every chart has a **View live data** toggle that re-executes the underlying query against your warehouse for a fresh view. + +- **Warehouse charts** come from a semantic-layer query the agent ran during the investigation. They show read-only applied-filter pills so you can see how the data was scoped, and support the live-data refresh. +- **Agent-computed charts** carry an **Agent-computed** badge. Their values are derived from analysis the agent performed during the run (for example, aggregations over data pulled from documents or the web) rather than from a single warehouse query, so the live-data refresh does not apply. + +If a chart in an older report can't be resolved — for example, because the underlying query is no longer available — the report leaves an inline note in place of the tile and the rest of the narrative renders normally. ## Follow-up actions @@ -105,7 +109,10 @@ No. Deep research runs must be started from a new thread. This keeps the compose Yes. Deep research honors the same [data access](/guides/ai-agents/data-access) rules as normal Ask mode, including dbt-tag scoping and any organization-level restrictions. **Do I have to keep the tab open?** -No. Runs execute server-side. You can close the tab, switch projects, or come back the next day — the run card in the thread will reflect the current state. +No. Runs execute server-side and are linked to the thread, so the run card and report are available from any browser or device you're signed in on, not just the one you started the run from. + +**Why do the charts in an older report show a snapshot instead of live data?** +Every chart in a report is snapshotted at publish time so the report is stable — reopening it later shows exactly the numbers the finding was based on. Use **View live data** on any warehouse chart to re-run the underlying query and see the current values. Agent-computed charts are marked with a badge and do not have a live view. **How does deep research relate to the Deep Research API?** They share the same backend, effort tiers, and evidence model. Use the API when you want to trigger runs programmatically or fetch reports from another system; use the composer when a human is doing the investigation from within Lightdash.