Using Dosi in your agents¶
An AI agent that answers data questions has two options. It can read your warehouse schema and write SQL itself, the usual "NL2SQL" setup, or it can call a semantic layer that already knows what a metric means. Dosi gives agents the second option: they discover your metrics, compile them to warehouse SQL, and run them.
Two ways in¶
| The Dosi plugin | The MCP server yourself | |
|---|---|---|
| For | Claude Code, Codex, DeepSeek Harness; the skills for other agents | any MCP client |
| What you get | dosi installed for you, skills that connect, build the model and answer, dosi's MCP tools, and hooks that keep passwords out of the conversation | dosi's MCP tools |
| Setup | one install | install dosi, start the server, register it, add prompt rules |
Start with the plugin if your agent has one: the quickstart installs it with one sentence, then connects a sample database, builds a model and asks questions, in under ten minutes.
What the agent gets¶
Tools in five groups, all speaking the same query shape the CLI and REST API use:
| Stage | Tools | What the agent learns or does |
|---|---|---|
| Discover | list_metrics, list_dimensions, list_datasets, describe_metric, describe_dataset, list_connections |
which metrics exist, how each is computed, which fields they can be broken down by and what those fields mean |
| Preview | compile_sql, explain_query, compile_select, explain_select (listed on request) |
the exact SQL or plan, before anything runs |
| Execute | run_query, select, attribute_metrics, attribute_dimensions |
metric results, lists of records, and why a metric changed: over its formula, then by groups |
| Author | validate_model |
whether a model edit is valid, in the server's engine mode |
| Ontology | describe, paths |
business concepts and the paths between them, when an ontology is loaded |
The vocabulary is small and closed: metrics are named, and group_by fields
are dataset.field (plus the reserved metric_time). An agent that stays
inside it cannot invent a column, and cannot quietly pick the wrong table.
Every tool is described in the MCP reference.
Why this beats raw-schema NL2SQL¶
The argument is not that models write bad SQL. It is that the correct SQL
for a business question is not derivable from column names. Someone has to
encode it once — that is what a semantic model is. Four things follow, all of
them visible in the bundled orders example.
It settles definitions instead of guessing them¶
revenue in the orders model is SUM(orders.amount) over all orders —
cancelled ones included. Ask an agent with only table access for "total
revenue" and it will usually add WHERE status = 'completed', because that is
the reasonable guess. Reasonable, and a different number: 350 instead of
450. Neither is wrong as SQL; only one matches what your company calls revenue.
Through the metric, every agent, dashboard, and notebook gets the same answer,
and the definition is reviewable in YAML instead of re-invented per question.
It does not double-count across tables¶
total_margin is defined as SUM(orders.amount) - SUM(products.unit_cost) —
an expression over two aggregates on two datasets. Dosi compiles it by
aggregating each side before combining them:
WITH m0 AS (SELECT SUM(orders.amount) AS orders_amount_sum FROM orders AS orders),
m1 AS (SELECT SUM(products.unit_cost) AS products_unit_cost_sum FROM products AS products)
SELECT m0.orders_amount_sum - m1.products_unit_cost_sum AS total_margin
FROM m0 CROSS JOIN m1
which answers 360. The natural hand-written version — join orders to
products, then SUM(o.amount - p.unit_cost) — answers 270, because the
join repeats each product row once per order and inflates the cost side. This
is the never-silently-double-counts guarantee
doing its job: fan-out is a property of the join graph, not something an agent
can see in a schema dump.
It gets grain and de-duplication right¶
unique_customers is COUNT(DISTINCT orders.customer_id). Broken down by
month on the sample data that is 1 / 2 / 1; a plain COUNT(customer_id) gives
2 / 3 / 1. The distinction lives in the metric definition, so the agent does
not have to rediscover it — or fail to.
It ports across warehouses for free¶
The same request compiles to whatever the target dialect actually supports:
DuckDB gets DATE_TRUNC('MONTH', …), MySQL — which has no DATE_TRUNC — gets
STR_TO_DATE(DATE_FORMAT(…, '%Y-%m-01'), '%Y-%m-%d'). An agent writing SQL by
hand has to know each warehouse's date idioms; an agent calling compile_sql
just changes dialect.
What it costs¶
Accuracy is the reason to do this. Cost is more nuanced than the usual pitch, so here is what we actually measure rather than what is convenient to claim.
Two things genuinely get cheaper:
- Compilation is Rust, not tokens. Planning the join graph and rendering dialect SQL takes about a millisecond, outside the model — measured, and deterministic.
- The agent stops probing the data. A raw-SQL agent spends turns on
SELECT DISTINCT status,LIMIT 5peeks and "is this column a code?" checks. With metrics there is nothing to probe, and a rejected name comes back withcandidatesinstead of starting a debugging loop.
One thing does not, and it is worth knowing before you plan a budget: on a small schema the MCP path uses more model context, not less. The tool definitions, including the full metric-query shape, are a fixed cost paid every call, and on our three-table example fixture that outweighs the entire schema dump the baseline gets for free. In our own runs the semantic-layer arm took more turns and more context than the raw-SQL arm on that fixture.
The trade flips as the warehouse grows: the tool surface stays the same size while a schema dump grows with every column, and probe turns grow with every ambiguous code column. Treat "cheaper" as a property of your schema size, and measure it on your own questions.
What it does not fix¶
Being straight about the limits, because they decide whether this fits you:
- Word-to-metric mapping is still the agent's job.
list_metricsexposes each metric's name and description. It does not yet project the Apache Ossie model'sai_contextsynonyms, so a question phrased in vocabulary that appears nowhere in a name or description can still miss. - Questions no metric covers cannot be answered through these tools. That is deliberate — a refusal beats a confident wrong number — but it means the model's coverage is your coverage. Keep raw SQL available for exploration.
- A wrong definition is now wrong everywhere. Centralizing the definition
centralizes the blast radius; treat
model.yamlas reviewed code, and rundosi validatein CI.
Where to next¶
-
Install it in Claude Code, Codex, DeepSeek Harness or another agent.
-
From an empty folder to answers on 200,000 orders, in about ten minutes.
-
For any MCP client: start the server, register it, and set what the agent may do.