> For the complete documentation index, see [llms.txt](https://docs.buildings.ability.abb/collection/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildings.ability.abb/collection/academy/building-intelligence-ai-and-machine-learning-in-buildingpro-suites/agents/nl2sql/agentic-nl2sql.md).

# Agentic NL2SQL

The limitations described [previously](/collection/academy/building-intelligence-ai-and-machine-learning-in-buildingpro-suites/agents/nl2sql/why-nl2sql-is-hard.md) motivate an **agentic approach** to NL2SQL: rather than treating natural-language-to-SQL as a single-step translation problem, it is decomposed into a multi-step workflow where different components handle different aspects of the task.

## Why a Subagent Architecture

In an agentic NL2SQL system, the SQL generation step is isolated into a dedicated **subagent**. This subagent receives a fully scoped, unambiguous request and generates SQL for it. It does not handle:

* Interpreting what the user meant by "the building"
* Resolving which asset types measure "energy"
* Deciding whether to query current or historical data
* Recovering from wrong results or asking for clarification

Those responsibilities belong to the **orchestrating agent**, which uses specialized tools to resolve concepts against the live data model before delegating to the SQL subagent.

This separation has several advantages:

* **Focused training**: the SQL subagent can be optimized purely for SQL generation quality on a known schema, without needing to handle conversation, ambiguity, or error recovery.
* **Stateless execution**: the SQL subagent operates statelessly - it receives a request, generates and executes a query, and returns results. No conversational memory, no multi-turn reasoning.
* **Independent evolution**: the SQL model can be retrained or swapped without changing the orchestrator. The orchestrator's prompt can be updated without retraining the SQL model.

### Concept Resolution as a Semantic Layer

The critical insight behind agentic NL2SQL is that the gap between a user's question and a correct SQL query is not primarily a *language-to-SQL translation* gap. It is a **concept resolution** gap.

Consider the question: *"What is the energy consumption in Building A?"*

To generate correct SQL, the system needs to know:

* Which database entity represents "Building A" (e.g. the concrete asset representing it)
* Which asset types under Building A record energy data (e.g. meters, submeters)
* What attribute name and type correspond to "energy consumption" in the schema (e.g. attribute "energy", attribute\_type "energy", subtype "input")
* Whether "energy consumption" refers to current data (heap table) or historical data (trend table), which depends on whether the user is asking about "now" or a time period
* What unit the data is stored in

The orchestrating agent uses specialized **resolution tools** to bridge this gap before any SQL is generated.

#### [Two Types of Ambiguity](/collection/academy/building-intelligence-ai-and-machine-learning-in-buildingpro-suites/agents/nl2sql/why-nl2sql-is-hard.md#two-types-of-ambiguity) Revisited

The [previous chapter](/collection/academy/building-intelligence-ai-and-machine-learning-in-buildingpro-suites/agents/nl2sql/why-nl2sql-is-hard.md) introduced query ambiguity and data ambiguity. The agentic approach handles them at different stages:

**Query ambiguity** is resolved by the orchestrating agent through tool-based concept resolution and, when necessary, user clarification. So there is no need to guess.

**Data ambiguity** is surfaced by the resolution tools and resolved through hierarchy inspection, data availability checks, and scope refinement. When multiple valid interpretations remain after automatic resolution, the agent presents concrete options with names and identifiers so the user can choose precisely.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.buildings.ability.abb/collection/academy/building-intelligence-ai-and-machine-learning-in-buildingpro-suites/agents/nl2sql/agentic-nl2sql.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.