notice

This is unreleased documentation for Rasa Documentation Main/Unreleased version.
For the latest released documentation, see the latest version (3.x).

Version: Main/Unreleased

Domain

The domain defines the universe in which your assistant operates. It specifies the intents, entities, slots, responses, forms, and actions your bot should know about. It also defines a configuration for conversation sessions.

Here is a full example of a domain, taken from the concertbot example:

version: "3.1"
intents:
- affirm
- deny
- greet
- thankyou
- goodbye
- search_concerts
- search_venues
- compare_reviews
- bot_challenge
- nlu_fallback
- how_to_get_started
entities:
- name
slots:
concerts:
type: list
influence_conversation: false
mappings:
- type: custom
venues:
type: list
influence_conversation: false
mappings:
- type: custom
likes_music:
type: bool
influence_conversation: true
mappings:
- type: custom
responses:
utter_greet:
- text: "Hey there!"
utter_goodbye:
- text: "Goodbye :("
utter_default:
- text: "Sorry, I didn't get that, can you rephrase?"
utter_youarewelcome:
- text: "You're very welcome."
utter_iamabot:
- text: "I am a bot, powered by Rasa."
utter_get_started:
- text: "I can help you find concerts and venues. Do you like music?"
utter_awesome:
- text: "Awesome! You can ask me things like \"Find me some concerts\" or \"What's a good venue\""
actions:
- action_search_concerts
- action_search_venues
- action_show_concert_reviews
- action_show_venue_reviews
- action_set_music_preference
session_config:
session_expiration_time: 60 # value in minutes
carry_over_slots_to_new_session: true

Multiple Domain Files

The domain can be defined as a single YAML file or split across multiple files in a directory. When split across multiple files, the domain contents will be read and automatically merged together.

Using the command line interface, you can train a model with split domain files by running:

rasa train --domain path_to_domain_directory

Intents

The intents key in your domain file lists all intents used in your NLU data and conversation training data.

Ignoring Entities for Certain Intents

To ignore all entities for certain intents, you can add the use_entities: [] parameter to the intent in your domain file like this:

intents:
- greet:
use_entities: []

To ignore some entities or explicitly take only certain entities into account you can use this syntax:

intents:
- greet:
use_entities:
- name
- first_name
- farewell:
ignore_entities:
- location
- age
- last_name

You can only use_entities or ignore_entities for any single intent.

Excluded entities for those intents will be unfeaturized and therefore will not impact the next action predictions. This is useful when you have an intent where you don't care about the entities being picked up.

If you list your intents without a use_entities or ignore_entities parameter, the entities will be featurized as normal.

It is also possible to ignore an entity for all intents by setting the influence_conversation flag to false for the entity itself. See the entities section for details.

Excluded entities for intents will be unfeaturized and therefore will not impact the next action predictions. This is useful when you have an intent where you don't care about the entities being picked up.

If you list your intents without this parameter, and without setting influence_conversation to false for any entities, all entities will be featurized as normal.

note

If you want these entities not to influence action prediction via slots either, set the influence_conversation: false parameter for slots with the same name.

Entities

New in 3.1

As of 3.1, you can use the influence_conversation flag under entities. The flag can be set to false to declare that an entity should not be featurized for any intents. It is a shorthand syntax for adding an entity to the ignore_entities list of every intent in the domain. The flag is optional and default behaviour remains unchanged.

The entities section lists all entities that can be extracted by any entity extractor in your NLU pipeline.

For example:

entities:
- PERSON # entity extracted by SpacyEntityExtractor
- time # entity extracted by DucklingEntityExtractor
- membership_type # custom entity extracted by DIETClassifier
- priority # custom entity extracted by DIETClassifier

When using multiple domain files, entities can be specified in any domain file, and can be used or ignored by any intent in any domain file.

If you are using the feature Entity Roles and Groups you also need to list the roles and groups of an entity in this section.

For example:

entities:
- city: # custom entity extracted by DIETClassifier
roles:
- from
- to
- topping: # custom entity extracted by DIETClassifier
groups:
- 1
- 2
- size: # custom entity extracted by DIETClassifier
groups:
- 1
- 2

