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
Log in with either the
developer
orflowbuilder
role.Click the assistant dropdown and select "Create assistant project."
Fill in the details:
Enter a unique assistant name, such as
transfer_money_assistant
, reflecting the purpose of facilitating money transfers.Leave "Modern" as the mode.
Finally, click the "Create assistant" button.
Configuration
After creating the assistant, navigate to the "Assistant Settings" page.
Click on the "Configuration" tab to access the
config.yml
andendpoints.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.
Read more
To learn more, visit the user guide or Rasa Pro model configuration pages.
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:
Navigate to the Flows page through the tab in the menu.
Click "Create flow" to begin crafting your welcome flow.
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.Your flow is created. Click on it to start building.
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.
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.
Choose "Create message" from the dropdown menu on the top of the side panel.
Fill in the details:
- Enter the name, e.g
greet
. - Enter the message e.g "Hello! I’m your assistant, created with Rasa Studio. I’m here to help you with money transfers".
- Leave the checkbox "Use Contextual Response Rephraser" checked if you want the message to be rephrased based on the conversation's context.
- Once you're set, click "Save".
- Enter the name, e.g
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:
Return to the flow list and click "Create flow".
Name your flow
money_transfer
and add the description: "Ask all the required questions to process a money transfer request from users." Click "Save."Click on the newly created flow to proceed with building it.
Collecting information about the recipient
Create the "Collect Information" step to ask the user who the recipient of the transfer will be.
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."
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."
Input
recipient
as a slot name. Then selectText
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.Finally, generate a message that the assistant will use to collect this information from the user. To do this, click "Create message".
The system will automatically fill in the message name by combining the slot name with the prefix
utter_ask
, resulting inutter_ask_recipient
. Enter the message content as "Who would you like to send money to?"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.
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.
Add as many variations as you'd like, then click "Save". During the conversation, Rasa will randomly pick one of them.
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.
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
orrecipient_name
, which can change each session. In this particular case, we recommend leaving the "Reset slot value" option enabled.
Collecting information about the amount
Add one more "Collect information" step to ask the user about the amount of transfer.
Enter the description: "This step inquires about the amount of the payment, in US Dollars".
Create a new slot.
Input
amount
as the slot name. Then selectFloat
as type — it is employed for storing numerical values that can have decimal points. Click "Save".Finally, generate a message that the assistant will use to collect this information from the user. To do this, click "Create message".
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)?"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".
In the modal that opens, enter a button title, e.g., "50". You can leave the Payload field empty.
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.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.
Add a "Logic" step. This type of step allows you to branch the flow based on a condition.
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
.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.
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.
After the first condition, add the "Collect information" step.
Add the description "Confirm the recipient and the transfer amount".
Create a slot and call it
final_confirmation
. Since you are asking a Yes or No question, you can store the result as aBoolean
type. Click "Save".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.Enable "Ask before filling" so that with the next transfer, the assistant will not automatically fill this slot and will ask for confirmation again.
After the "Collect information", add the "Logic" step.
For the scenario where the user confirms the request (first logic branch), enter the following details:
final_confirmation
is
True
.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.
After the
final_confirmation is true
branch, add the "Message" step.Create a new message named
transfer_successful
with the text "All done. {amount} USD has been sent to {recipient}".For the Else branch, also add the "Message" step.
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.
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.
In one of those Link steps, select "Create flow" in the dropdown.
Name the new flow
leave_feedback
. Enter the description: "This flow collects user feedback on a scale from 1 to 5."Select the same flow in another Link step.
Part 4: Building Feedback flow
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.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.
Select "Start the flow exclusively via "Link" or "Call a flow and return" steps". 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
money_transfer
flow.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:
- Add the step description "Confirm user wants to leave feedback".
- Create a slot named
feedback
with aBoolean
type, as it's a yes or No question. - Add an assistant's message with the name
utter_ask_feedback
and the text "Do you want to leave feedback?" - The result should look like this:
Following this question, insert the "Logic" step.
Set the first logic branch to
feedback
is
true
. If the user is willing to leave feedback, the conversation will follow this branch.After the Else branch — the case when the user doesn’t want to leave feedback — add the "Message" step.
Name the new message
goodbye
and add the text "Thank you and have a great day!"After
feedback
is
true
branch, add the “Collect information” step.Enter the description: "Ask users to rate the assistant's performance".
Create a new slot named
rating
and useFloat
as a type, as we’ll accept the number from 1 to 5.Create a new message automatically named
utter_ask_rating
and add the text "How would you rate my performance from 1 to 5?".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:
Go to the flow list and select the "Ready for training" switch for all of the flows that you have created and consider ready.
Click the "Train" button.
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.
Once the training has started, you will see the following message:
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.
In the event of a successful model training, you will see the green tick and the following message:
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.
Return to the
money_transfer
flow.After the question about how much money you would like to transfer and before the logic branch, add a "Custom action" step.
Open the custom action dropdown and click "Create custom action."
Enter the name
action_validate_sufficient_funds
and a description: "Goal: Validate whether the funds are sufficient for the transfer. Requirement: Check if the slotamount
is greater than 1000. If true, return atrue
value for the slothas_sufficient_funds
. If false, return afalse
value for the slothas_sufficient_funds
."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 ofamount
, create a new slot.Enter slot name
has_sufficient_funds
. SelectBoolean
as a type and click "Save".Set the condition so that
has_sufficient_funds
is
true
.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
rasa init --template calmImplement the custom action that validates the amount of funds. You can copy/paste the following Python code in
actions/actions.py
:# 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-actionsfrom typing import Any, Text, Dict, Listfrom rasa_sdk import Action, Trackerfrom rasa_sdk.executor import CollectingDispatcherfrom rasa_sdk.events import SlotSetclass 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 APIbalance = 1000transfer_amount = tracker.get_slot("amount")has_sufficient_funds = transfer_amount <= balancereturn [SlotSet("has_sufficient_funds", has_sufficient_funds)]Run action server using Rasa CLI.
rasa run actionsUse 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.ngrok http 5055You can provide the URL +
/webhook
in Assistant Settings - Configuration - Action Endpoint:Train and test your assistants again, as described in Part 5.
Part 7: Editing YAML files [Advanced]
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
andclient-id
based on variables used during your Studio deploymentCreate a new folder
mkdir my-assistant-namecd my-assistant-nameConfigure CLI to connect to Studio
rasa studio configProvide the Studio URL to configure the connection.
Log in to Studio as a developer
rasa studio loginProvide the credentials of the user belonging to the developer group.
Download assistant by assistant-name
Run the below command to download the assistant files.
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:
|-endpoints.yml|-config.yml|-domain.yml|-data| |-studio_flows.yml| |-studio_nlu.ymlRun
rasa studio download --help
to see the full list of arguments.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
Train the rasa model locally using rasa CLI.
rasa trainTest your assistant with custom action using Rasa Inspector.
rasa inspect