From 6838087f60eaa9dd904a86f5f93a7328810bcdcd Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 18 May 2026 09:06:38 +0000
Subject: [PATCH] docs: document SQL mode for AI agents

---
 guides/ai-agents/using-ai-agents.mdx | 33 ++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/guides/ai-agents/using-ai-agents.mdx b/guides/ai-agents/using-ai-agents.mdx
index 525ad7a5..df4089db 100644
--- a/guides/ai-agents/using-ai-agents.mdx
+++ b/guides/ai-agents/using-ai-agents.mdx
@@ -20,6 +20,39 @@ As mentioned earlier, Lightdash agents use the **semantic layer** defined in you
 This ensures that the AI generates accurate queries and visualizations based on your specific data context.
 So, *when an Agent generates an answer, the output is a semantic query, **not SQL!*** This means that you can easily swap between the conversational AI interface and the standard Lightdash exploration experience.
 
+## SQL mode
+
+SQL mode lets the agent reach for raw SQL when a question can't be answered from the semantic layer alone — for example, when the data exists in your warehouse but hasn't been modeled as an explore yet. With SQL mode on, the agent can list warehouse tables, describe their columns, and run SQL queries against your warehouse.
+
+SQL mode is **off by default** on every new thread. You opt in per conversation using the **SQL mode** toggle below the message input.
+
+### When to use it
+
+- The data you need lives in a warehouse table that isn't part of an explore.
+- You want a one-off lookup, audit, or shape-of-the-data check before modeling it.
+- The agent has already told you it can't answer from the semantic layer.
+
+Prefer the default (semantic) mode for anything that *can* be answered from your modeled explores — answers stay governed by your dbt metrics, joins, and row-level filters.
+
+### Who can use it
+
+The SQL mode toggle is visible only to users who hold the **`manage:SqlRunner`** ability — the same permission required to use the [SQL Runner](/guides/developer/sql-runner) page. If you don't see the toggle, ask a workspace admin to grant SQL Runner access to your role.
+
+### How approvals work
+
+SQL mode is gated by a human-in-the-loop check on every query:
+
+1. You flip **SQL mode** on for the thread.
+2. You ask a question. The agent drafts a SQL query.
+3. Lightdash shows the proposed SQL inline and waits for you to **Approve** or **Reject** before anything runs against your warehouse.
+4. Approved queries return results to the agent, which then summarizes or visualizes them.
+
+Each SQL call is approved individually — there is no \"approve all\" shortcut, and approvals don't carry over between threads.
+
+### SQL mode in Slack
+
+Slack-triggered prompts can only use SQL mode when your organization has the **\"Require Slack users to authenticate with Lightdash\"** setting (`aiRequireOAuth`) turned on. Without it, Slack messages run under a shared workspace-default identity, so SQL execution is disabled fail-closed regardless of the toggle. See [Slack AI bot setup](/guides/ai-agents/getting-started) for how to configure OAuth.
+
 ## Asking about a chart or dashboard
 
 You can launch an AI conversation with a chart or dashboard pre-loaded as context. From the resource's `⋯` menu, click **Ask AI Agent**.