> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-automate/19.latest/add-ons/ai/actions.md).

# Actions

Reference for the actions contributed by the Umbraco.AI.Automate add-on.

The AI add-on contributes the following actions.

## Run AI Agent

Alias: `umbracoAI.runAgent`. Run an AI agent and capture its response. Useful for tasks like generating translations, summarising content, or scoring leads.

The action picks an agent from the list of agents that are scoped to the **Automations** surface in Umbraco.AI. The user message supports [bindings](/umbraco-automate/19.latest/concepts/bindings.md).

When the agent declares a structured-output schema, each output field is exposed as a named binding under the step output. Inspect a real run to see the available fields.

### Settings

| Setting          | Description                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------- |
| Agent            | The agent to run. Only agents scoped to the **Automations** surface are listed.              |
| Message          | The message sent to the agent. Supports bindings.                                            |
| Attachments      | Optional media to send with the message. Supports bindings. See [Attachments](#attachments). |
| Tool permissions | Whether the agent can make changes. See [Tool permissions](#tool-permissions).               |

### Attachments

Attach media items so the agent can work with files, for example to describe an image or summarize a document. Enter one or more media references, separated by commas or new lines. Each reference can be:

* A media key (GUID).
* A media UDI, such as `umb://media/…`.
* A media picker value, for example bound from a trigger or an earlier step.

Images are passed to the model directly, so use an agent whose model supports images. Documents and audio are turned into text first. Plain text (`.txt`, `.md`, `.csv`) and Office files (`.docx`, `.xlsx`, `.pptx`) have their text extracted. Audio is transcribed, which needs a speech-to-text profile in Umbraco.AI.

Access to each media item is checked using the service account of the automation's workspace. If a reference can't be read, doesn't exist, or can't be accessed, the step fails and the agent does not run. A run can include up to 10 attachments, with a combined size of 20 MB.

### Tool permissions

Nobody is watching an automation run, so nothing can be approved mid-run. **Tool permissions** decides which changes the agent may make without a human:

| Option                           | Behavior                                                                                                                                                                                             |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read only (default)              | The agent can look things up but can't make any changes. Every destructive tool is denied.                                                                                                           |
| Changes that don't need approval | The agent can also make changes editors can undo, such as creating or editing draft content and media. Changes that need approval, such as publishing, unpublishing, or deleting, are always denied. |

This setting only narrows what the agent may do. The agent must also be allowed the tools in Umbraco.AI, for example through the `content-write` scope. Saved automations without this setting run as **Read only**.

### Service account access

The agent's tools act as the service account of the automation's workspace. They can only read and change what that account could in the backoffice. Its sections, start nodes, and permissions all apply:

| To let the agent                                | The service account needs                                                  |
| ----------------------------------------------- | -------------------------------------------------------------------------- |
| Read full content, or create and edit content   | The Content section                                                        |
| Create and edit media                           | The Media section                                                          |
| List or search content and media, or read media | Any section that shows the content or media tree, such as Content or Media |

Start nodes and permissions are checked on top of the section. For example, the agent can't read or change content outside the account's content start nodes. When the account lacks access, the tool tells the agent so and doesn't return or change the item. Search results the account can't see are left out.

## Transcribe Audio

Alias: `umbracoAI.transcribeAudio`. Transcribe an audio file using Umbraco.AI's speech-to-text capability. The Umbraco.AI profile used by the action must use a provider that supports speech-to-text.

## Decision Actions

{% hint style="warning" %}
The Decision actions use Umbraco.AI's experimental [Decision](https://docs.umbraco.com/ai-in-umbraco/using-the-api/decision) capability. They only appear in the action picker when the `Umbraco:AI:Experimental:Decision` feature flag is enabled at startup. If the flag is turned off later without a restart, the steps fail with a validation error and no provider is called.
{% endhint %}

The four Decision actions ask typed questions and return typed answers. Bind their outputs in an [If or Switch](/umbraco-automate/19.latest/concepts/control-flow.md) node to branch the automation.

* **Ask Yes/No**, **Ask Pick-One**, and **Ask Score** each ask one question.
* **Ask Questions** asks multiple questions about the same content in a single call.

The three single-question actions share these settings:

| Setting          | Required | Description                                                                                      |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------ |
| **Instructions** | Yes      | What to decide. Supports [bindings](/umbraco-automate/19.latest/concepts/bindings.md).           |
| **Context**      | No       | The content to judge against the instructions, such as a content item's text. Supports bindings. |
| **Profile**      | No       | The Umbraco.AI Decision profile to use. Leave empty to use the default Decision profile.         |

A step fails with a validation error when the settings are invalid or no Decision profile can be resolved. Provider errors, such as an invalid API key, fail the step with the provider's message. A step set to **Retry** stops the run without retrying when the API key is rejected or the request is invalid. Rate limits and network errors are retried.

### Ask Yes/No

Alias: `umbracoAI.askYesNoDecision`. Ask a yes/no question.

| Extra setting      | Required | Description                                                                                                                                     |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **True criteria**  | No       | What counts as "yes", beyond the instructions. Supports bindings.                                                                               |
| **False criteria** | No       | What counts as "no", beyond the instructions. Supports bindings.                                                                                |
| **Threshold**      | No       | The minimum probability, from 0.0 to 1.0, counted as "yes". Defaults to 0.5. A value outside 0.0 to 1.0 fails the step with a validation error. |

| Output          | Type    | Description                                                          |
| --------------- | ------- | -------------------------------------------------------------------- |
| **Answer**      | Boolean | `true` when **Probability** is at least **Threshold**.               |
| **Probability** | Number  | The estimated probability that the answer is "yes", from 0.0 to 1.0. |

### Ask Pick-One

Alias: `umbracoAI.askChoiceDecision`. Pick one option from a fixed list.

| Extra setting | Required | Description                                                                 |
| ------------- | -------- | --------------------------------------------------------------------------- |
| **Options**   | Yes      | The options to choose from. Between 2 and 255 rows, each with a unique key. |

The **Options** editor is a list of rows. Each row has a **Key** and a **Description**:

* **Key** is the value returned in the **Choice** output when the option is picked. It is required.
* **Description** is optional. It explains the option to the model, which helps when the key alone is not clear.

Use the editor to add, remove, and reorder rows.

| Output         | Type   | Description                                                                                                |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| **Choice**     | Text   | The key of the chosen option.                                                                              |
| **Confidence** | Number | The provider's own confidence in the choice, from 0.0 to 1.0. Empty when the provider does not report one. |

### Ask Score

Alias: `umbracoAI.askScoreDecision`. Score the content against labelled levels.

| Extra setting | Required | Description                                                                  |
| ------------- | -------- | ---------------------------------------------------------------------------- |
| **Levels**    | Yes      | The level labels, lowest first, entered as a list. Between 2 and 10 entries. |

| Output         | Type   | Description                                                                                               |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| **Score**      | Number | A 0-based, fractional index into the levels.                                                              |
| **Level**      | Text   | The label of the level nearest to the score.                                                              |
| **Confidence** | Number | The provider's own confidence in the score, from 0.0 to 1.0. Empty when the provider does not report one. |

### Ask Questions

Alias: `umbracoAI.askDecisions`. Ask multiple questions about the same content in a single call. Each run makes one call to the Decision profile, however many questions the step has.

| Setting       | Required | Description                                                                              |
| ------------- | -------- | ---------------------------------------------------------------------------------------- |
| **Questions** | Yes      | The questions to ask. Between 1 and 20.                                                  |
| **Context**   | No       | The content every question is judged against. Supports bindings.                         |
| **Profile**   | No       | The Umbraco.AI Decision profile to use. Leave empty to use the default Decision profile. |

To add a question, select **Add question** and pick a kind: **Yes/no**, **Pick-one**, or **Score**. Then fill in the question and save it. Select a question in the list to edit it, or remove it from the list.

Each question has:

| Field                                 | Required | Description                                                                                                                                |
| ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Alias**                             | Yes      | The name of the question's output. Must be unique within the step, start with a letter, and contain only letters, digits, and underscores. |
| **Instructions**                      | Yes      | What to decide.                                                                                                                            |
| **True criteria**, **False criteria** | No       | Yes/no only. What counts as "yes" and "no", beyond the instructions.                                                                       |
| **Threshold**                         | No       | Yes/no only. The minimum probability, from 0.0 to 1.0, counted as "yes". Defaults to 0.5.                                                  |
| **Options**                           | Yes      | Pick-one only. Between 2 and 255 rows, each with a unique **Key** and an optional **Value** that describes the option.                     |
| **Levels**                            | Yes      | Score only. The level labels, lowest first. Between 2 and 10 entries.                                                                      |

The fields inside a question do not support bindings. Use **Context** to pass content from earlier steps. If you need to bind the question text itself, use one of the single-question actions instead.

The output has one entry per question, named by its alias. Each entry has the same fields as the matching single-question action:

| Question kind | Output fields                  |
| ------------- | ------------------------------ |
| Yes/no        | `answer`, `probability`        |
| Pick-one      | `choice`, `confidence`         |
| Score         | `score`, `level`, `confidence` |

For example, a yes/no question with the alias `spam` produces `spam.answer` and `spam.probability`. The binding picker lists each alias and its fields once the questions are configured.

A missing, duplicated, or invalid alias, or any invalid question, fails the step with a validation error before any provider is called.

### Binding Support

| Setting                                                                | Supports bindings |
| ---------------------------------------------------------------------- | ----------------- |
| **Instructions** (single-question actions)                             | Yes               |
| **Context** (all four actions)                                         | Yes               |
| **True criteria**, **False criteria** (Ask Yes/No)                     | Yes               |
| **Threshold**, **Options**, **Levels**, **Profile**                    | No                |
| **Questions** (Ask Questions), including every field inside a question | No                |

## Extract Values

{% hint style="warning" %}
Extract Values uses Umbraco.AI's experimental [Extraction](https://docs.umbraco.com/ai-in-umbraco/using-the-api/extraction) capability. It only appears in the action picker when the `Umbraco:AI:Experimental:Extraction` feature flag is enabled at startup. If the flag is turned off later without a restart, the step fails with a validation error and no provider is called.
{% endhint %}

Alias: `umbracoAI.extractValues`. Read typed values, such as an order number, an amount, or a date, out of a piece of text. Each run makes one call to the Extraction profile, however many fields the step has. Each value becomes a step output that later steps can bind to.

### Settings

| Setting            | Required | Description                                                                                                                                                                                                  |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Fields**         | Yes      | The values to extract. Between 1 and 20.                                                                                                                                                                     |
| **Content**        | Yes      | The text to extract the values from, such as an email body. Supports [bindings](/umbraco-automate/19.latest/concepts/bindings.md).                                                                           |
| **Reference date** | No       | The date that relative dates in the content, such as "tomorrow", are resolved against. An ISO date, such as `2026-10-20`, or an ISO date and time. Supports bindings. Leave empty to use today's date (UTC). |
| **Profile**        | No       | The Umbraco.AI Extraction profile to use. Leave empty to use the default Extraction profile.                                                                                                                 |

To add a field, select **Add field** and pick a type: **Text**, **Number**, **Date**, **Time**, **Date and time**, **Duration**, or **List**. Then fill in the field and save it. Select a field in the list to edit it, or remove it from the list.

Each field has:

| Field              | Required        | Description                                                                                                                                                                                          |
| ------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Alias**          | Yes             | The name of the field's output. Must be unique within the step, start with a letter or `_`, and contain only letters, digits, and `_`. Up to 64 characters.                                          |
| **Instructions**   | Yes             | What the value is. Be specific, for example "The total amount the customer paid, including VAT".                                                                                                     |
| **Decimal places** | No              | Number and Duration only. Rounds the value, from 0 to 6.                                                                                                                                             |
| **Whole number**   | No              | Number and Duration only. Only accept whole numbers.                                                                                                                                                 |
| **Unit**           | See description | Number: optional. The unit or currency, such as `EUR` or `kg`, which helps the model pick the right number. Duration: required. The unit the duration is measured in, from **Seconds** to **Years**. |
| **Item type**      | No              | List only. What each item is: **Text** (default), **Number**, or **Date**.                                                                                                                           |

The fields inside a field definition do not support bindings. Use **Content** to pass text from earlier steps.

### Outputs

The output has one entry per field, named by its alias. Every entry is always there, even when the value was not found, so later steps can rely on it:

| Output field | Type                 | Description                                                                                                                                                                               |
| ------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`      | Depends on the field | The extracted value, or empty when it was not found. Text, Date, Time, and Date and time values are strings. Number and Duration values are numbers. List values are an array of strings. |
| `found`      | Boolean              | `true` when the value was found in the content.                                                                                                                                           |
| `confidence` | Number               | The model's confidence in the value, from 0.0 to 1.0. Empty when the provider does not report one.                                                                                        |

Dates use `yyyy-MM-dd`, and times use `HH:mm:ss`. A Duration value is in the unit the field asked for.

For example, a step with the alias `extract` and a field with the alias `orderId` produces `${ steps.extract.orderId.value }`, `${ steps.extract.orderId.found }`, and `${ steps.extract.orderId.confidence }`. The binding picker lists each alias and its fields once the fields are configured.

A missing, duplicated, or invalid alias, empty content, or any invalid field fails the step with a validation error before any provider is called. Provider errors, such as an invalid API token, fail the step with the provider's message. A step set to **Retry** stops the run without retrying when the API token is rejected or the request is invalid. Rate limits and network errors are retried.

### Example: Triage a Support Ticket

This automation reads a support email that arrives through a webhook, and only continues when the email names an order.

1. Add a **Webhook** trigger. The ticket text arrives as `${ trigger.body }`.
2. Add an **Extract Values** step with the alias `extract`:

   * **Content**: `${ trigger.body }`
   * **Fields**:

   | Type   | Alias             | Instructions                                    | Options                                |
   | ------ | ----------------- | ----------------------------------------------- | -------------------------------------- |
   | Text   | `orderId`         | The order number                                |                                        |
   | Number | `amount`          | The amount the customer paid                    | **Unit**: `DKK`, **Decimal places**: 2 |
   | Date   | `deliveredOn`     | The date the order was delivered                |                                        |
   | List   | `damagedProducts` | Every product the customer says arrived damaged | **Item type**: Text                    |
3. Add an **If** node that checks `${ steps.extract.orderId.found }` equals `true`.
4. On the true branch, add the steps that handle the ticket, for example a **Send Email** to the support team. Bind the extracted values in its body, such as `${ steps.extract.orderId.value }` and `${ steps.extract.damagedProducts.value }`.
5. On the false branch, add a step that asks the customer for their order number.

Given the ticket "Order A-88412 arrived on 3 October. I paid 701,10 kr, but the mug and the teapot were broken.", the step outputs `orderId` `"A-88412"`, `amount` `701.1`, `deliveredOn` `"2026-10-03"`, and `damagedProducts` `["mug", "teapot"]`, each with `found` set to `true`.

Branch on `found` to check whether a value was extracted. It is always `true` or `false`, whatever the type of value.

{% hint style="info" %}
Open the step in the canvas to see each action's settings and output fields.
{% endhint %}


---

# 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.umbraco.com/umbraco-automate/19.latest/add-ons/ai/actions.md?ask=<question>&goal=<user_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.
