AI Reports and AI Assistant – User Guide

What this guide covers. How to get answers and reports about your contact center just by typing a question in plain English, and how administrators set this up. No SQL or technical knowledge is needed to use AI Reports or the AI Assistant.

Quick start: see it in 30 seconds

Short on time? These two clips show the whole idea. The rest of this guide explains each part in detail.

Build a report by typing what you want

In Insights → AI Reports, type the report in plain words, click Generate report, and the AI builds it from live data with highlights, a chart and a table.

ai-reports-quickstart.gif


Ask the AI Assistant a question

In Insights → AI Assistant, ask a question as you would ask a colleague. You get a short answer, a chart, and suggested follow-up questions.

ai-assistant-chat.gif


1. What is it?

Agent Desk includes two AI tools that read your contact-center reporting data (queues, agents, conversations, wrap-ups, campaigns and so on) and turn a plain-language question into real numbers, tables and charts.

Tool

What it is for

Think of it as…

AI Reports

Building a report you can look at, export to Excel and save to rerun later on fresh data.

A report builder where you describe the report instead of designing it.

AI Assistant

Asking quick questions in a chat and getting a short written answer with a chart, then asking follow-up questions.

A colleague who knows the reporting database and answers in plain words.

Behind the scenes, the AI reads your question, works out which data it needs, writes a database query, checks it and runs it on the live reporting database. It can only read data. It can never change or delete anything.

Who can use it

Who

What they see

Supervisors and administrators

Insights → AI Reports and Insights → AI Assistant

Administrators (users who can manage Agent Desk settings)

Also Administration → AI settings, Reporting databases and AI agent access

If you don't see these menu items, either your user doesn't have the right role, or the AI Reports service hasn't been connected to Agent Desk yet. Ask your administrator.

The AI tools in the side menu
The AI tools in the side menu: AI Reports and AI Assistant under Insights; AI settings, AI agent access and Reporting databases under Administration.

2. First-time setup (administrators)

Before anyone can use AI Reports, an administrator does these steps once, in this order:

  1. Choose the AI model: Administration → AI settings. Pick the AI provider, model and key. See section 6.

  2. Add the reporting databases: Administration → Reporting databases. Tell the AI where your reporting data lives. See section 7.

  3. Try it: open Insights → AI Reports and run one of the templates.

  4. Optional, give AI agents access: Administration → AI agent access. Create a token so a person can use AI Reports from tools like Claude Code, Codex or Cursor. See section 8.

3. AI Reports: build a report by describing it

Open Insights → AI Reports. The screen has two parts:

  • Left: the report list. New report, a search box, your team's Saved reports and ready-made Templates. You can fold this list into a thin bar to give the report more room.

  • Right: the report. At the top is the box where you describe the report; below it the result appears.

AI Reports start screen
AI Reports: saved reports and templates on the left, the description box with the period picker on the right, and one-click template suggestions under it.

Step 1: Describe the report

Type what you want to see in your own words. Say what to measure and what to group it by. For example:

  • Answered and abandoned chats per queue, with the abandon rate and average wait time

  • For each agent: completed tasks, average handle time in minutes, and transfers

  • Number of conversations per day split into agent-handled, bot-handled and abandoned

You can also click the microphone to dictate, or add files and images (for example a screenshot of an old report to rebuild, or an Excel list of agents to report on).

Step 2: Pick the period and the database

  • Report period: Today, Yesterday, Last 7 days, Last 30 days, This month, Last month, This year, All time, a Custom range, or As described (use whatever period you wrote in the description).

  • Databases: only shown when more than one database is connected. Leave it on All databases (AI decides), or tick the ones you want. If the AI can't tell which database you mean, it asks you instead of guessing.

Step 3: Generate

Click Generate report (or press Ctrl + Enter). While it works you can watch each step: getting ready, understanding your request, planning the report and fetching live data. A report usually takes between 5 and 60 seconds. Click Stop to cancel.

A report being built
While the report builds you can follow its progress, what the AI understood and its plan. Click Stop to cancel.

