> 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/copilot-assistant/agent-modes/data-agent.md).
# Data Agent
Data retrieval, analysis, and visualization for assets and their data
The Data Agent is the current execution mode of Copilot Assistant. It is designed for data retrieval, analysis, and visualization on top of the smart building database.\
It processes natural-language requests about assets and their data, translates them into database queries, analyzes the results, and returns answers in a human-readable format with supporting visuals.
Every result is grounded in what is actually present in your project's asset model and live data. The agent does not infer, estimate, or fabricate data.
## How It Works
When you submit a request, the Data Agent follows a structured workflow:
1. **Understand the request:** identify concepts such as locations, asset types, measurements, and time ranges.
2. **Resolve the asset scope:** map those concepts to real database entities (specific assets, asset types, attributes) using the asset hierarchy and available data.
3. **Retrieve data:** use the dedicated SQL Subagent to generate and execute a query. The SQL generation can be refined and re-executed when the result needs further clarification.
4. [**Analyze results**](#result-analysis)**:** inspect the complete result set and compute aggregations, rankings, comparisons, or data-quality measures deterministically.
5. [**Present results**](#visualization)**:** return key results as text, tables, KPI cards, charts, and suggested follow-up directions.
This workflow is transparent: the [**tool call trace**](/collection/copilot-assistant/quick-start.md#understanding-the-tool-calling-trace) included in each response shows exactly which steps the agent took and what it found
## Tools & Capabilities
The Data Agent uses a set of specialized internal tools, each responsible for a distinct step of the workflow. Understanding them helps you know what the agent can and cannot do
### Asset & Location Resolution
Before querying any data, the agent resolves the concepts in your request into concrete database entities. This includes:
* Finding assets by name, type, location, or tag
* Traversing the asset hierarchy (e.g. all assets located under Building A → Floor 3 → Room 302)
* Resolving measurement concepts to actual sensor assets/asset types that track the corresponding data (e.g. *"energy usage"* → attribute energy on assets of type EMeter, input readings, unit: kWh)
The agent resolves scope iteratively. If multiple plausible interpretations remain after automatic refinement, it asks for clarification with concrete options
### SQL Subagent
Once the asset scope is resolved, the SQL Subagent generates and executes SQL against the smart building database. It is currently capable of querying four data domains:
| Domain | Description |
| --------------------------- | ---------------------------------------------------- |
| **Asset configuration** | Structure, types, counts, groupings, and identifiers |
| **Current data (Heap)** | Latest asset data |
| **Historical data (Trend)** | Time-series data with bucketing, aggregation |
| **Alarms** | Current & Historical Alarms on Assets |
The assistant will interact with the database through this specialized subagent for you, based on your requests and the assets in your project. This approach is often described as [NL2SQL](/collection/academy/building-intelligence-ai-and-machine-learning-in-buildingpro-suites/agents/nl2sql.md), meaning natural language is translated into controlled data queries behind the scenes. Users do not need SQL skills to explore portfolio and building data.
#### Asset Structure
Query the configuration and organization of assets in a portfolio.
> *Use for: counting assets, listing assets by type or location, retrieving identifiers and configurations.*
Examples:
* *How many assets are there in total?*
* *How many assets are located in Location X?*
* *Give me the asset IDs and GAI of all assets where their names start with 'Virtual'.*
* *Count all assets and group them by asset type.*
#### Current Asset Data (Heap)
Retrieve the latest recorded values for assets.
> *Use for: real-time overviews, live status checks, current comparisons between assets.*
Examples:
* *What are the current temperatures in the building?*
* *Show me the newest data of asset ABC.*
* *Which temperature recording assets deviate from their setpoint?*
* *What is the current occupancy in the meeting rooms?*
* *Retrieve the power consumption of all sockets with asset type SmartSocket.*
* *Get me the average temperatures on the first floor.*
* *How many occupants are currently in the building, and which floors are the most populated?*
* *Which sensors are showing a temperature above 20?*
#### Historical Asset Data (Trend)
Query the historic (time-series) data of assets with flexible time ranges and aggregations.
> *Use for: trend analysis, period comparisons, energy reporting.*
Examples:
* *How much energy did building B2F consume in the past quarter?*
* *Retrieve the historical water usage between 1st January and 31st December, categorized by floor.*
* *Compare CO2 levels in the meeting rooms during morning and afternoon hours.*
* *What are the top three assets consuming the most energy during off-hours?*
* *Calculate the energy consumption of room 202 for the last quarter and compare it with the same period last year.*
* *Check the average energy consumption of assets in room 101 during the last week and compare it with current consumption.*
#### Alarms
Query alarm rules and alarm event history associated with assets.
> *Use for: incident investigation, alarm coverage audits, reviewing active issues.*
Examples:
* *Identify devices that have been malfunctioning since last Tuesday in the east wing.*
* *Show me all alarms with a high priority.*
* *Identify all alarm rules for the break room.*
### Result Analysis
After raw data is retrieved, the agent applies deterministic analysis on the result set to surface insights beyond the raw rows:
* **Aggregations** - average, sum, min, max, ... across the result set
* **Rankings** - top and bottom N items by any metric
* **Deviations** - comparison of each item against the group average, mediana or baseline
* **Period-over-period comparisons** (e.g. this quarter vs. last quarter)
* **Data quality profiling** (null values, inactive sensors, coverage gaps)
### Visualisation
When the data suits it, the agent generates:
* **KPI summary cards**: 1-3 highlighted key results
* **Charts**: Line, Bar, Pie, Heatmap
Chart types are selected automatically based on the structure and content of the returned data. \
You can influence the output by explicitly requesting a chart type (e.g. *"show this as a bar chart"*) or a specific axis arrangement.
## Best suited for
requests related to retrieving & analyzing asset data
* Ad-hoc questions with a defined metric, location, or time range
* Exploring asset configuration and data availability across a portfolio
* Drill down from higher-level KPIs to more detailed asset views \
(e.g. Drilling down from site or building level to floor and room or even individual asset level)
* Comparing asset performance across locations or time periods
## Less suited for
* Very broad strategy questions without defined KPIs
* Business-impact ranking questions that require interpretation beyond the available data model
* Highly ambiguous prompts with no clear metric, scope, or time range
---
# 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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.buildings.ability.abb/collection/copilot-assistant/agent-modes/data-agent.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.