Tutorials for CALM assistants

This tutorial is designed for those new to Rasa and virtual assistants. It covers essential techniques that are fundamental to creating any Rasa Studio assistant. Understanding these basics will greatly facilitate your progress in mastering Rasa Studio.

You will build a CALM-based assistant that greets users, introduces itself, and assists with money transfers.

Part 1: Creating an assistant#

1. Log in with either the developer or flowbuilder role.

2. Click the assistant dropdown and select "Create assistant project."

   

3. Fill in the details:

   1. Enter a unique assistant name, such as transfer_money_assistant, reflecting the purpose of facilitating money transfers.

   2. Leave "Modern" as the mode.

   3. Finally, click the "Create assistant" button.

   

Configuration#

1. After creating the assistant, navigate to the "Assistant Settings" page.

   

2. Click on the "Configuration" tab to access the config.yml and endpoints.yml files.

Here you can find two .yml files that you can edit to configure your assistant: config.yml and endpoints.yml. Also, there is a dropdown to select the flows that will always be included in the prompt.

These files contain the configuration for the NLU and Core models, as well as the endpoints used by Rasa.

Some of the most common configurations you might want to adjust are:

• add or remove components from the pipeline,
• change the policies used for training,
• configure the endpoints for the tracker store, event broker, and NLG server.

Part 2: Creating Welcome flow#

One of the key concepts in Rasa's CALM (Conversational AI with Language Models) is a flow. A flow represents a series of steps that guide the user through a conversation. Think of it as a conversation tree, where each step helps the assistant figure out what to say or do next based on what the user says.

Now, let's create your first flow:

1. Navigate to the Flows page through the tab in the menu.

2. Click "Create flow" to begin crafting your welcome flow.

   

3. Enter the flow name, such as welcome. In the Description field, clearly state the flow's objective, like "Greet user and introduce yourself". The flow description is crucial because it helps Rasa know when to trigger a specific flow. For example, if a user says "Hi!", CALM checks all the flow descriptions and conversation context to match the input with the most relevant flow. If the flow description is something like "Greet the user," CALM will activate the “welcome” flow. If no suitable flow matches, CALM may not trigger any flow.

   

4. Your flow is created. Click on it to start building.

   

5. Flows start with the "Start" step, which is where you configure how the flow gets triggered. By default, it will be triggered by CALM based on the description you provided. This works for us, so you can leave it as is for now.

   

6. Click the "Plus" icon to add a step. From the dropdown menu, select "Message" to have your assistant send a text message to the user.

   

7. Choose "Create message" from the dropdown menu on the top of the side panel.

   

8. Fill in the details:

   1. Enter the name, e.g greet.
   2. Enter the message e.g "Hello! I’m your assistant, created with Rasa Studio. I’m here to help you with money transfers".
   3. Leave the checkbox "Use Contextual Response Rephraser" checked if you want the message to be rephrased based on the conversation's context.
   4. Once you're set, click "Save".
   

Part 3: Creating Money Transfer flow#

Let’s now build another flow to help users in conducting money transfers, allowing CALM to activate this process when users inquire about sending money. To do it:

1. Return to the flow list and click "Create flow".

   

2. Name your flow money_transfer and add the description: "Ask all the required questions to process a money transfer request from users." Click "Save."

   

3. Click on the newly created flow to proceed with building it.

   

Collecting information about the recipient#

1. Create the "Collect Information" step to ask the user who the recipient of the transfer will be.

   

2. Instruct the assistant on what information to collect in this step by filling out the "Description" field. For example, "This step inquires about the recipient of the payment."

   

3. To define the specific information the assistant should collect from the user's reply, you'll need to create a slot. Slots function as your bot's memory, acting as a key-value store to hold information provided by the user (like the name or address of the recepient) or gathered from external sources (like the result of a database query). To create a slot, click on the "Select or create slot" field and choose "Create slot."

   

4. Input recipient as a slot name. Then select Text as type—a text slot stores information like personal names, countries, cities, etc. While you can provide an initial value for any slot, it's not applicable in this scenario. Learn more about slot types.

   

5. Finally, generate a message that the assistant will use to collect this information from the user. To do this, click "Create message".

   

