> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/docs/automation/custom-instructions/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Custom Instructions > **Tip** > > **Not sure where to begin?** Explore our [Getting started](/docs/welcome/getting-started) guidelines to set up your first AI Agent, review [Key concepts](/docs/welcome/key-concepts) to understand the essentials, or check out [Improvement tactics](/docs/welcome/improvement-tactics) to resolve issues and keep things running smoothly. ## Overview Custom Instructions let you customize your AI Agent's behavior by adding rules that guide how it speaks to end users. Custom Instructions provide flexibility to shape your AI Agent's responses while working within defined constraints. ## Limitations Custom Instructions have the following constraints. * You can have up to 10 active Custom Instructions in your AI Agent. In addition to these active Custom Instructions, you can also have inactive drafts that you're working on. > **Note** > > You may see as many as 40 active Custom Instructions if your AI Agent was created before January 7, 2025. This state will be expected if your AI Agent previously relied upon the older version of Custom Instructions, Guidance. Please note that AI Agents in this state will continue to work as expected, however you can improve performance by [re-creating your contextual Custom Instructions as Coaching.](/docs/optimization/coaching/coaching-tools) * Each Custom Instruction can be up to 300 characters long. * Your Custom Instructions must be in English. Additionally, keep the following in mind to ensure that your Custom Instructions perform well: * Make sure your Custom Instructions don't conflict with each other. For example, you could have two Custom Instructions to tell end users about both a spring and summer sale. If both of them are live at the same time, you can't guarantee that the correct Custom Instruction will apply when an end user is talking with your AI Agent. * The AI Agent notifies you if a newly added Custom Instruction conflicts with any existing Custom Instruction. ## Use cases Custom Instructions help you shape your AI Agent's behavior and communication style. * **Response style guidelines**: Define how your AI Agent should communicate, such as maintaining a formal tone or avoiding certain phrases. * **Promotional messaging**: Instruct your AI Agent to mention current sales, promotions, or announcements during conversations. * **User-specific rules**: Apply different instructions based on end user attributes, such as providing premium support messaging only to VIP customers. ## Capabilities & configuration Custom Instructions support the following options. * **Availability rules**: Apply Custom Instructions to all end users or restrict them to specific users based on variable conditions. * **Draft mode**: Save Custom Instructions as drafts to refine them before publishing. * **Testing**: Test Custom Instructions in a chat window before making them active. * **Conflict detection**: The AI Agent notifies you if a new Custom Instruction conflicts with an existing one. * **Active/inactive toggle**: Publish or unpublish Custom Instructions at any time. ## Quick start Get a Custom Instruction up and running in minutes. **To add a Custom Instruction:** On the Ada dashboard, go to **Config > AI AGENT > Settings**, then on the **Custom instructions** tab, click **New custom instruction**. Enter a **Title** and add your **Instruction**. Under **Set availability**, select **Everyone**. Enable the toggle at the top of the page to publish. Your AI Agent immediately starts applying the Custom Instruction when generating responses. For more options, including restricting Custom Instructions to specific users, see [Create a Custom Instruction](#create-a-custom-instruction). ## Implementation & usage Create, manage, and review Custom Instructions to control how your AI Agent communicates with end users. ### Create a Custom Instruction As soon as you publish a Custom Instruction, your AI Agent can start considering it when generating responses to end users. If required, you can restrict Custom Instructions to certain users, based on information your AI Agent collects about your users and saves in variables. > **Note** > > You can only use variables your AI Agent can collect through your browser, or that you collect in a block and allow to be available outside of the structured content the block is in. You can't use variables your AI Agent collects using Actions. **To add a Custom Instruction:** 1. On the Ada dashboard, go to **Config > AI AGENT > Settings**, then on the **Custom instructions** tab, click **New custom instruction**. The **Add Custom Instruction** page opens. 2. Under **Title**, add a title for your new Custom Instruction. 3. Under **Instruction**, add the new rule you want your AI Agent to follow. 4. Under **Set availability**, choose which end users you want the Custom Instruction to apply to. * To make the Custom Instruction available to all users, select **Everyone**. * To restrict the Custom Instruction to certain users, select **Based on the following rules**. A section expands where you can enter the logic your AI Agent uses to decide whether to apply the Custom Instruction. 1. Under **Where**, in the **Choose a variable** list, select a variable. 2. In the next dropdown, select an operator so you can define a relationship between the variable and the value you want to target. #### Understand comparison operators Comparison operators are logic statements that tell your AI Agent to match end user information that's captured in the variable you're using. The available operators vary based on the variable type you're using: | **Operator** | **Variable types** | **Description** | | :---------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- | | ![Begins With icon](/_fern-img/e8b9c807586a4238654793da51b49ec15e7045c0691d461567178070e57a1840.webp) **Begins With** | - All text variables (including phone and email) | Match information in the variable that begins with certain text (partial match). | | ![Ends With icon](/_fern-img/9bc404d3db5ea684a901bf8426485894bb62abb8369e498b98dc4e4f3807a5ec.webp) **Ends With** | - All text variables (including phone and email) | Match information in the variable that ends with certain text (partial match). | | ![Contains icon](/_fern-img/a4f0225811b1ecde2f125de907c2ad1b084268805cd89a00f465649ddbf8eaa2.webp) **Contains** | - All text variables (including phone and email)- List variables | Match information in the variable that contains certain text in any position (partial match). | | ![Is icon](/_fern-img/7266dedcf2da1af5c496469379bd4fb68d5e65492c190e9567c75edbbbf7e260.webp) **Is** | - All text variables (including phone and email) - Number variables | Match information in the variable that equals specific text exactly (exact match). | | ![Is Not icon](/_fern-img/d94952ab65e9f266413c582390a1d702ebb32c7a2023709ee96741b6df1b17e4.webp) **Is Not** | - All text variables (including phone and email) - Number variables | Match information in the variable that does not equal specific text exactly (exact match). | | ![Is Not Set icon](/_fern-img/283cad3d89c7d92f279d722592cd958630a40527266a47d316ab3b3b2051b71f.webp) **Is Not Set** | - All text variables (including phone and email) - Number variables - List variables | Match if there is no information contained in the variable. | | ![Is Set icon](/_fern-img/8c1019797a0482018682d52622c9e2fe56ddc5aef8925dc3e3db678c121c6869.webp) **Is Set** | - All text variables (including phone and email) - Number variables - List variables | Match if there is any information contained in the variable. | | ![Greater Than icon](/_fern-img/45636711dfe933087353da3923c6865b6816ea671ad6e9db4739aeea4c80a697.webp) **Greater Than** | - Number variables | Match if the information in the variable is greater than a specific value. | | ![Less Than icon](/_fern-img/f2448b33a8931270e63ea8daab74e67ade1fdfdf1f8853529c2fb0a3e5abda55.webp) **Less Than** | - Number variables - List variables | Match if the information in the variable is less than a specific value. | | ![Is True icon](/_fern-img/fcf3fe21099df957ee22609d5a5c211601d3e402fcc8402c12115f4680a692b0.webp) **Is True** | - Yes/No variables | Match if the information in a variable is Yes (or True). | | ![Is False icon](/_fern-img/2b5c661e7e4445f1ea8f7736ee5b58b14f72283faf2dbd4f01220a26d621b238.webp) **Is False** | - Yes/No variables | Match if the information in a variable is No (or False). | | ![Does Not Contain icon](/_fern-img/2a459cf7a992abeb5cbdf8438f9f1be356bb5fcf915f55f7f1c2cdc3173b101d.webp) **Does Not Contain** | - List variables | Match if none of the selected items contains this value. | | ![Is Equal To icon](/_fern-img/7266dedcf2da1af5c496469379bd4fb68d5e65492c190e9567c75edbbbf7e260.webp) **Is Equal To** | - List variables | Match if the end user selected a particular number of options in a List Option block. | | ![Is Greater Than icon](/_fern-img/45636711dfe933087353da3923c6865b6816ea671ad6e9db4739aeea4c80a697.webp) **Is Greater Than** | - List variables | Match if the end user selected more than a particular number of options in a List Option block. | | ![Is Less Than icon](/_fern-img/f2448b33a8931270e63ea8daab74e67ade1fdfdf1f8853529c2fb0a3e5abda55.webp) **Is Less Than** | - List variables | Match if the end user selected fewer than a particular number of options in a List Option block. | 6. In the **Value** field, enter or select a value for the variable that you want to use to target users. 7. If required, add additional conditions. * To add a new **top-level** condition, click **Add** ![](/_fern-img/b0aa6bd9ade574c33763556b72bedb3fb7ba2384bf0c25ef6cc5401eab220757.webp). If you're adding your first additional top-level condition, in the dropdown that appears, choose **And** or **Or** as the operator for all of your top-level conditions. * To create or add to a **group** of conditions, click the **Add to group** icon ![](/_fern-img/881a5902ee010bd99b16914b2ac663810ad93cade88c2fddc273b4c3bc508b28.webp) beside a condition you want to include in the group. If you're creating a group, in the dropdown that appears, choose **And** or **Or** as the operator for all of the conditions in that group. 5. To save your new Custom Instruction as a draft, click **Save**. If you save it as a draft, it won't affect your AI Agent content until you publish it. 6. To test your new Custom Instruction, click **Test**. A chat window opens, where you can type prompts and test whether the Custom Instruction returns the kinds of responses you want, even if it's still a draft. If you haven't saved your Custom Instruction yet, testing it saves it as a draft. > **Note** > > If your new Custom Instruction conflicts with any existing Custom Instruction, your AI Agent notifies you when you click **Test**. Conflicts are checked against both active and inactive Custom Instructions. 7. To publish your Custom Instruction, at the top of the page, enable the toggle (changing it from **Inactive** to **Active**). Your AI Agent starts using your new Custom Instruction in the responses it writes to end users. ### View in Conversations You can review which Custom Instructions were considered during past [Conversations](/docs/optimization/conversations). On the Ada dashboard, when you go to **Conversations**, you can see transcripts of Conversations that end users have had with your AI Agent. In the **Details** pane, under **Custom instruction considered**, you can see a list of Custom Instructions that were active at the time of any given Conversation, and use that information to fine-tune your Custom Instructions. For more information, see [Improve your AI Agent's responses by viewing past Conversations](/docs/optimization/conversations/response-training). ### Edit or delete Custom Instructions\[#update-delete-guidance] You can modify or remove a Custom Instruction at any time. **To edit or delete a Custom Instruction:** 1. On the Ada dashboard, go to **Config > AI AGENT > Settings**, then open the **Custom instructions** tab. 2. Click the Custom Instruction you want to manage. The **Edit Custom Instructions** page opens. 3. Make your required changes to the Custom Instructions * You can edit the existing Custom Instruction and then click **Save** to update it and keep it active. * You can click **Convert to draft** to stop an active piece of Custom Instruction from affecting end user Conversations, without deleting the Custom Instruction from your AI Agent. * You can make changes to the piece of Custom Instruction and then click **Test** to try it out in a conversation. Testing a Custom Instruction automatically saves it, but doesn't change whether it's a draft or active. * You can click the **Delete** button ![](/_fern-img/0a157919e7d474dfc5dd172698eb0e3c0c25ee947f5d6bf8e8fe6a1dfa68048e.webp) to permanently delete the Custom Instruction from your AI Agent. ### Manage Custom Instruction availability\[#availability] You can select multiple Custom Instructions and quickly change whether they're available to all of your users, to only some of them, or delete your selected Custom Instructions altogether. **To change availability for multiple Custom Instructions:** 1. On the Ada dashboard, go to **Config > AI AGENT > Settings**, then open the **Custom instructions** tab. 2. Select the Custom Instructions you want to manage. Some options appear at the bottom of your screen: * To make the selected Custom Instructions available to only **some** of your users, click **Set availability**. The **Set Availability** window opens. * To make the Custom Instruction available to all users, select **Everyone**. * To restrict the Custom Instruction to certain users, select **Based on the following rules**. A section expands where you can enter the logic your AI Agent uses to decide whether to apply the Custom Instruction. 1. Under **Where**, in the **Choose a variable** list, select a variable. 2. In the next dropdown, select an operator so you can define a relationship between the variable and the value you want to target. #### Understand comparison operators Comparison operators are logic statements that tell your AI Agent to match end user information that's captured in the variable you're using. The available operators vary based on the variable type you're using: | **Operator** | **Variable types** | **Description** | | :---------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- | | ![Begins With icon](/_fern-img/e8b9c807586a4238654793da51b49ec15e7045c0691d461567178070e57a1840.webp) **Begins With** | - All text variables (including phone and email) | Match information in the variable that begins with certain text (partial match). | | ![Ends With icon](/_fern-img/9bc404d3db5ea684a901bf8426485894bb62abb8369e498b98dc4e4f3807a5ec.webp) **Ends With** | - All text variables (including phone and email) | Match information in the variable that ends with certain text (partial match). | | ![Contains icon](/_fern-img/a4f0225811b1ecde2f125de907c2ad1b084268805cd89a00f465649ddbf8eaa2.webp) **Contains** | - All text variables (including phone and email)- List variables | Match information in the variable that contains certain text in any position (partial match). | | ![Is icon](/_fern-img/7266dedcf2da1af5c496469379bd4fb68d5e65492c190e9567c75edbbbf7e260.webp) **Is** | - All text variables (including phone and email) - Number variables | Match information in the variable that equals specific text exactly (exact match). | | ![Is Not icon](/_fern-img/d94952ab65e9f266413c582390a1d702ebb32c7a2023709ee96741b6df1b17e4.webp) **Is Not** | - All text variables (including phone and email) - Number variables | Match information in the variable that does not equal specific text exactly (exact match). | | ![Is Not Set icon](/_fern-img/283cad3d89c7d92f279d722592cd958630a40527266a47d316ab3b3b2051b71f.webp) **Is Not Set** | - All text variables (including phone and email) - Number variables - List variables | Match if there is no information contained in the variable. | | ![Is Set icon](/_fern-img/8c1019797a0482018682d52622c9e2fe56ddc5aef8925dc3e3db678c121c6869.webp) **Is Set** | - All text variables (including phone and email) - Number variables - List variables | Match if there is any information contained in the variable. | | ![Greater Than icon](/_fern-img/45636711dfe933087353da3923c6865b6816ea671ad6e9db4739aeea4c80a697.webp) **Greater Than** | - Number variables | Match if the information in the variable is greater than a specific value. | | ![Less Than icon](/_fern-img/f2448b33a8931270e63ea8daab74e67ade1fdfdf1f8853529c2fb0a3e5abda55.webp) **Less Than** | - Number variables - List variables | Match if the information in the variable is less than a specific value. | | ![Is True icon](/_fern-img/fcf3fe21099df957ee22609d5a5c211601d3e402fcc8402c12115f4680a692b0.webp) **Is True** | - Yes/No variables | Match if the information in a variable is Yes (or True). | | ![Is False icon](/_fern-img/2b5c661e7e4445f1ea8f7736ee5b58b14f72283faf2dbd4f01220a26d621b238.webp) **Is False** | - Yes/No variables | Match if the information in a variable is No (or False). | | ![Does Not Contain icon](/_fern-img/2a459cf7a992abeb5cbdf8438f9f1be356bb5fcf915f55f7f1c2cdc3173b101d.webp) **Does Not Contain** | - List variables | Match if none of the selected items contains this value. | | ![Is Equal To icon](/_fern-img/7266dedcf2da1af5c496469379bd4fb68d5e65492c190e9567c75edbbbf7e260.webp) **Is Equal To** | - List variables | Match if the end user selected a particular number of options in a List Option block. | | ![Is Greater Than icon](/_fern-img/45636711dfe933087353da3923c6865b6816ea671ad6e9db4739aeea4c80a697.webp) **Is Greater Than** | - List variables | Match if the end user selected more than a particular number of options in a List Option block. | | ![Is Less Than icon](/_fern-img/f2448b33a8931270e63ea8daab74e67ade1fdfdf1f8853529c2fb0a3e5abda55.webp) **Is Less Than** | - List variables | Match if the end user selected fewer than a particular number of options in a List Option block. | 6. In the **Value** field, enter or select a value for the variable that you want to use to target users. 7. If required, add additional conditions. * To add a new **top-level** condition, click **Add** ![](/_fern-img/b0aa6bd9ade574c33763556b72bedb3fb7ba2384bf0c25ef6cc5401eab220757.webp). If you're adding your first additional top-level condition, in the dropdown that appears, choose **And** or **Or** as the operator for all of your top-level conditions. * To create or add to a **group** of conditions, click the **Add to group** icon ![](/_fern-img/881a5902ee010bd99b16914b2ac663810ad93cade88c2fddc273b4c3bc508b28.webp) beside a condition you want to include in the group. If you're creating a group, in the dropdown that appears, choose **And** or **Or** as the operator for all of the conditions in that group. * To make the selected Custom Instructions available to **none** of your users, click **Set as inactive**. * To make the selected Custom Instructions available to all of the users configured in its availability settings, click **Set as active**. * To delete the selected Custom Instructions, click **Delete**. ## Related features Extend your AI Agent's behavior with complementary capabilities. * [Coaching](/docs/optimization/coaching): Provide contextual guidance to help your AI Agent handle specific topics or scenarios more effectively. --- Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).