A Seven-Layer Architecture for Production Data Agents

“Why did new-customer conversion fall this month?” sounds like a SQL question. It is not.

Before touching a warehouse, a useful Data Agent has to establish what new customer means, which conversion window applies, whether the metric changed recently, which data the requester is allowed to see, and what evidence would make an explanation credible. A query can run perfectly and still answer the wrong question.

Production Data Agents therefore need more than a language model and a database connector. They need a chain of responsibilities that turns ambiguous intent into a result another person can inspect. The seven-layer model below is a way to design that chain—and, when it breaks, to locate the failure.

Three planes, not a one-way pipeline

The seven layers are easier to understand as three overlapping planes:

• the data plane finds and interprets data, then performs work through controlled tools;
• the control plane constrains context, orchestration, permissions, cost, and consequential actions;
• the evaluation plane checks one answer and tracks quality across a portfolio of real tasks.

An analysis request will loop between planning, execution, and verification. Governance and observability must remain present on every pass. This is why “natural language to SQL” is only a narrow capability inside a much larger system.

1. Access and task entry

The entry point may be chat, a notebook, an embedded BI panel, an API, or a scheduled workflow. Its job is not merely to capture a prompt. It must collect the smallest useful task envelope: user identity, business scope, time range, desired output, and risk level.

For the conversion question, the interface should be able to ask whether a new customer is defined by registration or first purchase. It should know which regions the requester may access and make important assumptions easy to correct.

The characteristic failure here is fluent misalignment: the system confidently solves a nearby problem. Good interaction design makes clarification cheap and exposes assumptions before they become conclusions.

2. Semantics, ontology, and trusted context

A schema describes columns. A semantic layer describes the business. It should represent metrics, dimensions, entities, relationships, synonyms, approved join paths, owners, and versions.

“New-customer conversion,” for example, might mean users who complete a first purchase within fourteen days of their first eligible touch, divided by all eligible new users. Refund treatment, excluded channels, and the effective date of the definition matter as much as the formula itself.

Context retrieval must be selective. A metric question should pull the definition and lineage; an entity question may need ontology and access policy; a recurring analysis may benefit from a previously verified query. Stuffing every document and query into the prompt creates confident noise, especially when definitions are stale.

3. Planning and orchestration

Planning converts a goal into steps with dependencies and stopping rules. A defensible plan for the conversion question might first reproduce the headline metric, decompose the change by channel and region, inspect the affected funnel stages, check data freshness, and run an alternative calculation before drafting a conclusion.

The plan should expose budget, uncertainty, and failure conditions. If the sample is too small or an essential feed is delayed, the agent should stop or narrow its language. Filling a missing step with plausible prose is not graceful degradation.

A single tool-using agent, a planner–executor–verifier pattern, or a multi-agent system can all implement orchestration. Additional agents also create coordination and state-management costs. Clear plans, tool contracts, and verification gates usually matter more than role count.

4. Tools and controlled execution

SQL engines, Python sandboxes, catalogs, document retrieval, visualization components, and business APIs turn reasoning into evidence. Each tool needs a real contract: typed inputs and outputs, propagated identity, data scope, timeout, cost ceiling, idempotency, and observable failure modes.

Read-only access should be the default. Expensive scans, sensitive fields, and write operations need explicit policy or approval. Code should run in an isolated environment, with artifacts and logs retained long enough to reproduce the result.

This is the practical role of an Agent Harness. It connects model calls to context assembly, tool selection, policy checks, state, and memory. Models can be replaced; the accumulated contracts and controls around them are usually the harder part of the system.

5. Verification, reflection, and repair

A successful tool call is not a verified business result. Computation checks may include compilation, null and cardinality tests, time-range checks, reconciliation to trusted totals, and comparison with an alternative query. Claim checks ask whether each statement is supported, whether correlation is being presented as causation, and whether data quality justifies the wording.

When verification fails, the agent should repair the plan or execution. If channel totals do not reconcile with the overall metric, it should inspect overlap and join expansion. Asking the model to rephrase the conclusion will not fix the numbers.

6. Governance, security, and observability

Governance is a runtime property, not a final approval screen. User identity must propagate into semantic objects, data sources, and execution tools. Masking, row- and column-level access, purpose restrictions, and retention rules need to remain effective throughout the task.

Observability should record which metric version and context were used, what plan was created, which tools ran, how much they cost, where a human intervened, and what was ultimately delivered. Without that trace, “the answer was wrong” is not actionable: the cause may be retrieval, semantics, data freshness, a tool contract, or model judgment.

Consequential actions also need human control. Sending an external report, changing production data, or triggering a business policy should require evidence-aware approval proportional to the impact—not a context-free confirmation dialog.

7. Delivery and continuous learning

A useful deliverable includes the conclusion, supporting evidence, metric definition, relevant time window, limitations, and a path to reproduce or explore the result. The right form may be an executive brief with drill-down charts, a reproducible notebook, or structured output consumed by another workflow.

Feedback after delivery should improve governed assets rather than create an indiscriminate memory dump. Confirmed mappings can become semantic candidates; rejected plans should enter the failure set; valuable workflows should become Golden Tasks that are rerun when models, prompts, semantics, or tools change.

A review that exposes whether the architecture is real

Ask the team to run one representative request end to end and show the evidence behind each layer:

If a checkpoint exists only in the presenter’s explanation, it is not yet a system capability. That is the practical value of the seven-layer model: it turns “the agent can answer” into a set of components that can be owned, tested, and improved.