By default, entities influence action prediction. To prevent extracted entities from influencing the conversation for specific intents you can ignore entities for certain intents. To ignore an entity for all intents, without having to list it under the ignore_entities flag of each intent, you can set the flag influence_conversation to false under the entity:

entities:
- location:
influence_conversation: false

This syntax has the same effect as adding the entity to the ignore_entities list for every intent in the domain.

Explicitly setting influence_conversation: true does not change any behaviour. This is the default setting.

Slots

Slots are your bot's memory. They act as a key-value store which can be used to store information the user provided (e.g their home city) as well as information gathered about the outside world (e.g. the result of a database query).

Slots are defined in the slots section of your domain with their name, type and if and how they should influence the assistant's behavior. The following example defines a slot with name "slot_name", type text and predefined slot mapping from_entity.

slots:
slot_name:
type: text
mappings:
- type: from_entity
entity: entity_name

Slots and Conversation Behavior

You can specify whether or not a slot influences the conversation with the influence_conversation property.

If you want to store information in a slot without it influencing the conversation, set influence_conversation: false when defining your slot.

The following example defines a slot age which will store information about the user's age, but which will not influence the flow of the conversation. This means that the assistant will ignore the value of the slot each time it predicts the next action.

slots:
age:
type: text
# this slot will not influence the predictions
# of the dialogue policies
influence_conversation: false

When defining a slot, if you leave out influence_conversation or set it to true, that slot will influence the next action prediction, unless it has slot type any. The way the slot influences the conversation will depend on its slot type.

The following example defines a slot home_city that influences the conversation. A text slot will influence the assistant's behavior depending on whether the slot has a value. The specific value of a text slot (e.g. Bangalore or New York or Hong Kong) doesn't make any difference.

slots:
# this slot will influence the conversation depending on
# whether the slot is set or not
home_city:
type: text
influence_conversation: true

As an example, consider the two inputs "What is the weather like?" and "What is the weather like in Bangalore?" The conversation should diverge based on whether the home_city slot was set automatically by the NLU. If the slot is already set, the bot can predict the action_forecast action. If the slot is not set, it needs to get the home_city information before it is able to predict the weather.

Slot Types

Text Slot

  • Type

    text

  • Use For

    Storing text values.

  • Example

    slots:
    cuisine:
    type: text
    mappings:
    - type: from_entity
    entity: cuisine
  • Description

    If influence_conversation is set to true, the assistant's behavior will change depending on whether the slot is set or not. Different texts do not influence the conversation any further. This means the following two stories are equal:

    stories:
    - story: French cuisine
    steps:
    - intent: inform
    - slot_was_set:
    - cuisine: french
    - story: Vietnamese cuisine
    steps:
    - intent: inform
    - slot_was_set:
    - cuisine: vietnamese

Boolean Slot

  • Type

    bool

  • Use For

    Storing true or false values.

  • Example

    slots:
    is_authenticated:
    type: bool
    mappings:
    - type: custom
  • Description

    If influence_conversation is set to true, the assistant's behavior will change depending on whether the slot is empty, set to true or set to false. Note that an empty bool slot influences the conversation differently than if the slot was set to false.

Categorical Slot

  • Type

    categorical

  • Use For

    Storing slots which can take one of N values.

  • Example

    slots:
    risk_level:
    type: categorical
    values:
    - low
    - medium
    - high
    mappings:
    - type: custom
  • Description

    If influence_conversation is set to true, the assistant's behavior will change depending on the concrete value of the slot. This means the assistant's behavior is different depending on whether the slot in the above example has the value low, medium, or high.

    A default value __other__ is automatically added to the user-defined values. All values encountered which are not explicitly defined in the slot's values are mapped to __other__. __other__ should not be used as a user-defined value; if it is, it will still behave as the default to which all unseen values are mapped.

Float Slot

  • Type

    float

  • Use For

    Storing real numbers.

  • Example

    slots:
    temperature:
    type: float
    min_value: -100.0
    max_value: 100.0
    mappings:
    - type: custom
  • Defaults

    max_value=1.0, min_value=0.0

  • Description

    If influence_conversation is set to true, the assistant's behavior will change depending on the value of the slot. If the value is between min_value and max_value, the specific value of the number is used. All values below min_value will be treated as min_value, and all values above max_value will be treated as max_value. Hence, if max_value is set to 1, there is no difference between the slot values 2 and 3.5.

