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#

Rasa's CALM (Conversational AI with Language Models) approach simplifies building AI assistants using Dialogue Understanding, that translates what users are saying into what that means for your business logic. This logic is represented through flows, outlining steps for tasks such as collecting user information, retrieving data from API or a database, and branching logic based on the information you collect. Unlike traditional NLU approach, CALM handles the conversation context without relying on predefined user intents. This method makes creating efficient and reliable AI assistants faster and more secure.

Now, let's create your first flow:

1. Navigate to the Flow Builder 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_and_self_introduction. In the Description field, clearly state the flow's objective, like "Greet, introduce the assistant, and ask what the user needs help with." The description assists Rasa in deciding when to start this flow. For instance, if a user says "Hi!", the description guides the Rasa assistant to recognize welcome_and_self_introduction as the relevant flow. The description also helps anyone viewing your flow understand its purpose. After filling in those fields, click "Save".

   

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

   

Introducing the assistant#

The CALM paradigm enables the native integration of LLMs with your business logic. The most important thing to notice about this business logic is that it doesn’t include any description of the user’s side of the conversation. There’s no step labeled intent, or lines describing “if the user says this and then says this”. The user’s side of the conversation is handled via Intentless Policy.

1. For example, when a user texts "Hi," your Dialogue Understanding component should generate a command StartFlow('welcome_and_self_introduction') as a response. In this welcome_and_self_introduction flow, we aim to greet the user with a simple "Hello!" message and introduce the assistant. To start building this flow, click the "+" icon and select the "Message" step.

   

2. Click "Select message" and then choose "Create message" from the menu.

   

3. Fill in the details:

   1. Enter the name, e.g greet.
   2. Enter the message e.g "Hello! I'm Sbot, a friendly assistant created using Rasa Studio".
   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. You might have noticed that "Use Contextual Response Rephraser" option is enabled by default. This feature enables the assistant to rephrase its responses by prompting an LLM, based on the conversation's context. It helps make the assistant's responses feel more organic and conversational. Learn more.

   

8. However, if you prefer full control over responses or don't want to use an LLM, you can manually create message variations. Simply uncheck the Rephraser checkbox and click the "Add variation" button.

   

9. Add as many variations as you'd like, then click "Save".

   

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 provide the user with structured choices, streamlining the process for users to quickly select an answer. To do this, enter the desired values in the input field below the message. Press the "Enter" key after typing each value. Once finished, click "Save".

   

8. 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 "On a scale from 1 to 5, how would you rate your experience chatting with Sbot?". Optionally you can add buttons so user could easily pick the answer.

    

13. If you want, you can activate "Ask before filling" so this question won’t be skipped after each transaction.

    

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 local Rasa project

   Copy

   rasa init --template calm

   Config connection to Studio

   Copy

   rasa studio config

   ? Please enter an URL path to the Authentication Server <studio-url>/auth/

   ? Please enter an URL path to the Studio <studio-url>/api/graphql

   ? Please enter Realm Name <realm-name>

   ? Please enter client ID <client-id>

   Use the appropriate parameters if the default were changed for your Rasa Studio deployment.

   Log in to Studio as a developer

   Copy

   rasa studio login --username=<username> --password=<password>

   Download assistant by assistant-name

   Run the following in the folder where your local Rasa project is located:

   Copy

   rasa studio download <assistant-name> -d domain

   The download will update domain.yml and data/studio_flows.yml of the local assistant.

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