Self-Service Analytics with Claude: The Architecture

Every analytics team eventually drowns in the same request: "Can you just pull this number for me?" The questions are simple, the answers are buried in a warehouse, and a human analyst becomes a slow, expensive translation layer between business people and SQL. Self-service analytics promises to remove that bottleneck — but the dashboard-builder era proved that handing non-technical users a pile of charts mostly produces confusion. A Claude-powered analytics agent is a different bet: instead of pre-building every view, you let a model translate plain English into governed queries, run them, and explain the result. This post walks the full architecture end to end, the way a senior engineer would draw it on a whiteboard before writing a line of code.

What a self-service analytics agent actually is

A self-service data analytics agent is a system that lets a non-technical user ask a question in natural language and receive a trustworthy, query-backed answer — by having an LLM plan the analysis, generate and execute read-only queries against a governed data layer, and narrate the result with its supporting evidence. The key word is governed: the agent never gets a blank check against your production database. It operates inside a tightly scoped contract of tables, columns, joins, and row-level rules that you define up front.

Claude sits at the center of this system as a planner and composer, not as a database. It reads the user's intent, decides which tools to call, and assembles the final explanation. The actual data work — schema lookup, query execution, aggregation — happens in deterministic tools that you control. That separation is the single most important architectural decision: the model is creative and fuzzy; the data path is exact and auditable. When you keep those concerns apart, you get an agent that is both flexible and trustworthy.

The five layers, end to end

I think of the architecture as five layers stacked between the user and the warehouse. The interaction layer captures the question and any conversational context. The reasoning layer is Claude, which interprets intent and plans tool calls. The tool layer exposes capabilities — schema introspection, query validation, execution, and chart rendering — typically as MCP servers or SDK tools. The governance layer enforces what is allowed: read-only access, allow-listed tables, row-level security, and cost ceilings. The data layer is the warehouse or semantic model itself. A request flows down through these layers and the answer flows back up, gathering evidence as it goes.

flowchart TD
  A["Business user question"] --> B["Claude: interpret intent & plan"]
  B --> C{"Schema known?"}
  C -->|No| D["Call schema tool: tables & columns"]
  D --> B
  C -->|Yes| E["Generate read-only SQL"]
  E --> F["Governance gate: validate & cost-check"]
  F -->|Rejected| G["Claude repairs query"]
  G --> F
  F -->|Approved| H["Execute against warehouse"]
  H --> I["Claude narrates result & cites SQL"]

Notice the two loops in that diagram. The first lets Claude fetch schema on demand instead of cramming your entire data dictionary into context. The second lets the governance gate bounce a bad query back for repair rather than failing outright. Those loops are where a robust agent earns its keep; a naive single-shot pipeline has neither and breaks the moment a question touches an unfamiliar table.

Why the semantic layer matters more than the model

The biggest determinant of answer quality is not which Claude model you pick — it is the quality of the metadata you expose. Raw warehouse schemas are hostile to both humans and models: cryptic column names, ambiguous foreign keys, three columns that all look like "revenue" but mean different things. If you point Claude at raw DDL, it will guess, and confident wrong guesses are worse than no answer.

The fix is a semantic layer: a curated description of business entities, metric definitions, approved joins, and synonyms. "Active customer" means a specific filter; "net revenue" excludes refunds; "this quarter" maps to your fiscal calendar. When Claude can read those definitions as structured context, it stops guessing and starts composing. In practice, teams that invest a week in semantic definitions get dramatically better results than teams that throw a bigger context window at raw tables. The model is the easy part; the meaning is the hard part.

The reasoning loop: plan, query, verify, narrate

Inside the reasoning layer, a good agent runs a small loop rather than a single inference. First it plans — decomposing "how did the Northeast region trend last quarter versus the prior one?" into the metrics, dimensions, and time grains involved. Then it queries, often in two passes: a cheap schema or sample query to confirm assumptions, then the real aggregation. Then it verifies — sanity-checking row counts, nulls, and whether the numbers are plausible given known totals. Finally it narrates, turning rows into a sentence a VP can read while citing the exact SQL it ran.

This loop is what separates an analytics agent from a text-to-SQL toy. Text-to-SQL emits a query and walks away. An agent treats the query as a hypothesis, checks whether the result makes sense, and corrects course when it does not. With Claude you implement this through tool results feeding back into the conversation: each tool call returns structured data, and the model decides whether it has enough to answer or needs another step. The 1M-token context window helps here because intermediate results, schema fragments, and prior turns can all coexist without you constantly pruning.

Trust, audit, and the human escape hatch

Self-service only works if people believe the numbers. That belief is engineered, not assumed. Every answer the agent produces should carry its provenance: the exact SQL executed, the tables touched, the row count, and the time the query ran. Surfacing the SQL underneath a plain-English answer lets a skeptical analyst verify in seconds and turns the agent from a black box into a glass box. Logging every query also gives you an audit trail for compliance and a dataset for improving the semantic layer over time.

You also need an escape hatch. When the agent's confidence is low, when a question requires data outside the governed scope, or when the result looks anomalous, it should say so and offer to route to a human rather than fabricate. Designing for graceful handoff is not an admission of failure; it is what makes the system safe to deploy to hundreds of non-technical users without an analyst babysitting every query.

Frequently asked questions

Does Claude connect directly to my database?

No — and it should not. Claude generates query plans and SQL, but execution happens in a deterministic tool layer you control, behind a governance gate that enforces read-only access, allow-listed tables, and cost limits. The model never holds raw credentials.

How is this different from text-to-SQL?

Text-to-SQL is one step inside this architecture. A full agent adds schema discovery, a governance gate, a verification loop, and natural-language narration with cited evidence. That loop is what makes results trustworthy enough for self-service rather than a single fragile guess.

Will it hallucinate numbers?

The risk drops sharply when the model never invents data — it only narrates rows returned by real queries. Hallucination of interpretation can still happen, which is why citing the SQL and verifying row counts against known totals are core parts of the design rather than afterthoughts.

How big does the semantic layer need to be?

Start with the twenty or thirty questions people actually ask, then define the entities, metrics, and joins those questions require. A focused semantic layer covering real demand beats an exhaustive one nobody validated. Expand it as new question patterns appear in your logs.

Bringing agentic AI to your phone lines

The same governed, tool-using, verify-before-you-answer architecture powers CallSphere's voice and chat agents — assistants that answer every call and message, pull live data mid-conversation, and book work around the clock. See it live at callsphere.ai.