How the Analytics Agent works
Mitzu's Analytics Agent does not write SQL. The agent composes analysis specifications — the structured parameters of a funnel, retention, or segmentation analysis — against a semantic layer specialised for product analytics. A deterministic query engine turns each specification into SQL and your warehouse executes it. The same specification always produces the same SQL, and the same answer.
This page describes that architecture. For day-to-day usage — where to open the agent and what to ask — see the Analytics Agent page.
The division of labor
| The agent | The query engine |
|---|---|
| Interprets your question | Generates the SQL |
| Discovers the right events, properties, and dimensions in the data catalog | Applies product analytics methodology — conversion windows, cohort bucketing, deduplication |
| Assembles the analysis specification: events, filters, breakdowns, time windows | Executes deterministically: same specification, same SQL, same answer |
| Summarises and explains the results | Returns the generated SQL for inspection |
The specification for a funnel names the first event, the subsequent steps, the conversion window, and the breakdowns. The specification for retention names the cohort-defining event, the return event, and the time granularity. The specification for a segmentation names the event, filters, breakdown, and time window. The agent fills in these parameters; it never authors the query text.
Why the agent does not write SQL
Product analytics errors are usually methodology errors, not syntax errors: a funnel computed without a conversion window, a retention chart that does not bucket cohorts by time, a segmentation that counts the same user twice. A query can be syntactically valid and still methodologically wrong.
Mitzu removes that failure mode by taking SQL authorship away from the language model entirely. The query engine that turns specifications into SQL is the same deterministic code that powers the Insights page — methodology is implemented once, in the engine, and every query inherits it. The model cannot introduce a methodology error into SQL it never writes.
Every generated query remains inspectable: the Show SQL option displays the exact SQL the engine produced, and the Query Admin tab lists every query sent to your warehouse. The SQL is a verification artifact — it is there for your analysts to review, not the agent's authored output.
What the semantic layer expresses
The agent's vocabulary is the semantic layer that the Configuration Agent builds from your warehouse and indexing keeps populated:
- Events and event properties discovered from your event tables
- Entities — users and groups — and the dimension properties attached to them
- Sampled filter values, so filters are suggested from values that actually exist in your warehouse rather than invented
- Saved insights, dashboards, and cohorts, which the agent searches and reuses before creating anything new
This layer is shaped for product analytics rather than for BI. A metrics-and-dimensions semantic layer has no native representation of a funnel's step sequence and conversion window, a retention cohort and its return event, or a user journey. Mitzu's semantic layer and engine express these directly — the engine constructs funnel, retention, segmentation, and journey queries from specifications, deterministically. See data modeling for how the layer is structured.
What the agent can do
- Create and run segmentation, funnel, and retention insights, and present the results with charts and a summary — the four-step workflow is described in How the agent works
- Reuse saved insights that already answer your question, instead of creating duplicates
- Explore the data catalog — events, properties, existing insights — to answer discovery questions
- Create and update cohorts from a request
- Combine insight results into presentation-only custom charts — ratios, period-over-period diffs, overlays
- Hold multi-turn conversations, propose a reviewable plan in planning mode, and run on a schedule as a Scheduled Agent
What the agent cannot do
- It cannot write or run free-form SQL against your warehouse. Analyses outside the engine's methodology — arbitrary statistical modelling, custom SQL transformations — are out of its scope.
- It cannot see raw event rows. The model receives aggregated results and metadata; raw event data never leaves your warehouse for the model — see AI Data & Privacy.
- It cannot answer from data that is not in the semantic layer. The quality of its answers depends on the configured catalog — see getting better results.
The same architecture on every surface
The in-app agent, the Slack Agent, the MCP Server, and Scheduled Agents all share the same semantic layer and the same deterministic query engine. A question asked in Slack and the same question asked in the app produce the same specification, the same SQL, and the same answer.
All of it runs on Mitzu's warehouse-native architecture: the engine's queries execute inside your data warehouse, and event data is never copied out of it.