> This page is for Omni Channel. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.hams.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.hams.ai/_mcp/server. # Assistants > Create an AI agent, set its instructions and behavior, and assign it to conversations. An AI agent answers customers in conversations. It reads the messages of the customer and searches the knowledge that you gave it. Then it replies, or it transfers the conversation to a human agent. The same AI agent can also answer calls. See [Voice agents](/cloud-call-center/voice-agents). > **Note** > > The AI agent is off by default. Hams support turns on the **Workflows + Agent** feature for your account. The same feature turns on workflows. Only administrators can see **AI** in the sidebar and create or change AI agents. All agents can assign an AI agent to a conversation and take a conversation over from it. In this page, `{account_id}` is the number of your account in the dashboard URL. ## The list of AI agents The **AI agents** page lists your AI agents. It is at `/app/accounts/{account_id}/hams-agent/agents`. To open it, click **AI** in the sidebar. Then click **Agents**. ![The AI agents page: each AI agent, its voice status, and the actions menu.](/_fern-img/2068075a9d51f41305c69e11754254a15d854cad515ef9f837bed0a56a56de52.webp) | Column | What it shows | | ----------- | ------------------------------------------------------------- | | **Name** | The name of the AI agent and its product name. | | **Voice** | **On** if the AI agent answers calls. **Off** if it does not. | | **Created** | When you created the AI agent. | | **Updated** | When the AI agent last changed. | To find an AI agent, type its name in **Search agents**. Click a row to open the AI agent in the editor. The actions menu of each row has **Edit**, **Duplicate**, and **Delete**. ## Create an AI agent #### Open the list Click **AI** in the sidebar. Then click **Agents**. #### Start an AI agent Click **New agent**. The editor opens on the **General** tab. #### Set the profile Under **Profile**, enter the **Name**, the **Product name**, and the **Description**. #### Write the instructions Under **Instructions**, write how the AI agent behaves and what it can say. #### Save the AI agent Click **Save**. The header shows **All changes saved**. #### Add knowledge and tools Open the **Documents**, **FAQ**, and **Tools** tabs. Give the AI agent content to answer from and actions to do. The instructions are necessary. If they are empty, **Save** shows **Instructions are required — they define the agent's persona.** You must save a new AI agent before you can use the **Documents**, **FAQ**, **Tools**, and **Scenarios** tabs. Until then, these tabs show **Save the agent first to manage this section.** ## The editor The editor is 1 page for all the settings of the AI agent. The switch at the top selects **Chat** or **Voice**. **Chat** has the settings for conversations. **Voice** has the settings for calls. See [Voice agents](/cloud-call-center/voice-agents). ![The General tab of the AI agent editor: the profile and the instructions.](/_fern-img/48e7c286c778b34a071a971fc549238254d58bcb2287fa3eef5c00c3acd2574f.webp) **Chat** has these tabs: | Tab | What it contains | | ------------- | ------------------------------------------------------------------------------------------------------------- | | **General** | **Profile**, **Instructions**, **Messages**, **When customers stop replying**, **Learning**, and **Tuning**. | | **Rules** | **Guardrails** and **Response guidelines**. | | **Documents** | The web pages and PDF files of the AI agent. See [Knowledge and documents](/omni-channel/ai-agent/knowledge). | | **FAQ** | The question and answer pairs of the AI agent. See [FAQ and responses](/omni-channel/ai-agent/faq). | | **Tools** | The actions that the AI agent can do. See [Tools](/omni-channel/ai-agent/tools). | | **Scenarios** | The sub-agents of the AI agent. See [Scenarios](/omni-channel/ai-agent/scenarios). | ### Save and discard The header shows the save state: **All changes saved** or **Unsaved changes**. 1 **Save** writes all the changes on the **General**, **Rules**, and **Tools** tabs and in the **Voice** settings. If 1 change is not valid, the system saves no change. To go back to the last saved version, click **Discard**. **Discard** shows only when an existing AI agent has unsaved changes. If you leave the editor with unsaved changes, the dialog **Discard unsaved changes?** opens. Click **Keep editing** to stay. Click **Discard changes** to leave without a save. Documents, FAQs, and scenarios save immediately when you add or change them. **Save** and **Discard** do not apply to them. To test the AI agent, click **Test**. With **Chat** selected, **Test** opens a test chat. With **Voice** selected, it opens a test call in your browser. See [Playground](/omni-channel/ai-agent/playground). ## The General tab | Section | What it controls | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Profile** | The **Name** of the AI agent, the **Product name** that it speaks for, and the **Description**. The description has a maximum of 200 characters. | | **Instructions** | The persona of the AI agent and how it behaves. The instructions have a maximum of 40,000 characters. | | **Messages** | The **Handoff message** and the **Resolution message**. | | **When customers stop replying** | What the AI agent does with a conversation after the customer stops replying. | | **Learning** | What the AI agent keeps from conversations, and if it can read the contact. | | **Tuning** | **Temperature** and **Reply delay (seconds)**. | Most problems with an AI agent come from the instructions. Write what the AI agent is for, what it can promise, and what it must not do, in plain sentences. For example: ```text You help customers of Acme Bikes with orders and returns. Do not give a refund amount. Transfer the conversation to a human agent instead. ``` An instruction such as `Be helpful and friendly` tells the AI agent nothing new. ### Variables in the instructions The instructions can contain live values of the conversation and the contact. Write a variable in double braces: ```text The customer is {{ contact.name }}. Their conversation number is {{ conversation.display_id }}. ``` | Object | Fields | | -------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `contact` | `id`, `name`, `email`, `phone_number`, `identifier`, `contact_type`, `custom_attributes`, `additional_attributes` | | `conversation` | `id`, `display_id`, `inbox_id`, `contact_id`, `status`, `priority`, `label_list`, `custom_attributes`, `additional_attributes` | To read a custom attribute, add its key, for example `{{ contact.custom_attributes.plan }}`. The `contact` variables have a value only when **Allow access to contact information** is on. When it is off, they are empty. Variables do not work on calls. If the instructions contain an error in the variable syntax, the AI agent uses the instructions without a change. ### Messages **Handoff message** and **Resolution message** each have a switch: * **Handoff message**: the message that the customer gets when the AI agent transfers the conversation to a human agent. * **Resolution message**: the message that the customer gets when the AI agent resolves the conversation. When the switch is on, the message has 2 fields: * **AI instructions (optional)**: the AI agent writes the message from these instructions. * **Static fallback message (optional)**: the system sends this text if the AI agent cannot write the message. If the switch is off, or both fields are empty, the customer gets no message. The handoff or the resolution still occurs. ### When customers stop replying This section sets what the AI agent does with a conversation that had no activity for a period. Select 1 option: | Option | What occurs | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Let the agent review it (recommended)** | After the time in **Review after**, the AI agent decides if the conversation is complete. It resolves a complete conversation. It transfers the other conversations to a human agent. | | **Always resolve** | After the time in **Resolve after**, the AI agent resolves every conversation. It does not review the conversation. | | **Wait for the customer** | The AI agent does not resolve the conversation. The conversation stays open with the AI agent until the customer replies. The AI agent can still transfer the conversation if the customer asks. | **Review after** and **Resolve after** have an hours field and a minutes field. The time is from 5 minutes to 24 hours, in steps of 5 minutes. The default is 1 hour. With **Always resolve**, the editor shows a warning. Some conversations that still need help can close. **Review instructions** shows only with **Let the agent review it (recommended)**. It contains the rules that the AI agent uses to decide if a conversation is complete. Edit them to fit your business. To go back to the default rules, click **Reset to default**. The system adds the role of the AI agent and the reply format to the rules. When the AI agent resolves a conversation after a review, it adds a private note that starts with `Auto-resolved:` and gives the reason. When it transfers the conversation, the private note starts with `Auto-handoff:`. The AI agent also sends the resolution message or the handoff message. The activity lines of these actions are in the language of your account. ![The settings for a conversation when the customer does not reply.](/_fern-img/38ae38979a5dc2871fe185b8cb4b4ec04912201deb13806a51b2b8061759eb1b.webp) ### Learning Under **Learning**, turn on the features that the AI agent can use: * **Generate FAQs from resolved conversations**. See [FAQ and responses](/omni-channel/ai-agent/faq). * **Capture key details as memories from customer interactions**. * **Allow access to contact information**. The AI agent can read the contact of the conversation. This feature is necessary for contact variables in the instructions. ### Tuning | Setting | What it controls | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Temperature** | How much the replies change. Lower values give more focused replies. Higher values give more creative replies. The default is 0.5. | | **Reply delay (seconds)** | How long the AI agent waits after a message of the customer before it replies. A customer who sends many messages in a row gets 1 reply. The value is from 0 to 5 seconds. The default is 5. Enter 0 to reply immediately. | ## The Rules tab | Section | What it controls | | ----------------------- | ---------------------------------------------------------------------- | | **Guardrails** | Limits that the AI agent must not go past, whatever the customer asks. | | **Response guidelines** | Short rules for the tone and the format of each reply. | Write 1 rule on each line. The system ignores empty lines. ## Duplicate an AI agent A copy starts with the settings, the tools, the scenarios, the FAQs, and the voice setup of the AI agent. #### Open the menu On the **AI agents** page, click the actions menu of the AI agent. #### Start the copy Click **Duplicate**. The **Duplicate agent** dialog opens. The **Name** is `Copy of` and the name of the AI agent. #### Name the copy Change the **Name** if necessary. #### Make the copy Click **Duplicate**. The copy opens in the editor. The copy does not get the documents. Add the sources again on the **Documents** tab of the copy. The FAQs that the system wrote from the documents stay in the copy. The copy does not answer calls. To let it answer calls, turn on voice for the copy. See [Voice agents](/cloud-call-center/voice-agents). ## Delete an AI agent > **Warning** > > Do not delete an AI agent that you still need. When you delete it, it stops replying in conversations, and the system deletes its documents and FAQs. You cannot undo this action. 1. On the **AI agents** page, click the actions menu of the AI agent. 2. Click **Delete**. 3. Click **Delete** again in the dialog. ## Assign an AI agent to a conversation An AI agent takes the assignee place of a conversation, as a person does. An AI agent can get a conversation in 2 ways: * In the conversation sidebar, select the AI agent in **Assigned AI Agent**. * A workflow with an **Assign to** node set to **Assign an AI agent**. See [Workflows](/omni-channel/workflows). When the AI agent gets the conversation, the system removes the human assignee. The status of the conversation does not change. Then the AI agent answers the message that waits. After that, it answers each new message of the customer. Automatic assignment does not give a conversation of an AI agent to a human agent. In the conversation list, the card of the conversation shows the name of the AI agent with a bot icon. A human assignee shows with a person icon. The AI agent replies only when the conversation is open or pending. It does not reply while a workflow runs on the conversation. It does not reply to X mentions, because mentions are not conversations. A call message does not count as a customer message. On a conversation that contains only calls, the AI agent answers the first message that the customer writes. When the status of the conversation changes to resolved or snoozed, the AI agent stops and the conversation has no AI agent. ### Activities of the AI agent The activity lines in the conversation give the name of the AI agent for the actions that it does. For example: * `Conversation was handed off by ` when the AI agent transfers the conversation. * `Conversation was marked resolved by ` when the AI agent resolves the conversation. * The activity line of a label or a priority that the AI agent changes. ### Take over from the AI agent While an AI agent has the conversation, the reply box shows **An AI teammate is handling this conversation. Take over to reply.** Agents can write private notes, but they cannot reply. To reply, click **Take over**. The system assigns the conversation to you and removes the AI agent. ### Handoff When the AI agent transfers a conversation, the **Handoff to Human** tool sets where it goes. Set **Assign the conversation to** on the **Tools** tab: | Mode | What occurs | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | **Inbox assignment policy** | The automatic assignment of the inbox selects an agent. If automatic assignment is off, the conversation stays unassigned. | | **A specific member or team** | The conversation goes to the **Member** or the **Team** that you select. | After each handoff, the conversation is open for a human agent, and the members of the inbox get a notification. The customer gets the handoff message in both modes. If the member is no longer in that inbox, or the team no longer exists, the inbox assignment policy applies. An activity line in the conversation gives the reason. The AI agent also transfers the conversation to a human agent in these cases: * The reply window of the channel closes. For example, WhatsApp accepts a free-form reply only in the 24 hours after the last message of the customer. * The account has no AI credit left. * The AI agent cannot write a reply because of an error. A private note says `⚠️ AI error: the automated reply could not be generated, so this conversation was handed off for manual follow-up.` ## How the AI agent replies On WhatsApp and Telegram, the chat of the customer shows an indicator while the AI agent writes a reply. On WhatsApp, this works for the providers **WhatsApp Cloud** and **Quick setup with Meta**. The AI agent reads the history of the conversation before each reply. It reads a maximum of the last 100 messages, and a maximum of about 40,000 characters. Private notes are not in the history. If an earlier conversation cycle ended with a resolution, the AI agent knows that the messages before that point belong to a closed cycle. See [Conversation cycles](/omni-channel/conversation-cycles). A call in the conversation shows to the AI agent as its direction, its status, and its duration. If the call has a transcript, the AI agent also reads the transcript. The AI agent does not see failed calls. See [Phone calls](/omni-channel/voice). These rules also apply to each reply: * If a human agent already answered the last message of the customer, the AI agent does not reply. * If the customer sends a new message while the AI agent writes a reply, the AI agent drops that reply. Then it answers again with the new message. The tools of the dropped reply do not run. * If the upload of a file in a message of the customer is not complete, the AI agent waits for the file. * A reply fits the maximum message length of the channel. If a reply is too long, the AI agent makes it shorter. If it is still too long, the AI agent transfers the conversation to a human agent. | Channel | Maximum length of 1 reply | | ------------------ | ------------------------- | | Facebook | 2,000 characters | | Instagram | 1,000 characters | | LINE | 5,000 characters | | SMS and Twilio SMS | 320 characters | | Telegram | 4,096 characters | | TikTok | 6,000 characters | | WhatsApp | 4,096 characters | | Twilio WhatsApp | 1,600 characters | | Other channels | 10,000 characters | ### See how a reply was generated Administrators see **Generated by AI** under each message of an AI agent. Click it to open **How was this reply generated?**: | Item | What it shows | | -------------------- | -------------------------------------------------------------------------------------- | | **Generation steps** | The tools that the AI agent called, with their input, and each transfer to a scenario. | | **Knowledge used** | The documents and the FAQs that gave the facts for the reply. | | **Reasoning** | Why the AI agent wrote the reply. | | **Credits** | The AI credits that the reply used. | Agents do not see **Generated by AI**. ![The panel that shows how the AI agent generated a reply.](/_fern-img/a539c97cf43811d11060c040fa43e2acd3032cd844102515de9ef21ac507dedd.webp) ## Filter by AI agent To see the conversations of an AI agent, use the conversation filter **AI agent**. This is a fast way to review the work of an AI agent. ## Related * [Tools](/omni-channel/ai-agent/tools) * [Knowledge and documents](/omni-channel/ai-agent/knowledge) * [Scenarios](/omni-channel/ai-agent/scenarios) * [Playground](/omni-channel/ai-agent/playground) * [AI agent reports](/omni-channel/ai-agent/reports) * [Voice agents](/cloud-call-center/voice-agents) * [Workflows](/omni-channel/workflows)