> For the complete documentation index, see [llms.txt](https://help.genesis.autify.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.genesis.autify.com/workflow/ai-agent-block.md).

# AI Agent block

This article explains how to configure and use the AI Agent block in Autify Genesis. The AI Agent block is the basic workflow unit that uses an LLM (large language model) to generate text or structured data.

## Basic settings

Click a block to open the **Details** tab in the inspector on the right. Configure the following fields.

| Field                   | Description                                                                                                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name                    | Display name of the block. Appears on the canvas and in the inspector.                                                                                                                |
| Description             | Additional explanation of the block's role or processing.                                                                                                                             |
| Prompt                  | Instructions for the AI agent. Reference user inputs or explicitly defined inputs as `{{variable_name}}`. Outputs from connected upstream blocks are passed automatically as context. |
| Save output as artifact | When enabled, the output of this block is saved as a downloadable artifact.                                                                                                           |
| Review required         | When enabled, the workflow pauses after this block runs and waits for manual approval.                                                                                                |
| Model                   | Select the AI model to use. Multiple models are available per provider.                                                                                                               |

## Writing prompts

There are two ways to use values in a prompt: reference user inputs with `{{variable_name}}`, or use outputs from connected upstream blocks as automatic context.

### Referencing user inputs as variables

Use `{{variable_name}}` in a prompt to reference user inputs provided at run time or inputs explicitly defined on this block.

To insert a variable, click **Variable** at the top of the prompt editor to open the variable insertion menu. Depending on your configuration, the menu shows the following types.

| Variable type | Description                                           | Reference example    |
| ------------- | ----------------------------------------------------- | -------------------- |
| Inputs        | Input variables defined on this block                 | `{{input_key}}`      |
| Context       | User inputs provided by the user at workflow run time | `{{my_input}}`       |
| Block outputs | Outputs from other blocks added explicitly as inputs  | `{{previous_block}}` |

If you only want to use upstream block outputs as automatic context, you do not need to insert a variable.

{% hint style="warning" %}
If a variable referenced in the prompt is not defined in the block's inputs, validation fails. Use the variable insertion menu to pick from the available variables.
{% endhint %}

### Referencing outputs from connected upstream blocks

Outputs from upstream blocks connected to this block on the canvas are passed automatically as context at run time. To use upstream outputs, you do not need to insert `{{variable_name}}` each time.

When there are connections, the count of available connected blocks and the block names appear below the prompt field. Write your prompt assuming the outputs of those blocks.

### Referencing files, folders, and skills

You can insert workspace files, folders, and skills directly into the prompt so the AI agent can use them during execution.

#### Files and folders

1. Click **Add file** at the top of the prompt editor to open the file browser.
2. Search for files, browse folders, and select the files or folders you want to insert.
3. Add the selected items. They are inserted into the prompt as references.
4. To reference a particular file version, type `@` in the prompt, open the menu next to the file name, and select the target version.

When you reference a folder, the AI agent can inspect files inside that folder during execution.

#### Skills

Skills are reusable instruction packs discovered from `SKILL.md` files uploaded to the workspace or included in connected codebases.

1. Click **Add skill** at the top of the prompt editor, or type `/` at the start of a new token in the prompt.
2. Search for the skill you want to use.
3. Select the skill from the list.
4. The skill is inserted into the prompt as `/skill-name`.

If the workspace skill mode is **Automatic**, the AI agent can also choose relevant skills on its own. Referencing `/skill-name` always applies that skill to this prompt.

### Refining a prompt

Click **Refine** in the top-right of the prompt editor to use the AI-based prompt improvement feature.

| Action             | Description                                                                        |
| ------------------ | ---------------------------------------------------------------------------------- |
| Auto improve       | Tightens language and clarifies steps                                              |
| Make actionable    | Rewrites the prompt to include clear outputs, acceptance criteria, and constraints |
| Custom instruction | Enter your own improvement request and the AI adjusts the prompt accordingly       |

<figure><img src="/files/lhfZSSSDg5GEvRlXCCrR" alt="Screenshot of the refine prompt dialog"><figcaption><p>Refine prompt screen</p></figcaption></figure>

## Selecting a model

From the **Model** dropdown, select a model that fits the task. For details on available models, see [AI Models](/ai-feature/ai-models.md).

## Saving as an artifact

When you enable **Save output as artifact**, this block's output is saved as a downloadable file.

1. Turn on **Save output as artifact** in the inspector.
2. Enter a file name in **Artifact title** (if omitted, a name is generated automatically).
3. In **Artifact format**, choose **Markdown**, **JSON**, or **HTML**.
4. In **On re-run**, choose how the artifact should be updated on re-runs.

   | Mode          | Description                                                                               |
   | ------------- | ----------------------------------------------------------------------------------------- |
   | Regenerate    | Each run writes a new artifact from scratch. Good when every run should stand on its own. |
   | Edit in place | Re-runs apply targeted edits to the latest version of the existing artifact.              |

If **Structured output** is enabled, the artifact format is fixed to **JSON**.

{% hint style="info" %}
Saved artifacts can be accessed and downloaded from the execution details screen after the workflow run completes. Saved HTML artifacts open as rendered previews from execution details and file details. For versions created with **Edit in place**, open the diff panel against the previous version from the **Edits** chip, which shows the added and removed line counts. Click a line in the diff panel to jump to the matching position in the current document.
{% endhint %}

## Using the review feature

When you enable **Review required**, the workflow pauses after this block runs and waits for human review. For details, see [Review feature](/workflow/workflow-creation.md#review-feature) in "Create and Edit Workflows."

## Advanced options

Expand **Advanced options** in the inspector to access the following advanced settings.

<figure><img src="/files/Jmm7cZNKh0lMVH32CIJA" alt="Screenshot of the advanced options section"><figcaption><p>Advanced options screen</p></figcaption></figure>

### Structured output

When you enable **Structured output**, you can define the AI agent's output format with a JSON Schema. This makes it easier for downstream blocks to access specific fields in this block's output.

You can define a schema in two ways.

| Edit mode     | Description                                                      |
| ------------- | ---------------------------------------------------------------- |
| Schema editor | UI designer mode to add, delete, and configure fields one by one |
| JSON          | Text mode to input a JSON Schema directly                        |

In the schema editor, configure the following for each field.

| Field                  | Description                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------- |
| Field name             | Property name in the output JSON                                                      |
| Schema type            | Select from string / number / boolean / array / object                                |
| Description (optional) | Additional explanation for the AI agent. Helps the agent generate appropriate values. |
| Required               | Whether the field is required                                                         |

Click **Refine schema** to enter natural-language instructions for the AI to adjust the schema automatically.

{% hint style="warning" %}
When structured output is enabled, validation fails if the schema has no fields.
{% endhint %}

### Thinking effort

For supported reasoning models, **Thinking effort** lets you adjust how much internal reasoning the AI Agent block uses. Leave it on **Default** to use the model's recommended setting. Raise it for more complex tasks, or lower it when you want faster responses for simpler tasks.

If the selected model does not support **Thinking effort**, the control is unavailable.

### Tools

Under **Tools**, select the built-in tools the AI agent can use during execution. Enabled tools are called automatically when the agent determines they are needed.

Enabled tools appear as icons on the block on the canvas. Click the **+** button in the bottom-right of the block to add or remove tools in a popover with the same content as the **Tools** tab, without opening the inspector.

When external service integrations such as GitHub, Slack, or Aximo are configured, the corresponding tools do not appear in the **Tools** tab, and the AI agent uses them automatically at run time. For the full list of tool types and conditions, see [Tools](/ai-feature/tools.md).

### MCP server

Under **MCP servers**, you can add external MCP (Model Context Protocol) connections registered on the workspace to extend the agent's capabilities. For how to register external MCP connections, see [Workspace Settings](/settings/workspace-settings/workspace-configuration.md).

## Troubleshooting

### Model errors

| Situation                                     | Cause                                                      | Resolution               |
| --------------------------------------------- | ---------------------------------------------------------- | ------------------------ |
| "The selected model '{model}' is unavailable" | The selected model is not provided by any enabled provider | Select a different model |

### Structured output errors

| Situation                                 | Cause                                                       | Resolution                                                    |
| ----------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------- |
| Cannot run with structured output enabled | No fields are defined in the schema                         | Add fields in the schema editor, or disable structured output |
| "Invalid JSON schema"                     | The content entered in JSON mode is not a valid JSON Schema | Verify and fix the JSON syntax                                |

### Prompt errors

| Situation                                                | Cause                                                                    | Resolution                                                                                              |
| -------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| "Variables used in the prompt are not defined in inputs" | An input corresponding to a `{{variable_name}}` in the prompt is missing | Reinsert the variable from the variable insertion menu, or add the matching input in the **Inputs** tab |

### MCP server errors

| Situation                                                       | Cause                                                                                   | Resolution                                               |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| "Using an MCP connection that does not exist in this workspace" | The MCP connection referenced by the block was deleted, or belongs to another workspace | Re-add the connection in MCP server settings             |
| The connection check shows "Error"                              | The MCP server is not responding, or the credentials are invalid                        | Verify the URL and credentials, then edit the connection |


---

# 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://help.genesis.autify.com/workflow/ai-agent-block.md?ask=<question>&goal=<endgoal>
```

`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.