Step 4: Read and explore the result

  • Highlights: short cards at the top pointing out the highest, lowest, total, peak or average values.

  • Show as: switch between Table, Bar, Line, Pie and Figures (big numbers). Only the views that suit the data are offered.

  • Data table: filter rows, page through them, and see totals.

  • Refine: one-click changes such as Top 5 only, Add share of total, Split by day, Group by week, Compare with previous period or Break down by queue. The AI rebuilds the report with that change.

A finished report
A finished report: its title and summary, the period and row count, highlight cards, Refine suggestions and the Table / Bar switch.
Report chart and data table
Further down: the chart and the data table, with small bars that make the numbers easy to compare.
Report details panel
Report details: how the report was built step by step, the data it used and the exact query.

Step 5: Export, save and check the details

Button (top right)

What it does

Report details (panel icon)

Shows how the AI understood your request, which data it used, any corrections it made, the exact query, and the report's run history (who ran it, when, and how many rows).

Export (download icon)

Downloads the result as CSV or an Excel workbook.

Save

Saves the report to the shared list so you and your colleagues can rerun it.

How saved reports work. A saved report keeps your description, period and chart type, not a fixed query. Each time you open it, the AI builds the query again and runs it on the latest data. Saved reports are shared: everyone with access sees them, and deleting one removes it (and its run history) for everyone.

The status next to the report name tells you where you are: Not saved (new draft), Saved, or Unsaved changes.

Templates: ready-made starting points

Template

What it shows

Queue performance

Answered, abandoned and wait time per queue

Daily conversation outcomes

Agent-handled, bot-handled and abandoned per day

Agent productivity

Completed tasks and handle time per agent

No agent available

Tasks lost because no agent was free

Not-ready time by reason

Time agents spent not ready, per reason

Wrap-up categories

Share of each wrap-up category

Campaign results

Dialled, connected and success rate per campaign

Tips for good results

  • Name what to count or measure (answered chats, abandoned calls, handle time, ready time) and what to group by (per queue, per agent, per day).

  • Put the date range in the period picker rather than in the text. That way a saved report can be rerun for any period.

  • If a report shows too many rows, ask for totals or a top 10 instead of every row, or choose a shorter period.

  • If the result isn't what you meant, edit the wording and generate again, or use a Refine button.

4. AI Assistant: ask questions in a chat

Open Insights → AI Assistant, or use the Chat / Reports switch at the top of AI Reports. Type a question as you would ask a colleague, or click one of the suggested questions, such as:

  • How did my queues do in the last 7 days?

  • Which agents handled the most conversations this month?

  • What are the top wrap-up reasons in the last 30 days?

AI Assistant welcome screen
The AI Assistant: your chats on the left, suggested questions in the middle, and the question box at the bottom with buttons to add files and dictate.

What the assistant can do

  • Answer in plain words, with a chart or table when it helps.

  • Handle follow-up questions: after an answer, just ask and per agent? or what about last month?. It remembers the conversation.

  • Show its work: click the Worked for … s line above an answer to see each step (understanding the question, finding the data, planning the numbers, pulling the results). Click Show the query there to see the exact query behind the answer.

  • Read files and images: add Excel, CSV, PDF, Word, text files or screenshots with the paper-clip button, or drag and drop or paste them. Up to 5 files per message (4 of them images); files up to 10 MB, images up to 20 MB.

  • Take dictation: click the microphone and speak your question.

  • Suggest next questions under each answer.

The assistant's steps
Click Worked for … to see the steps the assistant took and the data it used. Show the query reveals the exact query.
An assistant answer with a chart
An answer: a short written summary, then a card with the chart. The icons at the top right of the card switch between table and chart, open it in Reports, download it, or save it as a report.

Buttons on each answer

Button

What it does

Open in Reports

Opens the same question in AI Reports, where you can change the chart, refine and export it.

Download

Downloads the numbers behind the answer.

Save as report

Adds it to the shared saved-reports list.

Copy answer

Copies the written answer.

Tokens badge

Shows how much AI work the answer used (text read and written by the AI, number of AI steps) and, where known, the cost.

Chat history

Your chats are listed on the left, grouped by Today, Yesterday, Previous 7 days and Older. Use New chat to start fresh, search old chats, or delete them.

Chat history is kept in your browser only. It is not shared with colleagues and won't appear on another computer. Saved reports are shared and are not affected when you delete a chat.