6. The system will automatically fill in the message name by combining the slot name with the prefix utter_ask, resulting in utter_ask_recipient. Enter the message content as "Who would you like to send money to?"

   

7. Decide whether to check the "Use contextual response rephraser" box. If you leave it unchecked, the assistant will always use the exact same wording. If you check it, the message will vary slightly each time, depending on the conversation context, making it sound more natural. Learn more.

   

8. If you prefer full control over responses or don’t want to use an LLM, you can manually create message variations by unselecting the "Rephraser" option and clicking the "Add variation" button.

   

9. Add as many variations as you'd like, then click "Save". During the conversation, Rasa will randomly pick one of them.

   

10. By default, a "Collect Information" step can be skipped if the slot is already filled. For example, if a user says, "I want to transfer money to John" at the beginning of the conversation, the assistant will recognize John as the recipient and won't ask for the name again. If you want the assistant to always ask the question, even if the slot is already filled, enable the "Ask before filling" option. In this particular case, we recommend to leave it disabled.

    

11. The "Reset slot value" option clears the slot after the flow's final steps, prompting the question again in future sessions. This is useful for slots like transfer_amount or recipient_name, which can change each session. In this particular case, we recommend leaving the "Reset slot value" option enabled.

    

Collecting information about the amount#

1. Add one more "Collect information" step to ask the user about the amount of transfer.

   

2. Enter the description: "This step inquires about the amount of the payment, in US Dollars".

   

3. Create a new slot.

   

4. Input amount as the slot name. Then select Float as type — it is employed for storing numerical values that can have decimal points. Click "Save".

   

5. Finally, generate a message that the assistant will use to collect this information from the user. To do this, click "Create message".

   

6. The system will automatically fill in the message with utter_ask_amount. For the message content, you might use "How much money would you like to send (in US Dollars)?"

   

7. You can optionally add buttons to give users structured choices, making it easier for them to quickly select an answer. To do this, click "Add buttons".

   

8. In the modal that opens, enter a button title, e.g., "50". You can leave the Payload field empty.

   

9. Click "Add another button" to add more options, such as 500, 1000, 1500, etc. Don’t forget to save your buttons and the message when you're done.

   

10. Leave "Ask before filling" option disabled. If a user starts the conversation with "I want to transfer 50 dollars", the assistant will already fill the slot and won't to ask for the amount again. Also leave "Reset slot value" enabled to ensure that the next time a user requests a money transfer, the assistant will ask for the amount again.

    

Verifying if funds are sufficient#

In this step, we aim to verify whether the user has sufficient funds for the transfer. Ideally, this is done using a custom action (API call) to check the user's balance and return a response. However, for the first part of the tutorial, we'll use Logic to mock the result of this custom action.

1. Add a "Logic" step. This type of step allows you to branch the flow based on a condition.

   

2. Define the condition for sufficient funds. Click on the first logic branch to create a scenario where the transaction amount is less than or equal to $1000. If the transaction amount is less than the available funds, it indicates sufficient funds are available. Select the first condition and set it to amount is less than or equal 1000.

   

3. For cases where the user does not have enough funds, the "Else" logic branch will be activated. In this case, we need to notify the user that the transfer amount is insufficient. To do so, add a "Message" step after the "Else" branch.

   

4. Create the message. Name it insufficient_funds and add the text "You don't have sufficient funds to complete this transaction". Click "Save."

   

Confirming the request#

If the user has sufficient funds, we can proceed to the next step: verifying the transfer details.

1. After the first condition, add the "Collect information" step.

   

2. Add the description "This step asks the user to confirm the recipient and the transfer amount".

   

3. Create a slot and call it final_confirmation. Since you are asking a Yes or No question, you can store the result as a Boolean type. Click "Save".

   

4. Create a new assistant message, which will be automatically named utter_ask_final_confirmation. Enter the message "Please confirm that you want to transfer {amount} to {recipient}." We use curly brackets to reference slot values, so the amount and recipient saved from previous questions will be inserted here.

   

5. Enable "Ask before filling" so that with the next transfer, the assistant will not automatically fill this slot and will ask for confirmation again.

   

6. After the "Collect information", add the "Logic" step.

   

7. For the scenario where the user confirms the request (first logic branch), enter the following details: final_confirmation is True.

   

8. The Else branch will automatically cover any other scenarios, such as the user denying the transfer or sending messages outside of the flow's business logic.

