8 design principles for building the agentic analytics harness
A year of building Cube’s analytics agent on top of our open-source semantic layer, written down. Each principle states the constraint, then shows how we implement it in Cube — including the tradeoffs, the production failures, and the questions we haven’t resolved.
Eight principles, each one a constraint we hit in production. The principle states the constraint; the section that follows shows how we implement it in Cube.
1 — Context as a budget
Past a certain size, additional context makes the model less reliable at retrieving information already in its window.
2 — Durable artifacts
A later run starts without prior session state unless the earlier run stored it in a durable artifact.
3 — Tool design
A tool’s description and the shape of what it returns are the only parts of it the model ever sees. Both are prompt.
4 — Executable context
Catalogs, glossaries, and lineage cannot enforce authorization on SQL sent directly to the warehouse.
5 — Query expressiveness
Agents need an expressive query language for calculations over semantic-layer definitions, with execution pushed down to the compute layer.
6 — Model search
Preloading the data model consumes context with members the current user may not be allowed to query.
7 — Business context, query corpus, and memory
A governed data model does not capture every company-specific rule, reusable query, or correction the agent needs.
8 — User context
Authorization alone does not tell the agent which valid metric definition fits the person asking.
Written for the people building it
The harness is the system that decides what the model sees, which tools it can call, what persists between runs, how outputs are checked, and which actions are allowed. Most of that reasoning generalizes across domains. Its implementation rarely does — an analytics agent has to work through a governed semantic model, compose calculations without leaving the query path, and enforce caller permissions deterministically.
21 pages, free. One email address the first time, and the PDF downloads straight from cube.dev.
Get the guide
Read how Cube builds the agentic analytics harness on top of a semantic layer.