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

# Manage AI agents

{% hint style="warning" %}
Requires the **Manage AI agents** permission. Workspace admins can grant this under [**Settings → Workspace → Roles & permissions**](/docs/settings/general/roles-and-permissions.md).
{% endhint %}

Open the **AI Agents** module to manage agents. All new workspaces start with a Default AI agent which can be modified or deleted.

***

## Switch agents

1. Select the **current agent dropdown** at the top of the dashboard.
2. Select the agent to switch to.

***

## Create or import an agent

{% hint style="info" %}
The number of AI agents available depends on your subscription plan.
{% endhint %}

Select the **current agent dropdown** → **Create AI agent**, then choose **Create** or **Import AI agent**.

{% tabs %}
{% tab title="Create" %}

| Field                | Description                                                          |
| -------------------- | -------------------------------------------------------------------- |
| **Avatar**           | The agent's profile picture. Shown in agent network views. Optional. |
| **Name**             | The agent's name shown in messaging apps.                            |
| **Default language** | The default localisation language for triggers and actions.          |

Press **Create** to finish.
{% endtab %}

{% tab title="Import" %}
{% hint style="warning" %}
Importing is for legacy chatbots previously exported from Proto v2 (pre-2025) only.
{% endhint %}

Supply the same **Avatar** and **Name** fields, then upload the ZIP file of the previously exported agent. Press **Create** to finish.
{% endtab %}
{% endtabs %}

***

## Agent tabs

{% tabs %}
{% tab title="Agent" %}

### Personalisation

| Setting                  | Description                                                  |
| ------------------------ | ------------------------------------------------------------ |
| **Large language model** | Toggle to enable or disable generative LLM replies.          |
| **Agent persona**        | Instructions defining the agent's role, tone, and behaviour. |

### Languages

| Setting              | Description                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------- |
| **Languages**        | Languages the agent's workflows operate in. Content must be translated manually for each. |
| **Default language** | The agent's fallback language when no other matches.                                      |

{% hint style="info" %}
The number of assignable languages depends on your subscription plan.
{% endhint %}

### Settings

| Setting    | Description                    |
| ---------- | ------------------------------ |
| **Avatar** | PNG, JPEG, or GIF up to 10 MB. |
| **Name**   | The agent's display name.      |

### Danger zone

{% hint style="danger" %}
**Delete agent** permanently removes the agent and all associated data. This cannot be undone. Historic chat logs persist, but channels the agent was published to will stop working. Migrate your audience to another agent before deleting.
{% endhint %}

Press **Save** in each section to apply changes.
{% endtab %}

{% tab title="Voice" %}

### Speech-to-text

| Setting                   | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| **Enable speech-to-text** | Toggle transcription of incoming voice messages on or off. |
| **Languages**             | The languages to transcribe.                               |

### Text-to-speech

| Setting                      | Description                                            |
| ---------------------------- | ------------------------------------------------------ |
| **Enable text-to-speech**    | Toggle AI agent voice replies on or off.               |
| **Include audio transcript** | Sends the text transcript alongside the voice message. |
| **Languages**                | Languages for generated voice messages.                |
| **Gender**                   | The gender of the generated voice (male or female).    |

Press **Save** in each section to apply changes.
{% endtab %}

{% tab title="Versions" %}

| Column        | Description                                           |
| ------------- | ----------------------------------------------------- |
| Name          | Version name                                          |
| Created       | Who created it and when                               |
| Last deployed | When it was last pushed live                          |
| Last changed  | Most recent edit                                      |
| Note          | Optional version note                                 |
| Status        | **Live** marks the version currently active for users |
| {% endtab %}  |                                                       |

{% tab title="Change log" %}
An audit trail of changes to the selected version's workflows. Each entry records the user, event type, the affected action's ID and name, and the timestamp.

Filterable by date, user, and action.
{% endtab %}

{% tab title="Network" %}
Contains the agent's external handoff credentials — used to receive conversations from another AI agent.

| Field           | Description                               |
| --------------- | ----------------------------------------- |
| AI agent ID     | Unique identifier for this agent          |
| AI agent secret | Secure key for verifying inbound handoffs |
| Platform domain | The domain where this agent is hosted     |

Copy these values into the [AI agent handoff](/docs/modules/ai-agents/workflows-and-actions/ai-agent-handoff.md) action of the originating agent.
{% endtab %}
{% endtabs %}

***

## AI agent tester

A built-in chat panel for testing the agent's responses directly from the dashboard. Shows which version is being tested and whether it is live. Type a message to interact as a person would. Use the refresh button to restart the test conversation.

***

## Knowledge

Train the agent on content it uses to generate replies. See [Knowledge](/docs/modules/ai-agents/knowledge.md).

***

## Publish

Deploy the agent live to messaging channels. See [Publishing](/docs/modules/ai-agents/publishing.md).