AI can make mistakes. Double-check important numbers before you share them. Open the answer in Reports or look at the query if something looks off.

5. When something goes wrong

Message you see

What it means

What to do

No AI model is set up for reports yet

AI settings haven't been filled in.

Administrator: complete AI settings (section 6).

Which database?

Several databases are connected and the AI can't tell which one you mean.

Choose the database next to the period and run again.

The reporting data can't answer this

The data needed for this question doesn't exist in the reporting database. The AI explains why.

Rephrase, or ask about something the data holds.

No data for this period

The query worked but found nothing.

Try a longer period or a broader description.

Showing the first … rows

The result was too big to show completely.

Narrow the period or ask for totals instead of every row.

The AI service isn't available right now

The AI account ran out of credit, reached its usage limit, or its key was rejected.

Administrator: top up the account or check the key in AI settings.

The AI Reports service didn't respond

The reporting service can't be reached.

Check your connection and try again in a moment. If it continues, contact support.

The report couldn't be built

Something went wrong while building it.

Click Run again; if it still fails, word it a little differently.

6. AI settings: choosing the AI model

Administrators only. Open Administration → AI settings. This decides which AI model turns questions into reports.

  1. Provider: OpenAI, Azure OpenAI, Anthropic, Google Gemini, Moonshot AI (Kimi), or a self-hosted OpenAI-compatible server (for example vLLM, Ollama or a LiteLLM proxy).

  2. Model: pick from the provider's own list (it loads once the key is entered) or type any model name the provider supports. Azure uses a Deployment name instead.

  3. Base URL / API version: only for Azure, self-hosted servers and Moonshot.

  4. API key: paste the key from the provider's console. It is stored encrypted and never shown again; only its last characters are displayed so you can recognise it. Leave the box empty to keep the saved key.

  5. Reasoning: Fast (quickest, may miscount on complex reports), Balanced (recommended) or Thorough (most careful, often several times slower).

  6. Click Test connection. When the model answers, save.

AI settings page
AI settings: provider, model, base URL (only for some providers), reasoning level and the API key.

What is sent to the AI provider? For AI Reports: the report description, table and column names, and a few sample rows, so the AI can write the right query. Report results are not sent. For AI Assistant answers, a small summary of the results is also sent so the AI can write the answer and understand follow-up questions.

7. Reporting databases: connecting your data

Administrators only. Open Administration → Reporting databases. This is the list of databases AI Reports is allowed to read. Most sites have one; larger setups may have several (for example one per site or server).

Reporting databases list
The Reporting databases list: each database with its type, address, whether it is in use, and how its login is stored.

Add a database

Click Add database and fill in:

Field

What to enter

ID

A short code such as server_a (lower-case letters, digits and _). It can't be changed later.

Name

A friendly name people will see, for example Karachi reporting.

What it holds

One line describing the data. This helps the AI pick the right database, so be specific.

Type

MySQL, SQL Server, PostgreSQL or Informix.

Host / Port

The database server address and port. The usual port is filled in for you. For Informix, use the server's DRDA port.

Database / Schema

The database name, and optionally the schema (for example dbo or public).

Username / Password

A read-only database login. It is encrypted on the server and never shown again, not even to administrators.

Links to other servers (optional)

Only if this server already reaches another database through an existing link (for example a SQL Server linked server or PostgreSQL foreign tables). Tick it and enter how this server names the other server's tables.

Click Test connection. A green message such as Connected: 120 tables in 35 ms means it works. Then click Add.

Add a database form
The Add a database form, filled in with example values. Enter a read-only login, click Test connection, then Add.

Always use a read-only login. AI Reports only ever runs read-only queries, but a read-only account adds a second layer of safety.

Reading the list

Label

Meaning

In use

The database is loaded and AI Reports can read it.

Not loaded

Saved, but not in use yet (often a login or connection problem).

Login stored (encrypted)

The username and password were entered here.

Login from the server

The login comes from the server's own settings.

No login

No working login. Edit the database and enter one.

Use Edit to change details (leave the login empty to keep the stored one) or Remove to stop reading a database. Removing deletes its stored login, and saved reports that used it will ask for another database.

