# AI Task

> Define AI work once and run it automatically on a schedule or on demand, with results verified against your acceptance criteria

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

## What is an AI Task?

An AI Task is a reusable unit of AI work that you define once and run automatically on a schedule or on demand.

Use an AI Task for work that is:

- **Repetitive**: it needs to happen regularly (daily, weekly, monthly).
- **Has a clear definition of done**: you can describe what a good output looks like.
- **Doesn't need your presence**: it can run without you being online.

For example:
- Summarize a weekly sales report and send it to Slack every Monday
- Run an eval that checks an AI answer quality against a gold standard
- Aggregate [AI Chat Insights](/docs/ai/learn-from-conversations) and make improvements in your models on a weekly basis.

Because the task has explicit acceptance criteria, every run is automatically evaluated (pass or fail), not just generated. This means:

- **Consistent output**: the AI follows the same brief every time.
- **Verified results**: the output is checked against your criteria before the task is marked complete.
- **Full automation**: runs on a schedule without any manual triggering.

## Create an AI Task

### Where to create an AI Task

Go to **Development**, then click **Add AI Task**.

### What goes into an AI Task

Below are the essential inputs you'll see on the UI. For advanced settings, see [How it works in code](#how-it-works-in-code).

- **Name** (required): The task's unique identifier, e.g. `revenue_weekly_insight`. Used to reference the task in a schedule or slash command.
- **Label** (required): Display name shown in the AI Tasks management page.
- **Description** (optional): A short note about what the task does, useful for teammates browsing the list.
- **Brief** (required): What you want the AI to complete, written like a detailed prompt. You can reference specific dashboards or datasets, and call on [AI Skills](/docs/ai/skills) to guide how the AI approaches the work.
- **Acceptance Criteria** (required): What a successful output looks like. AI can automatically generate this from your brief.
- **Tool list** (optional, coming soon): Restrict which tools the agent can use, to save cost and task latency.

## Schedule an AI Task

An AI Schedule defines when to run which AI Tasks, automatically. When creating an AI Task, you have the option to create a schedule for it.

**What goes into a schedule:**

- **Time and frequency** (required): When the task runs, e.g. every Monday at 8am, or on the 1st of every month. Follows your workspace timezone setting.
- **Run as** (required): The user identity the task executes as. The AI sees only what this user can see. If the user is deactivated or deleted before the schedule fires, the run fails.

## View published AI Tasks

Go to the AI Tasks page to see all published AI Tasks. The list shows each task's label, associated schedule, last run time, and last run status (running / success / failure).

Click a task to see its run history. Each run record includes:

- Status and timestamps (start time, end time).
- The trigger type: whether it was run by a schedule or triggered manually.
- The full output conversation, which you can read and continue from directly.

## Run an AI Task

### Test in development
While building a task in Development, you can run the task to test and iterate it before publishing.
In the AI Copilot chat page, type `/task-name` to run the task.

### Run in production
After publishing an AI Task, you and your teams can run it in production by:
- Clicking **Run** on the AI Tasks management page.
- Using the slash command `/task-name` in the **Ask AI** chat page. 

### Run on schedule
If an AI Task is configured to run on a schedule, the AI will automatically execute it under the "run as" user's permission.

## How it works in code

AI Task and AI Schedule are independent building blocks: one task can be targeted by multiple schedules, and one schedule can run multiple tasks. 

- When you create an AI Task, an `AiTask` is created in an `.ai_task.aml` file under `settings/ai/tasks/`. 
- When you schedule an AI Task, an `AiSchedule` is created in the `schedules.aml` file.

**`AiTask` definition in code:**

```aml
AiTask name {
  label:
  description (optional):
  brief:
  acceptance_criteria:
  timeout_minutes (optional):

  // Advanced settings:
  output_schema (optional):
  branch (optional):
}
```

Advanced settings not covered above:

- **Output Schema** (optional): A JSON schema defining the expected structure of the output. Use this when you need the result in a specific format, for example when a downstream system needs to parse it.
- **Branch** (optional, default: production): Which version of your data model the AI works against. 'Development' is coming soon.

**`AiSchedule` definition in code:**

```aml
AiSchedule {
  cron:
  run_as:
  targets: //One or more AiTask to run.
}
```

## AI Task vs. AI Skill

If you're already using [AI Skills](/docs/ai/skills), here's how a Task is different.

| | AI Skill | AI Task |
|---|---|---|
| **What it is** | Instructions on *how* the AI should perform a task | Defines *what* the AI should complete, with a clear definition of "done" |
| **When to use** | You have a repetitive task and want consistent answers | You have repetitive work to complete, need the output verified (not just generated), or have a potential need for automation |

**Analogy: briefing a new hire**

- You give a new analyst a brief: summarize last week's revenue by region and flag anomalies, with a clear definition of done: your team's checklist for what a good summary looks like. This is an **AI Task**.
- You hand them the team playbook: which tables to pull from, how to format the numbers, always compare against last quarter. This is an **AI Skill**.
- You put a standing invite on their calendar so it happens every Monday morning without you asking. This is an **AI Schedule**.

**Trigger behaviors:**

- **Can an AI Task trigger an AI Skill?**
  - Yes. A Task's brief can call on existing Skills to guide how the AI approaches the work: the Task defines *what* to do, the Skill defines *how* to do it well.
- **Can an AI Skill trigger an AI Task?**
  - No. Knowing how to do something best doesn't mean you'll randomly go do it. Even a well-trained analyst doesn't start summarizing revenue on their own just because they know how: someone has to actually assign the work.

## Send an email or Slack with AI Task

:::info Coming soon
We're building a delivery solution for AI Tasks.
:::

Today, an AI Task's output lives in its run record: you (or a teammate) open the run to read the result. Soon, an AI Task will be able to deliver its output directly, so a task like "summarize last week's revenue by region and flag anomalies" can end with that summary landing in a Slack channel or an inbox, with no manual step to copy it out.