Agent mode

Some questions need looking around before one query can answer them: "who owns this tenant?", "why did signups drop last week?", "is status 3 cancelled or refunded?". Agent mode works through them in read-only steps and answers with the queries it ran.

#Start an investigation

• Switch the Ask box to Agent (or press ⌘⇧A, or type /agent), type your question and press ↵. With the box empty, it suggests a few questions to start with.
• The agent first shows a short plan. Change any line, then press Go.
• Auto mode: click Ask first next to the model name to switch to Auto, or press Go, and don't ask again on a plan. In Auto the agent doesn't stop for the plan or before each send; it still asks when a question has two meanings, and what it may see stays as the connection's setting. It applies to every tab until you switch it back.
• Each step appears as it runs, with its SQL, row count and time. Click a step to see its rows in Results. Stop ends the run and the running query on the server.
• When a question has two reasonable meanings, the agent asks you with choices instead of guessing.

#The answer

• Each sentence links to the steps it rests on. SayQL checks every number in the answer against the steps' results; a number it can't find is marked not verified.
• The agent checks its joins: a join that repeats rows before they are summed is flagged, and the agent is told to fix it.
• It never changes data. If the answer is a change, it shows the statement marked not run, with Open in editor; the usual confirmation applies when you run it.
• Open as query, Save as script, Rerun (the same queries on fresh data, no AI) and Ask a follow-up work from the answer. To steer, open a step, choose Edit and continue, change its SQL, and the run continues from there.

#Database notes

At the end of a run the agent may suggest notes: facts about the database such as "the owner of a tenant is memberships.role = 'owner'". Save the ones you agree with. Notes show under Notes in the Database Navigator (right-click to edit or delete), and the Ask box, the agent and MCP apps all use them. A note can't hold values from your rows: one with an email, a number like a phone, or a masked value is refused.

#What the AI sees

Agent mode is off on every connection until you turn it on. The first /agent on a connection asks what it may see of query results there; change it later with Change under the Ask box, or by right-clicking the connection and choosing Agent settings.

• Ask before each send pauses on exactly what would go, with Send and Skip (Skip sends the row count only). It starts on for cloud providers.
• Never send columns are masked whatever the setting, and queries that use them are refused. MCP apps get the same treatment.
• Every step has a Sent to AI fold-out with the exact text that went to the model.
• Masking is best effort. Columns are masked by name (email, phone, name, address, birth, SSN, MRN, patient, token, password, notes and similar) and values by shape (emails, phone numbers, card numbers, ID-like strings). A name in a free-text column with an ordinary name can get through, so for health or production data keep results Off or at counts, or mark such columns never send.
• With Ollama or LM Studio, nothing leaves your computer.

#Safety and limits

Every agent query goes through the same read-only checks as the rest of SayQL, one statement at a time, and the database enforces read-only where it can. A query that would read all of a very large table without a filter is refused until the agent checks its plan. Each run has limits on steps, queries, time per query, time per run and tokens; change them in Settings → Agent mode, where you can also pick the model that runs the agent (by default your expert model). Connect with a read-only database login for production.

Something missing or unclear? Ask in Discussions.