List Slot

  • Type

    list

  • Use For

    Storing lists of values.

  • Example

    slots:
    shopping_items:
    type: list
    mappings:
    - type: from_entity
    entity: shopping_item
  • Description

    If influence_conversation is set to true, the assistant's behavior will change depending on whether the list is empty or not. The length of the list stored in the slot does not influence the dialogue. It only matters whether list length is zero or non-zero.

Any Slot

  • Type

    any

  • Use For

    Storing arbitrary values (they can be of any type, such as dictionaries or lists).

  • Example

    slots:
    shopping_items:
    type: any
    mappings:
    - type: custom
  • Description

    Slots of type any are always ignored during conversations. The property influence_conversation cannot be set to true for this slot type. If you want to store a custom data structure which should influence the conversation, use a custom slot type.

Custom Slot Types

Maybe your restaurant booking system can only handle bookings for up to 6 people. In this case you want the value of the slot to influence the next selected action (and not just whether it's been specified). You can do this by defining a custom slot class.

The code below defines a custom slot class called NumberOfPeopleSlot. The featurization defines how the value of this slot gets converted to a vector so Rasa machine learning model can deal with it. The NumberOfPeopleSlot has three possible “values”, which can be represented with a vector of length 2.

(0,0)not yet set
(1,0)between 1 and 6
(0,1)more than 6
my_custom_slots.py
from rasa.shared.core.slots import Slot
class NumberOfPeopleSlot(Slot):
def feature_dimensionality(self):
return 2
def as_feature(self):
r = [0.0] * self.feature_dimensionality()
if self.value:
if self.value <= 6:
r[0] = 1.0
else:
r[1] = 1.0
return r

You can implement a custom slot class as an independent python module, separate from custom action code. Save the code for your custom slot in a directory alongside an empty file called "__init__.py" so that it will be recognized as a python module. You can then refer to the custom slot class by it's module path.

For example, say you have saved the code above in "addons/my_custom_slots.py", a directory relative to your bot project:

└── rasa_bot
├── addons
│ ├── __init__.py
│ └── my_custom_slots.py
├── config.yml
├── credentials.yml
├── data
├── domain.yml
├── endpoints.yml

Your custom slot type's module path is then addons.my_custom_slots.NumberOfPeopleSlot. Use the module path to refer to the custom slot type in your domain file:

domain.yaml
slots:
people:
type: addons.my_custom_slots.NumberOfPeopleSlot
influence_conversation: true
mappings:
- type: custom

Now that your custom slot class can be used by Rasa, add training stories that diverge based on the value of the people slot. You could write one story for the case where people has a value between 1 and 6, and one for a value greater than six. You can choose any value within these ranges to put in your stories, since they are all featurized the same way (see the featurization table above).

stories:
- story: collecting table info
steps:
# ... other story steps
- intent: inform
entities:
- people: 3
- slot_was_set:
- people: 3
- action: action_book_table
- story: too many people at the table
steps:
# ... other story steps
- intent: inform
entities:
- people: 9
- slot_was_set:
- people: 9
- action: action_explain_table_limit

Slot Mappings

New in 3.0

As of 3.0, slot mappings are defined in the slots section of the domain. This change removes the implicit mechanism of setting slots via auto-fill and replaces it with a new explicit mechanism of setting slots after every user message. You will need to explicitly define slot mappings for each slot in the slots section of domain.yml. If you are migrating from an earlier version, please read through the migration guide to update your assistant.

Rasa comes with four predefined mappings to fill slots based on the latest user message.

In addition to the predefined mappings, you can define custom slot mappings. All custom slot mappings should contain a mapping of type custom.

Slot mappings are specified as a YAML list of dictionaries under the key mappings in the domain file. Slot mappings are prioritized in the order they are listed in the domain. The first slot mapping found to apply will be used to fill the slot.

The default behavior is for slot mappings to apply after every user message, regardless of the dialogue context. To make a slot mapping apply only within the context of a form see Mapping Conditions. There is one additional default limitation on applying from_entity slot mappings in the context of a form; see unique from_entity mapping matching for details.

Note that you can also define lists of intents for the optional parameters intent and not_intent.

from_entity

The from_entity slot mapping fills slots based on extracted entities. The following parameters are required:

  • entity: the entity that should fill the slot

The following parameters are optional and can be used to further specify when the mapping applies:

  • intent: Only applies the mapping when this intent is predicted.
  • not_intent: Does not apply the mapping when this intent is predicted
  • role: Only applies the mapping if the extracted entity has this role
  • group: Only applies the mapping if the extracted entity belongs to this group.
entities:
- entity_name
slots:
slot_name:
type: any
mappings:
- type: from_entity
entity: entity_name
role: role_name
group: group name
intent: intent_name
not_intent: excluded_intent
Unique from_entity mapping matching

There is an intentional limitation on applying from_entity slot mappings in the context of a form. When a form is active, a from_entity slot mapping will be applied only if one or more of the following conditions are met:

  1. The slot with the from_entity mapping has just been requested by the form
  2. Only one of the active form's required_slots has that specific from_entity mapping, including all the attributes of the extracted entity (i.e, entity name, role, group). This is known as a unique entity mapping for the form. The extracted entity will be ignored if the mapping is not unique within the list of required_slots.

This limitation exists to prevent a form from filling multiple required slots with the same extracted entity value.

For example, in the example below, 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.

slots:
departure_city:
type: text
mappings:
- type: from_entity
entity: city
role: from
- type: from_entity
entity: city
arrival_city:
type: text
mappings:
- type: from_entity
entity: city
role: to
- type: from_entity
entity: city
arrival_date:
type: any
mappings:
- type: from_entity
entity: date
forms:
your_form:
required_slots:
- departure_city
- arrival_city
- arrival_date

Note that the unique from_entity mapping constraint will not prevent filling slots which are not in the active form's required_slots; those mappings will apply as usual, regardless of the uniqueness of the mapping. To limit applicability of a slot mapping to a specific form, see Mapping Conditions.

from_text

The from_text mapping will use the text of the last 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.

slots:
slot_name:
type: text
mappings:
- type: from_text
intent: intent_name
not_intent: excluded_intent
note

To maintain the 2.x form behavior when using from_text slot mappings, you must use mapping conditions, where both active_loop and requested_slot keys are defined.

from_intent

The from_intent mapping will fill slot slot_name with value my_value if user intent is intent_name. If you choose not to specify the parameter intent, the slot mapping will apply regardless of the intent of the message as long as the intent is not listed under not_intent parameter.

The following parameter is required:

  • value: the value that fills the slot slot_name

The following parameters are optional and can be used to further specify when the mapping applies:

  • intent: Only applies the mapping when this intent is predicted.
  • not_intent: Does not apply the mapping when this intent is predicted

Note that if you choose not to define the parameter intent, the slot mapping will apply regardless of the intent of the message as long as the intent is not listed under the not_intent parameter.

slots:
slot_name:
type: any
mappings:
- type: from_intent
value: my_value
intent: intent_name
not_intent: excluded_intent

from_trigger_intent

The from_trigger_intent mapping will fill slot slot_name with value my_value if a form is activated by a user message with intent intent_name. The slot mapping will not apply if the intent of the message is excluded_intent.

slots:
slot_name:
type: any
mappings:
- type: from_trigger_intent
value: my_value
intent: intent_name
not_intent: excluded_intent

Mapping Conditions

To apply a slot mapping only within the context of a form, specify the name of the form in the conditions key of a slot mapping. Conditions list the form name(s) for which the mapping is applicable in the active_loop key.

New in 3.6

Slot mappings can now specify null as the value of active_loop to indicate that the slot should only be filled when no form is active. Note that requested_slot cannot be used in conjunction with active_loop: null.

Conditions can also include the name of the requested_slot. If requested_slot is not mentioned, then the slot will be set if relevant information is extracted, regardless of which slot is being requested by the form.

slots:
slot_name:
type: text
mappings:
- type: from_text
intent: intent_name
conditions:
- active_loop: your_form
requested_slot: slot_name
- active_loop: another_form
note

If conditions are not included in a slot mapping, the slot mapping will be applicable regardless of whether any form is active. As long as a slot is listed in a form's required_slots, the form will prompt for the slot if it is empty when the form is activated.

Custom Slot Mappings

You can define custom slot mappings using slot validation actions when none of the predefined mappings fit your use case. You must define this slot mapping to be of type custom, for example:

slots:
day_of_week:
type: text
mappings:
- type: custom
action: action_calculate_day_of_week

You can also use the custom slot mapping to list slots that will be filled by arbitrary custom actions in the course of a conversation, by listing the type and no specific action. For example:

slots:
handoff_completed:
type: boolean
mappings:
- type: custom

This slot will not be updated on every user turn, but only once a custom action that returns a SlotSet event for it is predicted.

Initial slot values

You can provide an initial value for a slot in your domain file:

slots:
num_fallbacks:
type: float
initial_value: 0
mappings:
- type: custom

Responses

Responses are actions that send a message to a user without running any custom code or returning events. These responses can be defined directly in the domain file under the responses key and can include rich content such as buttons and attachments. For more information on responses and how to define them, see Responses.

Forms

Forms are a special type of action meant to help your assistant collect information from a user. Define forms under the forms key in your domain file. For more information on form and how to define them, see Forms.

Actions

Actions are the things your bot can actually do. For example, an action could:

  • respond to a user,

  • make an external API call,

  • query a database, or

  • just about anything!

All custom actions should be listed in your domain, except responses which need not be listed under actions: as they are already listed under responses:.

Select which actions should receive domain

New in 3.4.3

You can control if an action should receive a domain or not.

To do this you must first enable selective domain in you endpoint configuration for action_endpoint in endpoints.yml.

# endpoints.yml
action_endpoint:
url: "http://localhost:5055/webhook" # URL to your action server
enable_selective_domain: true

After selective domain for custom actions is enabled, domain will be sent only to those custom actions which have specifically stated that they need it. Custom actions inheriting from rasa-sdk FormValidationAction parent class are an exception to this rule as they will always have the domain sent to them. To specify if an action needs the domain add {send_domain: true} to custom action in the list of actions in domain.yml:

# domain.yml
actions:
- action_hello_world: {send_domain: True} # will receive domain
- action_calculate_mass_of_sun # will not receive domain
- validate_my_form # will receive domain

Session configuration

A conversation session represents the dialogue between the assistant and the user. Conversation sessions can begin in three ways:

  1. the user begins the conversation with the assistant,

  2. the user sends their first message after a configurable period of inactivity, or

  3. a manual session start is triggered with the /session_start intent message.

You can define the period of inactivity after which a new conversation session is triggered in the domain under the session_config key.

Available parameters are:

  • session_expiration_time defines the time of inactivity in minutes after which a new session will begin.
  • carry_over_slots_to_new_session determines whether existing set slots should be carried over to new sessions.

The default session configuration looks as follows:

session_config:
session_expiration_time: 60 # value in minutes, 0 means infinitely long
carry_over_slots_to_new_session: true # set to false to forget slots between sessions

This means that if a user sends their first message after 60 minutes of inactivity, a new conversation session is triggered, and that any existing slots are carried over into the new session. Setting the value of session_expiration_time to 0 means that sessions will not end (note that the action_session_start action will still be triggered at the very beginning of conversations).

note

A session start triggers the default action action_session_start. Its default implementation moves all existing slots into the new session. Note that all conversations begin with an action_session_start. Overriding this action could for instance be used to initialize the tracker with slots from an external API call, or to start the conversation with a bot message. The docs on Customizing the session start action shows you how to do that.

Config

The config key in the domain file maintains the store_entities_as_slots parameter. This parameter is used only in the context of reading stories and turning them into trackers. If the parameter is set to True, this will result in slots being implicitly set from entities if applicable entities are present in the story. When an entity matches the from_entity slot mapping, store_entities_as_slots defines whether the entity value should be placed in that slot. Therefore, this parameter skips adding an explicit slot_was_set step manually in the story. By default, this behaviour is switched on.

You can turn off this functionality by setting the store_entities_as_slots parameter to false:

domain.yml
config:
store_entities_as_slots: false
looking for config.yml?

If you're looking for information on the config.yml file, check out the docs on Model Configuration.