Forms

These docs are for version 1.x of Rasa Open Source.

User Guide

NLU

Core

Conversation Design

API Reference

Migrate from (beta)

Reference

Versions

viewing: 1.9.6

Forms

Note

There is an in-depth tutorial here about how to use Rasa Forms for slot filling.

Configuration File

Form Basics

Custom slot mappings

Validating user input

Handling unhappy paths

The requested_slot slot

Handling conditional slot logic

Debugging

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. If you need to collect multiple pieces of information in a row, we recommended that you create a FormAction. This is a single action which contains the logic to loop over the required slots and ask the user for this information. There is a full example using forms in the examples/formbot directory of Rasa Core.

When you define a form, you need to add it to your domain file. If your form’s name is restaurant_form, your domain would look like this:

forms:
  - restaurant_form
actions:
  ...

To use forms, you also need to include the FormPolicy in your policy configuration file. For example:

policies:
  - name: "FormPolicy"

Using a FormAction, you can describe all of the happy paths with a single story. By “happy path”, we mean that whenever you ask a user for some information, they respond with the information you asked for.

If we take the example of the restaurant bot, this single story describes all of the happy paths:

## happy path
* request_restaurant
    - restaurant_form
    - form{"name": "restaurant_form"}
    - form{"name": null}

In this story the user intent is request_restaurant, which is followed by the form action restaurant_form. With form{"name": "restaurant_form"} the form is activated and with form{"name": null} the form is deactivated again.

The FormAction will only request slots which haven’t already been set. If a user starts the conversation with I’d like a vegetarian Chinese restaurant for 8 people, then they won’t be asked about the cuisine and num_people slots.

Note that for this story to work, your slots should be unfeaturized. If any of these slots are featurized, your story needs to include slot{} events to show these slots being set. In that case, the easiest way to create valid stories is to use Interactive Learning.

The FormPolicy is extremely simple and just always predicts the form action. Every time the form action gets called, it will ask the user for the next slot in required_slots which is not already set. It does this by looking for a response called utter_ask_{slot_name}, so you need to define these in your domain file for each required slot.

Once all the slots are filled, the submit() method is called, where you can use the information you’ve collected to do something for the user, for example querying a restaurant API. If you don’t want your form to do anything at the end, just use return [] as your submit method.

Example Code

def name(self) -> Text:
    """Unique identifier of the form"""
    return "restaurant_form"

@staticmethod
def required_slots(tracker: Tracker) -> List[Text]:
    """A list of required slots that the form has to fill"""
    return ["cuisine", "num_people", "outdoor_seating", "preferences", "feedback"]

def submit(
    self,
    dispatcher: CollectingDispatcher,
    tracker: Tracker,
    domain: Dict[Text, Any],
) -> List[Dict]:
    """Define what the form has to do
        after all required slots are filled"""
    dispatcher.utter_message(template="utter_submit")
    return []

If you want to allow a combination of these, provide them as a list as in the example above.

After extracting a slot value from user input, the form will try to validate the value of the slot. This can be done by writing a helper validation function with the name validate_{slot-name}. Here’s an example , validate_cuisine() that checks if the extracted cuisine slot belongs to a list of supported cuisines.

    @staticmethod
def cuisine_db() -> List[Text]:
        """Database of supported cuisines"""
        return ["caribbean","chinese","french","greek","indian","italian","mexican"]

def validate_cuisine(
    self,
    value: Text,
    dispatcher: CollectingDispatcher,
    tracker: Tracker,
    domain: Dict[Text, Any],
) -> Dict[Text, Any]:
    """Validate cuisine value."""
    if value.lower() in self.cuisine_db():
        return {"cuisine": value}
    else:
        dispatcher.utter_message(template="utter_wrong_cuisine")
        return {"cuisine": None}

If you are writing stories by hand, you will likely miss important things. Please read Interactive Learning with Forms.