notice
This is documentation for Rasa Open Source Documentation v2.0.x, which is no longer actively maintained.
For up-to-date documentation, see the latest version (2.3.x).
Forms
One of the most common conversation patterns is to collect a few pieces of information from a user in order to do something (book a restaurant, call an API, search a database, etc.). This is also called **slot filling**.
Usage
To use forms with Rasa Open Source you need to make sure that the Rule Policy is added to your policy configuration. For example:
Defining a Form
Define a form by adding it to the forms
section in your domain.
The name of the form is also the name of the action which you can use in
stories or rules to handle form executions. You also
need to define slot mappings for each slot which your
form should fill.
You can specify one or more slot mappings for each slot to be filled.
The following example form restaurant_form
will fill the slot
cuisine
from an extracted entity cuisine
and slot num_people
from entity number
.
Once the form action gets called for the first time, the form gets activated and will
prompt the user for the next required slot value. It does this by
looking for a response called
utter_ask_{form_name}_{slot_name}
or utter_ask_{slot_name}
if the former isn't
found. Make sure to define these responses in your domain file for
each required slot.
Activating a Form
To activate a form you need to add a story or rule, which describes when the assistant should run the form. In the case a specific intent triggering a form, you can for example use the following rule:
note
The active_loop: restaurant_form
step indicates that the form should be activated after
restaurant_form
was run.
Deactivating a Form
A form will automatically deactivate itself once all required slots are filled.
You can describe your assistant's behavior for the end of a form with a rule or a story.
If you don't add an applicable story or rule, the assistant will automatically listen
for the next user message after the form is finished.
The following example runs the utterance utter_all_slots_filled
as soon as the form
your_form
filled all required slots.
Users might want to break out of a form early. Please see Writing Stories / Rules for Unhappy Form Paths on how to write stories or rules for this case.
Slot Mappings
Rasa Open Source comes with four predefined mappings to fill the slots of a form based on the latest user message. Please see Custom Slot Mappings if you need a custom function to extract the required information.
from_entity
The from_entity
mapping fills slots based on extracted entities.
It will look for an entity called entity_name
to fill a slot slot_name
.
If intent_name
is None
, the slot will be filled regardless of intent name.
Otherwise, the slot will only be filled if the user's intent is intent_name
.
If role_name
and/or group_name
are provided, the role/group
label of the entity also needs to match the given values. The slot mapping will not
apply if the intent of the message is excluded_intent
. Note that you can
also define lists of intents for the parameters intent
and not_intent
.
In from_entity
mapping, when an extracted entity uniquely maps onto a slot,
the slot will be filled even if this slot wasn't requested by the form.
The extracted entity will be ignored if the mapping is not unique.
In the example above, an entity date
uniquely sets the slot arrival_date
,
an entity city
with a role from
uniquely sets the slot departure_city
and
an entity city
with a role to
uniquely sets the slot arrival_city
,
therefore they can be used to fit corresponding slots
even if these slots were not requested.
However, entity city
without a role can fill both departure_city
and arrival_city
slots, depending which one is requested, so if an entity city
is extracted when
slot arrival_date
is requested, it'll be ignored by the form.
from_text
The from_text
mapping will use the text of the next user utterance to fill the slot
slot_name
. If intent_name
is None
, the slot will be filled regardless of intent name.
Otherwise, the slot will only be filled if the user's intent is intent_name
.
The slot mapping will not apply if the intent of the message is excluded_intent
.
Note that you can define lists of intents for the parameters intent
and not_intent
.
from_intent
The from_intent
mapping will fill slot slot_name
with value my_value
if
user intent is intent_name
or None
. The slot mapping will not
apply if the intent of the message is excluded_intent
. Note that you can
also define lists of intents for the parameters intent
and not_intent
.
note
The from_intent
slot mapping will not apply during the initial activation of the form. To fill
a slot based on the intent that activated the form, use the from_trigger_intent
mapping.
from_trigger_intent
The from_trigger_intent
mapping will fill slot slot_name
with value my_value
if the form was activated by a user message with intent intent_name
.
The slot mapping will not apply if the intent of the message is
excluded_intent
. Note that you can
also define lists of intents for the parameters intent
and not_intent
.
Writing Stories / Rules for Unhappy Form Paths
Your users will not always respond with the information you ask of them.
Typically, users will ask questions, make chitchat, change their mind, or otherwise
stray from the happy path. The way this works with forms is that a form will raise
an ActionExecutionRejection
if the user didn't provide the requested information.
You need to handle events that might cause ActionExecutionRejection
errors
with rules or stories. For example, if you expect your users to chitchat with your bot,
you could add a rule to handle this:
In some situations, users may change their mind in the middle of the form action and decide not to go forward with their initial request. In cases like this, the assistant should stop asking for the requested slots.
You can handle such situations
gracefully using a default action action_deactivate_loop
which will deactivate
the form and reset the requested slot. An example story of such conversation could
look as follows:
It is strongly recommended that you build these rules or stories using interactive learning. If you write these rules / stories by hand you will likely miss important things.
Advanced Usage
Forms are fully customizable using Custom Actions.
Validating Form Input
After extracting a slot value from user input, you can validate the extracted slots.
By default Rasa Open Source only validates if any slot was filled after requesting
a slot. If nothing is extracted from the user’s utterance for any of the required slots,
an ActionExecutionRejection
error will be raised, meaning the action execution was
rejected and therefore Rasa Open Source will fall back onto a different policy to
predict another action.
You can implement a Custom Action validate_{form_name}
to validate any extracted slots. Make sure to add this action to the actions
section of your domain:
When the form is executed it will run your custom action.
This custom action can extend FormValidationAction
class to simplify
the process of validating extracted slots. In this case, you need to write functions
named validate_<slot_name>
for every extracted slot.
The following example shows the implementation of a custom action
which validates that the slot named cuisine
is valid.
You can also extend the Action
class and retrieve extracted slots with tracker.slots_to_validate
to fully customize the validation process.
Custom Slot Mappings
If none of the predefined Slot Mappings fit your use
case, you can use the
Custom Action validate_{form_name}
to write your own
extraction code. Rasa Open Source will trigger this function when the form is run.
Make sure your custom action returns SlotSet
events for every extracted value.
The following example shows the implementation of a custom slot mapping which sets
a slot based on the length of the last user message.
Requesting Extra Slots
If you make frequent changes to the required slots and don't want to retrain your
assistant when your form changes, you can also use a
Custom Action validate_{form_name}
to define
which slots should be requested. Rasa Open Source will run your custom action whenever
the form validates user input. Set the slot requested_slot
to the name of the slot
which should be extracted next. If all desired slots are filled, set requested_slot
to None
.
The following example shows the implementation of a custom action which requests
the three slots cuisine
, num_people
, and outdoor_seating
.
The requested_slot slot
The slot requested_slot
is automatically added to the domain as a
slot of type text
. The value of the requested_slot
will be
ignored during conversations. If you want to change this behavior, you need to add
the requested_slot
to your domain file as a categorical slot with
influence_conversation
set to true
.
You might want to do this if you
want to handle your unhappy paths differently, depending on what slot is
currently being asked from the user. For example, if your users respond
to one of the bot's questions with another question, like why do you need to know that?
The response to this explain
intent depends on where we are in the story.
In the restaurant case, your stories would look something like this:
Again, it is strongly recommended that you use interactive learning to build these stories.
Using a Custom Action to Ask For the Next Slot
As soon as the form determines which slot has to be filled next by the user, it will
execute the action utter_ask_{form_name}_{slot_name}
or utter_ask_{slot_name}
to ask the user to provide the necessary information. If a regular utterance is not
enough, you can also use a custom action action_ask_{form_name}__{slot_name}
or
action_ask_{slot_name}
to ask for the next slot.