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

# AI Agent

AI Agent allows you to build AI-powered conversations in Flow Builder. By defining the AI's role, goals, and completion criteria, the AI can understand customer requests, answer questions, and optionally perform actions such as searching your Knowledge Base, creating bookings, or interacting with Google Sheets.

{% hint style="info" %}
AI Agent is currently available in Beta for **Business Plan** and above.
{% endhint %}

***

## Before you start

Before configuring an AI Agent, make sure you have:

* A **Business Plan or above**.
* A Flow created in **Flow Builder**.
* (Optional) Booking items created if you want the AI to create bookings.
* (Optional) Google Sheets connected if you want the AI to access spreadsheet data.
* (Optional) Knowledge Base documents uploaded if you want the AI to answer using your documents.

> **Note:** AI Agent is currently in **Beta**. Features and supported actions may change in future releases.

***

## Add an AI Agent block

1. Open **Flow Builder**.
2. Drag the **AI Agent** block onto the canvas.
3. Connect it to your flow.
4. Click **Configure**.

<figure><img src="/files/0bhGIR6wq5DjaOfObqZZ" alt="" width="278"><figcaption></figcaption></figure>

***

## Configure the AI Agent

The AI Agent is configured using three sections.

<figure><img src="/files/RkLrSSNvxIAj3avL7lxo" alt="" width="375"><figcaption></figcaption></figure>

### Role

Describe who the AI should act as.

This helps define the AI's identity, expertise, or tone when interacting with customers.

**Example**

> You are a customer service representative for a beauty salon.

***

### Goal

Describe what the AI should achieve.

Clearly define the tasks or objectives you expect the AI to accomplish.

**Example**

> Answer customer enquiries, recommend suitable treatments, assist customers with appointment booking, and collect the required booking information.

***

### Completion criteria

Define when the AI has successfully completed its task.

You can add one or multiple completion criteria depending on your use case.

**Examples**

* The customer's question has been answered.
* A booking has been created successfully.
* All required booking information has been collected.
* The customer no longer needs assistance.

***

## Actions (Optional)

Actions extend what the AI Agent can do.

You may configure one, multiple, or no actions depending on your use case. If no actions are configured, the AI Agent will respond according to its Role, Goal, Completion Criteria, and the available conversation context.

***

### Set Custom Field

<figure><img src="/files/fqFjCywLZHYGatevZQno" alt="" width="375"><figcaption></figcaption></figure>

Allow the AI Agent to save collected information into contact custom fields.

Typical use cases include:

* Customer name
* Membership ID
* Preferred language
* Product preference

***

### Set Label

<figure><img src="/files/D6ok6EYygbF8Oh92TwoT" alt="" width="375"><figcaption></figcaption></figure>

Allow the AI Agent to automatically apply labels to conversations.

Example labels:

* VIP
* New Customer
* Interested
* Follow-up Required

***

### Search Knowledge Base

<figure><img src="/files/j15vm8BnSWx607UxbysO" alt="" width="375"><figcaption></figcaption></figure>

Allow the AI Agent to search your uploaded Knowledge Base documents when answering customer questions.

This is useful for:

* Frequently asked questions
* Product information
* Internal documentation
* Company policies
* Service guides

***

### Create Booking

Allow the AI Agent to create bookings for customers.

After adding this action:

1. Select a booking item.
2. (Optional) Add booking instructions.
3. Configure the metadata fields.
4. Mark fields as **Required** if customers must provide the information before a booking can be created.

<figure><img src="/files/VvkewSuwSUysnEu9DLKq" alt="" width="375"><figcaption></figcaption></figure>

#### Metadata fields

Metadata fields tell the AI what information it should collect for the booking.

For example:

| Field           | Description                     |
| --------------- | ------------------------------- |
| CustomerName    | Customer's full name            |
| PhoneNumber     | Contact number                  |
| AppointmentDate | Preferred appointment date      |
| SkinConcern     | Customer's primary skin concern |

You can customize each field description to help the AI understand what information should be collected.

***

### Google Sheet

Allow the AI Agent to interact with a connected Google Sheet.

<figure><img src="/files/3C9hXuVYeVJZqXt5lYcZ" alt="" width="375"><figcaption></figcaption></figure>

#### Step 1

Select a spreadsheet from Google Drive.

#### Step 2

(Optional) Specify a sheet title.

If left empty, the default sheet will be used.

#### Step 3

Provide instructions describing how the AI should use the spreadsheet.

**Example**

> Search customer membership records before answering customer enquiries.

***

#### Configure columns (Optional)

You may specify which columns the AI can access.

For each column, choose one or more permissions:

* **Read** – Read data from the column.
* **Append** – Add new values to the column.
* **Update** – Modify existing values in the column.

If no columns are configured, the AI Agent may use all available columns according to the permissions you have granted.

***

#### Sheet permissions

Select how the AI can interact with the spreadsheet.

* Allow AI to read from this sheet
* Allow AI to append rows to this sheet
* Allow AI to update rows in this sheet

Grant only the permissions required for your use case.

***

## Continue building your flow

After configuring the AI Agent:

1. Click **Done** to save the AI Agent configuration.
2. Continue building your Flow by connecting the AI Agent to other Flow blocks as needed.
3. Once your Flow is complete, click **Save** and **Publish** to make it available to customers.

***

## Best practices

* Clearly define the AI Agent's role and responsibilities.
* Keep goals focused on a specific business task.
* Use completion criteria to define when the AI should finish the conversation.
* Only enable the actions required for your use case.
* Provide clear descriptions for booking metadata fields.
* Grant Google Sheet permissions based on the minimum access required.
* Test your AI Agent thoroughly before publishing your Flow.