> 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/suites/space-and-assets-analytics/copilot-assistant/quick-start.md). # Quick Start ## Prerequisites * Access to the Space & Assets Analytics Suite with the Copilot Assistant Module enabled * Assets [configured](/collection/mandatory-base/assets.md) in the Portfolio - ideally with some data being ingested already ## Your First Query The Copilot Assistant Module page is the central place to start new conversations, continue previous conversations and to view and manage the conversation history.
### Starting a Conversation 1. In the top menubar, click on *AI Assist* **\[1]**.\ ▷ The Copilot Assistant welcome page opens. 2. In the welcome page, enter a prompt or choose one of the suggestions below to start a new conversation **\[2]** or continue a previous one from the conversation history on the left. 3. If you are happy with your prompt click on the *Send Button* **\[3]**.\ ▷ The request is processed and intermediate progress updates will become visible. \ A good first query is something specific or simple: * *"How many assets are in my portfolio?"* * *"Show me all alarms with high priority."* * *"What are the current temperatures in buildings?"* * *"Could you show me the average weekly energy usage of the past 6 months for all buildings?"* ### Understanding the Tool Calling Trace As the Assistant processes your request it will perform Tool Calls to match your request to your asset structure and invoke subagents to retrieve concrete data from the database or generate visualisations.\ The tool call trace shows exactly how the agent interpreted and processed your request. Examining it is the fastest way to understand why a response looks the way it does and where to rephrase if it does not match your intent. > **Example:** Processing the query *"Show me the average weekly energy usage of the past 6 months for all buildings"*
In this case the Assistant called **4 Tools** and invoked **2 subagents**: 1. Resolving the location concept *'buildings'* from the request under **\[E1]**.\ ◈ It found a matching [AssetType](/collection/getting-started/2.-setting-up-assets/asset-modeling.md) *Building*\ ◈ It examined several assets with that AssetType (e.g. several SmartOffice Buildings) 2. Resolving the measurement concept *'energy usage'* **\[E2]**.\ ◈ It uses the previously retrieved AssetType Building as a condition and only examines entities within those buildings\ ◈ As the request aims to analyse incoming data, only [asset measurements](/collection/mandatory-base/platform-core/asset-core/create-a-new-template.md) with the subtype input are considered\ ◈ The request specifies a time range of the past 6 months, thus only assets which actively recorded data in that time range are retrieved\ ◈ Several asset types which measure energy usage and have asset instances that were active in the past 6 months were detected\ ◈ Results are shown as AssetType.attribute and also display the AttributeType and unit if any 3. Once the Assistant has determined the Asset Scope it invokes the specialized SQL Subagent to retrieve the corresponding data from the database **\[E3]**.\ ◈ The SQL Subagent was able to query and return 255 rows of data - of which the main Assistant will see a 10 row preview 4. The assistant inspects and analyses the result set deterministically **\[E4]**.\ ◈ It applied three operations on the whole database result to compute key results: *overall mean energy usage*, *lowest average energy usage*, *highest average energy usage* 5. It uses the computed metrics to create KPI cards that visualise these to the user **\[E5]** 6. The assistant decides that Charts are appropriate based on the returned data in addition to the user request and invokes the Visualisation Subagent **\[E6]**.\ ◈ The Visualisation Subagent determines to visualise the full 250 rows of data and not just a 10 row preview ◈ The Subagent created a line chart which will display the average weekly energy usage on the y-axis and the week on the x-axis. It also creates a series for each Building in the chart. ### **What to Expect** While each response includes a final textual response about what was retrieved and analysed it will also include several artifacts that show the underlying asset data and visualise the results.\ Once the Assistant processes your request it will make the result artifacts visible in the active Chat Window **\[A]** as they become available.
\ Each response can include:
MarkerComponentDescription
[E]Tool call traceA log of which steps the agent took (expandable)
[H]Data tableRaw query results
[I]KPI cards1-3 highlighted key numbers from the retrieved data
[K]ChartsAuto-generated when data suits visualization (can be expanded in a Dialog [J])
Once the Assistant finishes the turn you have several options to continue: 1. Starting a fresh conversation by creating a new chat **\[C]**.\ ▷ The initial Welcome Page will open. 2. Sending a follow-up Request **\[L] + \[M]**.\ ▷ A new turn is started - the Assistant still has the context of the previous turn. {% hint style="info" %} If the Conversation Stream was interrupted at any point the **Refresh Chat Button \[G]** can be used to fetch the latests updates without having to reload the page {% endhint %} ### Additional Configuration * The Copilot Assistant Settings will allow adjusting the Agent Behaviour **\[B]** * Detailed Information About the Conversation and the results of called Tools is available in the Agent Debug Sidepanel **\[F]** The Button above the Chat Window **\[D]** allows to switch the viewing mode. Once a conversation becomes longer it can get become harder to orient and navigate inside of it. Switching to Tabs mode allows to navigate faster between all of the requests inside of a conversation **\[D1]**.
## Tips before you start * If you already know the asset or metric, start specific. If you're exploring an unfamiliar portfolio, start broad and let the assistant and its suggested follow-ups guide you. * Mention asset names, locations or asset types to get more focused results * For historical data, always include a time range (e.g. *"last 7 days"*, *"past quarter"*) * Use the suggested follow-up prompts or your own, to drill down progressively --- # 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/suites/space-and-assets-analytics/copilot-assistant/quick-start.md?ask=&goal= ``` `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.