> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent modes

> Create chat modes the AI enters on its own, each with its own instructions. Use when a web chat session should switch into a guided flow with a custom screen.

Agent modes are chat modes the AI enters on its own, each with its own instructions. Use one when a web chat session should switch from normal back-and-forth into a guided step, such as onboarding, and your website shows a dedicated screen for that step.

> [!NOTE]
>
> **Settings → Agent Modes** in your [OpenCX dashboard](https://platform.open.cx/settings/agent-modes). Viewing needs the **Settings** permission; creating and editing modes needs edit access to **Settings**.

## How a mode runs

**1. The AI decides to enter**

While a session is not in a mode, the AI sees every enabled mode with its **When to enter the mode?** text and enters one when the session matches.

**2. It follows the entry instructions**

In the same reply, the AI follows **Behavior upon entering the mode**.

**3. Your widget shows the mode's screen**

The session records the active mode. The web widget renders the component you registered for that mode with [`modesComponents`](https://docs.open.cx/widget/configuration-reference#modescomponents).

**4. Your screen ends the mode**

When the visitor finishes, your component calls `sendMessage` with the visitor's message and an `exitModePrompt`. The AI uses the exit prompt for its reply, and the session leaves the mode.

While a session is in a mode, the AI cannot enter another one.

## Create a mode

![Creating the agent mode Return request in Settings, Agent Modes, and seeing it switched on in the list](https://mintcdn.com/openchat/hiyaCL2S28Hya6Q7/images/settings/agent-mode-create.gif?s=aece3e0aef81e3196e53c772305cf776)

Create a Return request mode with its instructions; it is on as soon as it is saved.

**1. Open Agent Modes**

Go to **[Settings → Agent Modes](https://platform.open.cx/settings/agent-modes)** and select **New mode**.

**2. Fill in the fields**

Give the mode a **Name** and the instructions described below.

**3. Create it**

Leave **Enable this mode** on and select **Create mode**.

| Field | What it does |
| - | - |
| **Name** | Identifies the mode to the AI and to your widget. Saving also sets the mode's slug from the name: lowercase, with hyphens for spaces and symbols (*Account onboarding* becomes `account-onboarding`) |
| **When to enter the mode?** | The condition the AI checks before entering, for example *when the user asks about creating an account* |
| **Behavior upon entering the mode** | Instructions the AI follows in the reply where it enters the mode |
| **Behavior while in the mode** | Saved with the mode. It does not currently change how the AI replies, so put what the AI must say in **Behavior upon entering the mode** and in your component's exit prompt |
| **Enable this mode** | Only enabled modes are offered to the AI. On by default when you create a mode |

To change a mode, select the settings icon on its row and **Save changes**. To retire one, turn off its switch in the **Enabled** column.

> [!NOTE]
>
> If your widget looks a mode up by its slug, update the `modesComponents` key after renaming the mode. Looking it up by ID avoids this.

## Which channels support modes

Modes are built for web chat: only the web widget shows a mode's screen and sends the message that ends the mode. Modes apply to your whole organization, and the AI's choice to enter one is not limited to web chat. On another channel, a session that enters a mode stays in it, so the AI cannot enter a different mode later in that session.

## Example: onboarding

A merchant asks in web chat how to join your service. You want the AI to hand over to a short form, then confirm the request.

| Field | Value |
| - | - |
| **Name** | Onboarding |
| **When to enter the mode?** | When the visitor wants to sign up as a new merchant or asks how to create an account. |
| **Behavior upon entering the mode** | Tell the visitor you need two details to check eligibility, their expected monthly volume and their target market, and that they can enter them in the form on screen. |
| **Behavior while in the mode** | Leave empty. |
| **Enable this mode** | On |

On your website, register a component under the key `onboarding`, the slug made from the name:

```tsx theme={"dark"}
const options = {
  token: '<WIDGET_TOKEN>',
  modesComponents: [{ key: 'onboarding', component: Onboarding }],
};
```

The `Onboarding` component collects the two values and, on submit, calls `sendMessage` with them as `content` and an `exitModePrompt` such as *Tell the visitor their request is submitted and that you will notify them after the review.* The full component is in the [configuration reference](https://docs.open.cx/widget/configuration-reference.md#modescomponents).

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| The AI never enters the mode | The mode is off, or **When to enter the mode?** does not match how visitors ask | Turn on **Enable this mode** and describe the situation in the visitors' words |
| The mode starts but the widget shows normal chat | No component is registered for the mode, or the key no longer matches after a rename | Register the mode's ID, name or slug in `modesComponents` |
| The AI does not enter a second mode | The session is still in the first mode | End the first mode from your component with `sendMessage` |

***

## Related Documentation

> [card] [Custom components](https://docs.open.cx/widget/custom-components.md)
>
> Build richer UI for modes and action results.

> [card] [Widget configuration reference](https://docs.open.cx/widget/configuration-reference.md#modescomponents)
>
> `modesComponents` props and a full example.

> [card] [Widget configuration](https://docs.open.cx/widget/configuration.md#advanced-ui-conversation-modes)
>
> When to use modes versus custom components.

> [card] [Training scenarios](https://docs.open.cx/ai-instructions/training-scenarios.md)
>
> Instructions that apply in every session.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.