Displaying success and cancel messages#

If the user confirms the transaction request, we'll provide a success message.

1. After the final_confirmation is true branch, add the "Message" step.

   

2. Create a new message named transfer_successful with the text "All done. {amount} USD has been sent to {recipient}".

   

3. For the Else branch, also add the "Message" step.

   

4. Create a new message. Name it cancel_transfer and add the text "Transfer canceled". Click "Save".

   

Linking to Feedback flow#

Let's now ask users to leave feedback on the assistant's performance. For a complex assistant, this feedback logic can be reused in multiple scenarios, so it makes sense to separate it into a different flow.

1. Add a “Link” step after both “Transfer successful” and “Transfer canceled” messages. This step links flows together by ending the current flow and starting the target one.

   

2. In one of those Link steps, select "Create flow" in the dropdown.

   

3. Name the new flow leave_feedback. Enter the description: "This flow collects user feedback on a scale from 1 to 5."

   

4. Select the same flow in another Link step.

   

Part 4: Building Feedback flow#

1. Go to the leave_feedback flow that you’ve just created. You can do this by clicking on the "Open the flow in a new tab" link.

   

2. We don't want the user to see the feedback flow out of nowhere and want it to only be triggered after particular operations with the assistant. To add this restriction, let's use Flow guards. Flow guards help you start the flow only if specific conditions are met, preventing automatic triggering with CALM or intents. To add a flow guard, select the "Start" step. This is where you configure how the flow can be started. Click on the "Flow guards" section.

   

3. Select "Start the flow exclusively via links". This setting will ensure that this flow won't be started automatically by the LLM and will only be initiated after the "Link" step in the transfer_money flow.

   

4. Now we can proceed to building the flow. Add the “Collect Information” step to ask the user if they want to leave feedback. Fill it with the following details:

   1. Add the step description "Ask user to leave feedback".
   2. Create a slot named feedback with a Boolean type, as it's a yes or No question.
   3. Add an assistant's message with the name utter_ask_feedback and the text "Do you want to leave feedback?"
   4. The result should look like this:
   

5. Following this question, insert the "Logic" step.

   

6. Set the first logic branch to feedback is true. If the user is willing to leave feedback, the conversation will follow this branch.

   

7. After the Else branch — the case when the user doesn’t want to leave feedback — add the "Message" step.

   

8. Name the new message goodbye and add the text "Thank you and have a great day!"

   

9. After feedback is true branch, add the “Collect information” step.

   

10. Enter the description: "Ask users to rate the assistant's performance".

    

11. Create a new slot named rating and use Float as a type, as we’ll accept the number from 1 to 5.

    

12. Create a new message automatically named utter_ask_rating and add the text "How would you rate my performance from 1 to 5?".

    

13. Optionally you can add buttons so user could easily pick the answer.

    

Your simple assistant is ready!

Part 5: Training and testing the assistant#

Training and testing a model are fundamental steps in developing an assistant. Studio users can directly train their assistant within the user interface. To train your assistant:

1. Go to the flow list and select the "Ready for training" switch for all of the flows that you have created and consider ready.

   

2. Click the "Train" button.

   

3. First, Studio will validate all your flows. If there are errors that could lead to training failures, you will see the "Unable to train" message. You can navigate through the list of flows with errors by clicking on their names. Once all errors are corrected, you can try to train the assistant again.

   

4. Once the training has started, you will see the following message:

   

5. If the training process encounters an issue or fails, the following message will appear. You can download training log and investigate the reason for the failure.

   

6. In the event of a successful model training, you will see the green tick and the following message:

   

7. After successful training, go to "Try your assistant" page to test how well the assistant navigates between your flows and provides the correct answers.

   

Part 6 [Advanced]: Adding a custom action#

A Custom action step can execute any code you desire, including API calls, database queries, and more. Whether it's turning on the lights, adding an event to a calendar, checking a user's bank balance, or anything else you can imagine, custom actions offer extensive flexibility.

As of now, custom actions can only be implemented outside of Studio. For details on how to implement a custom action, please refer to the SDK Action Server docimentation. Any custom action that you want to use in flows should be added into the actions section of your domain.

In this part of the tutorial, we are going to replace the previously created amount validation logic with a custom action.

