Skip to content

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 5 peeks and "is this column a code?" checks. With metrics there is nothing to probe, and a rejected name comes back with candidates instead 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_metrics exposes each metric's name and description. It does not yet project the Apache Ossie model's ai_context synonyms, 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.yaml as reviewed code, and run dosi validate in CI.

Where to next

  • The Dosi plugin


    Install it in Claude Code, Codex, DeepSeek Harness or another agent.

  • Quickstart


    From an empty folder to answers on 200,000 orders, in about ten minutes.

  • Run the MCP server yourself


    For any MCP client: start the server, register it, and set what the agent may do.