Building an AI agent on top of your data

The promise is simple to state and powerful to experience: a business person asks "which channel brought in the most revenue this month" and gets the answer, with the number and context, without writing a line of SQL and without waiting in the analyst's queue. That is an agent on top of your data. It is not magic, it is architecture: when the right pieces are in place, the agent reads your data, understands the question and answers. This guide shows what those pieces are and how they fit together.

The four ingredients

A trustworthy agent comes from combining four things. And one of them matters more than the others: context. Without context the agent guesses what the data means and gets it wrong; with good context it understands what each column means and gets it right, even when reading simpler tables. The other three provide the support: accessible data to read, MCP to reach it and an AI client to talk to.

The fourth ingredient is the AI client (for example Claude), the interface where the person asks the question in plain language. It talks to the MCP, which in turn reads your data backed by the Semantic Layer. Notice the role of each one: the Semantic Layer is the manual that explains the data, the MCP is the plumbing and the AI client is the tap. A well-modeled Gold layer helps and tends to improve the result, but it is not a prerequisite. Many people build agents that query the rawest data directly and it works well, as long as the context is there to explain what each thing means.

The path from question to answer

Every natural-language question follows the same path. Here is the whole flow at once.

In text, the route is: a natural-language question reaches the agent (via MCP), which reads your data backed by the Semantic Layer to understand which tables to use and what each field means, builds the query, and returns the answer. A well-modeled Gold table makes this step easier, but what actually keeps it from guessing is the context: instead of guessing that "revenue" is the vl column, it reads in the context document that revenue is valor_liquido summed after approval. Without this context, not even cleaned-up tables can save the answer.

What makes it right, what makes it wrong

The difference between an agent you trust and one that spits out wrong numbers lies almost entirely in the context it receives, more than in the layer where the data lives. The same principle applies to both sides below.

This contrast is easier to see when the Gold layer and the context are evaluated together. The context document guide teaches you how to write the context that makes the agent get it right.

Questions a good agent answers

When the four ingredients are in place, questions like these come back with an answer and a number, right in the chat, without going through the analyst:

• "Which channel brought in the most revenue this month?" sums revenue by channel in the Gold table and sorts it.
• “How many new customers did we close in the last 4 weeks?” filters by conversion date and counts distinct customers.
• "Which product had the most returns this quarter?" joins sales and returns already consolidated in Gold.
• "How does the average order value compare to last month?" calculates the average and compares the two periods.
• "Which customers haven't bought in more than 60 days?" lists those past the recency threshold.

Notice that these are all business questions, not technical ones. The person does not need to know the table name or the right column. That knowledge lives in the Semantic Layer, and it is the agent that uses it.