1. Return to the money_transfer flow.

2. After the question about how much money you would like to transfer and before the logic branch, add a "Custom action" step.

   

3. Open the custom action dropdown and click "Create custom action."

   

4. Enter the name action_validate_sufficient_funds and a description: "Goal: Validate whether the funds are sufficient for the transfer. Requirement: Check if the slot amount is greater than 1000. If true, return a true value for the slot has_sufficient_funds. If false, return a false value for the slot has_sufficient_funds."

   

5. Select the first logic branch, the one labeled amount is less_or_equal 1000. We’ll need to replace this with validation from the custom action. Instead of amount, create a new slot.

   

6. Enter slot name has_sufficient_funds. Select Boolean as a type and click "Save".

   

7. Set the condition so that has_sufficient_funds is true.

   

8. Switch to an IDE to set up your own Rasa Action Server.

   To do this, you need Rasa Pro 3.7.0 or newer.

   Create a local Rasa project

   Copy

   rasa init --template calm

9. Implement the custom action that validates the amount of funds. You can copy/paste the following Python code in actions/actions.py:

   Copy

   # These files contains your custom actions which can be used to run

   # custom Python code.

   #

   # See this guide on how to implement these action:

   # https://rasa.com/docs/rasa/custom-actions

   from typing import Any, Text, Dict, List

   from rasa_sdk import Action, Tracker

   from rasa_sdk.executor import CollectingDispatcher

   from rasa_sdk.events import SlotSet

   class ActionValidateSufficientFunds(Action):

   def name(self) -> Text:

   return "action_validate_sufficient_funds"

   def run(self, dispatcher: CollectingDispatcher,

   tracker: Tracker,

   domain: Dict[Text, Any]) -> List[Dict[Text, Any]]:

   # hard-coded balance for tutorial purposes. in production this

   # would be retrieved from a database or an API

   balance = 1000

   transfer_amount = tracker.get_slot("amount")

   has_sufficient_funds = transfer_amount <= balance

   return [SlotSet("has_sufficient_funds", has_sufficient_funds)]

10. Run action server using Rasa CLI.

    Copy

    rasa run actions

11. Use a reverse proxy like ngrok to expose the action server running on your local machine to the public internet and pass this to Studio for training. This can help you with quick prototyping & testing. Optionally you can also deploy this action server in your chosen cloud environment and pass the public URL to Studio to connect with your assistant.

    Copy

    ngrok http 5055

12. You can provide the URL + /webhook in Assistant Settings - Configuration - Action Endpoint:

    

13. Train and test your assistants again, as described in Part 5.

Part 7: Editing YAML files [Advanced]#

1. Download YAML files from Studio via Rasa CLI.

   To do this, you need Rasa Pro 3.7.0 or newer. We recommend the latest Rasa Pro in order to use the latest features and improvements. Starting from Rasa Pro 3.9.8, you can download endpoint and config files as well.

   Note: Make sure you pass the value for studio-url, realm-name and client-id based on variables used during your Studio deployment

   Create a new folder

   Copy

   mkdir my-assistant-name

   cd my-assistant-name

   Configure CLI to connect to Studio

   Copy

   rasa studio config

   Provide the Studio URL to configure the connection.

   Log in to Studio as a developer

   Copy

   rasa studio login

   Provide the credentials of the user belonging to the developer group.

   Download assistant by assistant-name

   Run the below command to download the assistant files.

   Copy

   rasa studio download <my-assistant-name>

   This will download the assistant's files to the current directory. The default directory structure will look like this:

   Copy

   |-endpoints.yml

   |-config.yml

   |-domain.yml

   |-data

   | |-studio_flows.yml

   | |-studio_nlu.yml

   Run rasa studio download --help to see the full list of arguments.

2. Apply changes, you can’t apply in Studio but only in YAML:

   • view Tracing (Observability)
   • add IVR Channel with AudioCodes
   • run End-to-End Test
   • use Secrets Management
   • use PII Management
   • add markers
   • use Custom Information Retrieval
   • add Conversation Tracking
   • add Generation prompt in flow.yml

3. Train the rasa model locally using rasa CLI.

   Copy

   rasa train

4. Test your assistant with custom action using Rasa Inspector.

   Copy

   rasa inspect