# AI Block on dashboard

> Add prompt-driven AI-generated content to your dashboard that stays in sync with your data.

:::info Coming soon
AI Block is under development. Specs and design may change.
:::

## What is an AI Block?

An AI Block is a [dashboard block](/docs/dashboards#block) that generates written content from your dashboard's data, based on a prompt you write.

## Example use cases

### Summarize a dashboard

Turn your data into insights instead of leaving viewers to interpret the numbers themselves.

- **Prompt**: Summarize this dashboard and call out key insights.

### Analyze customer reviews

Turn open-ended reviews into sentiment and themes, instead of reading through every one yourself.

- **Prompt**: Analyze these customer reviews. Report whether sentiment is trending positive or negative, and group the feedback into common themes.

### Support tickets brief by viewer

Give each viewer the brief that's relevant to their role, instead of one summary everyone has to translate for themselves.

- **Prompt**: Use `/support_agent_manual`, `/cs_lead_manual`, or `/support_dashboard_brief` depending on the dashboard viewer's attribute.

- Each skill is scoped to a viewer attribute using [AI Skills](/docs/ai/skills):

  | Skill | Available to | What it does |
  |---|---|---|
  | `/cs_lead_manual` | Head of CS | Turns the dashboard into a brief on the pattern, the revenue it threatens, and this week's cross-functional decision. |
  | `/support_agent_manual` | Support Agents | Turns the dashboard into an ordered work list: what to reply to first, what to batch, what to hand off. |
  | `/support_dashboard_brief` | Everyone else | Summarizes what changed, why, and what it's costing. |

## Create an AI Block

### Where to create an AI Block

You can create an AI Block in either Development or Reporting. Go to a dashboard's edit mode, then add **AI Block** from the toolbar. 

In Development, you can also create one in code by adding an `AiBlock` to your dashboard file. See [How it works in code](#how-it-works-in-code).

### What goes into an AI Block

- **Prompt** (required): What you want the AI to generate, and how.
  - Reference the whole dashboard implicitly (e.g. "summarize this dashboard"), or point to a specific visualization or tab by `@mentioning` it.
  - You can also call on [AI Skills](/docs/ai/skills) to guide how the AI writes it, e.g. which template to follow or factor in business context like marketing campaigns.
- **Label** (optional): The block title displayed to dashboard viewers.

## Scope of data source

An AI Block uses the visualizations it detects in your prompt, all from the same dashboard, as its source data. It only works from what's already shown in those visualizations; it doesn't run a new query against the underlying dataset.

An AI Block cannot be a source for another AI Block.

## Refresh behavior

An AI Block is aware of changes in the data source. Whether it refreshes automatically or waits for your approval depends on the dashboard's [Auto-run on changes](/docs/dashboards/settings#auto-run-on-changes) setting:

- **Enabled**: when a change affects a source visualization (e.g. a filter, a drilldown, refreshed data), the AI Block refreshes automatically with the updated data.
- **Disabled**: the same change instead pops up a confirmation, asking whether to refresh the AI Block.

You can also refresh an AI Block anytime on demand, using its **Refresh** button.

## Permissions

Permission to create or view an AI Block follows a user's access to AI, not their role alone.

- By default, Viewers don't have access to AI, so they can't create or view an AI Block.
- Explorer, Analyst, and Admin can create or view an AI Block if AI access is enabled for them. See [Who Can Use AI](/docs/ai/user-access) for details.

:::info Coming soon
We're considering AI access for Viewers.
:::

## How it works in code

An AI Block is defined as an `AiBlock` inside a dashboard's definition:

```aml
block <name>: AiBlock {
  label: 'Block Label' // optional
  prompt: 'Your prompt here' // or @md Heredoc;;
  theme: BlockTheme { ... } // optional
}
```

For example:

```aml
Dashboard ecommerce_demo {
  title: 'Ecommerce Demo'
  description: ''

  block v_xgoq: AiBlock {
    label: 'Summary of Ecommerce Dashboard'
    prompt: @md Summarize the whole dashboard;;
  }
}
```

## Export AI Block with your dashboard

:::info Coming soon
We're building export support for AI Block.
:::

Today, an AI Block's content doesn't appear when you export or schedule an export of its dashboard. Soon, AI Block content will be included in dashboard exports, so a recurring report (like a weekly summary emailed to your team) can include the AI-generated narrative alongside your charts, using the same [export and scheduled export](/tutorials/schedule-dashboard) feature you already use today.