If the page says the list is read-only, the database list is managed directly on the server and can only be changed there. Contact whoever runs the AI Reports service.

8. AI agent access: MCP tokens

Administrators only. Open Administration → AI agent access.

What is this, in simple terms?

Many people now use AI assistants on their own computer, such as Claude Code, Codex or Cursor. These assistants can connect to outside tools through a standard called MCP (Model Context Protocol). AI Reports offers such a connection, so a person can ask their own AI assistant show me abandoned chats per queue last week and get the answer straight from your reporting data.

An access token is like a personal key for that connection. You create one key per person or agent, decide what it may do and for how long, and can switch it off at any time.

AI agent access page
AI agent access: every token with what it may do, its status, who created it and when it expires. Connecting an agent at the bottom shows the address agents connect to.

Create a token

  1. Click New token.

  2. Name: name it after who or what will use it, for example claude-code-ayesha, so you can tell tokens apart later.

  3. Access: tick what the token may do (see the table below). See reports and Run reports are ticked by default and are enough for most people.

  4. Databases: shown when more than one database is connected. Leave all unticked to allow every database (including ones added later), or tick only the ones this person should see.

  5. Expires after: 7, 30, 90, 180 or 365 days.

  6. Click Create token.

New agent token form
The New agent token form: a name, the access options and how long the token lasts.

Access option

What it allows

Who needs it

See reports

See the data sources, saved reports and their run history.

Everyone

Run reports

Ask new questions and run saved reports. Each run uses the AI model.

Everyone

Save reports

Add reports to the shared library. Nothing can be deleted.

People who build reports for others

See table structure

Search tables and see their columns, keys and indexes.

Report developers

See sample data

See a few sample rows (at most 10) of a table.

Report developers

Run SQL

Run and explain read-only SQL, checked like the AI's own queries.

Report developers

Copy the token and connect

After you click Create token, the token is shown once only. Click Copy token straight away: it is not stored anywhere and can't be shown again. The same window also shows ready-to-copy commands for connecting:

  • Claude Code: a single claude mcp add … command that already contains the address and the token. The person pastes it into their terminal.

  • Codex: a codex mcp add … command. The person first puts the token in an environment variable called AI_REPORTS_TOKEN.

  • Other tools (Cursor and others): use the Agent address shown under Connecting an agent on the page, and send the token as a Bearer token.

Bash
# Claude Code (one line; the window fills in your address and token)
claude mcp add --scope user --transport http ai-reports https://your-domain.example.com/ai-reports/mcp --header "Authorization: Bearer YOUR_TOKEN"

# Codex (put the token in AI_REPORTS_TOKEN first)
codex mcp add ai-reports --url https://your-domain.example.com/ai-reports/mcp --bearer-token-env-var AI_REPORTS_TOKEN

Treat a token like a password. Send it privately (a direct message or a password manager), never in a group chat, email thread or ticket. Anyone who has it can use these reports.

Once connected, the person can ask their AI assistant things like list the saved reports, run the Queue performance report for last month or average handle time per agent this week.

Managing tokens

  • Each token shows its status ( Active , Expired or Revoked ), what it can do, which databases it can use, who created it, when it expires and when it was last used.

  • Revoke switches a token off. The agent loses access on its next request. This can't be undone; create a new token if access is needed again.

  • When a token expires, create a new one and send it to the person.

9. Frequently asked questions

Can the AI change or delete data?

No. Every query is read-only and is checked before it runs. Tokens with Save reports can add reports to the library but can't delete anything.

Are the numbers always right?

Usually, and the AI double-checks its own query, but it can misread a question. For important numbers, open Report details to see how it understood the request and the query it used.

Why does the same saved report give different numbers each time?

Saved reports run on the latest data every time, so numbers change as new conversations come in. Choose a fixed custom period if you need the same window.

Can my colleagues see my reports and chats?

Saved reports are shared with everyone who has AI Reports. Chats in the AI Assistant stay in your own browser.

The assistant only saw the names of my images. Why?

The AI model in use can't read images. An administrator can choose a model that can in AI settings.

Who do I contact if AI Reports doesn't work at all?

Your Agent Desk administrator. They can check AI settings, the reporting databases, and whether the AI Reports service is running.