## Format A story is a representation of a conversation between a user and an AI assistant, converted into a specific format where user inputs are expressed as intents (and entities when necessary), while the assistant's responses and actions are expressed as action names. Here's an example of a dialogue in the Rasa story format: ```yaml stories: - story: collect restaurant booking info # name of the story - just for debugging steps: - intent: greet # user message with no entities - action: utter_ask_howcanhelp - intent: inform # user message with entities entities: - location: "rome" - price: "cheap" - action: utter_on_it # action that the bot should execute - action: utter_ask_cuisine - intent: inform entities: - cuisine: "spanish" - action: utter_ask_num_people ``` ### User Messages While writing stories, you do not have to deal with the specific contents of the messages that the users send. Instead, you can take advantage of the output from the NLU pipeline, which lets you use just the combination of an intent and entities to refer to all the possible messages the users can send to mean the same thing. It is important to include the entities here as well because the policies learn to predict the next action based on a combination of both the intent and entities (you can, however, change this behavior using the [use_entities](https://legacy-docs-oss.rasa.com/docs/rasa/next/domain#ignoring-entities-for-certain-intents) attribute). ### Actions All actions executed by the bot, including responses, are listed in stories under the `action` key. You can use a response from your domain as an action by listing it as one in a story. Similarly, you can indicate that a story should call a custom action by including the name of the custom action from the `actions` list in your domain. ### Events During training, Rasa does not call the action server. This means that your assistant's dialogue management model doesn't know which events a custom action will return. Because of this, events such as setting a slot or activating/deactivating a form have to be explicitly written out as part of the stories. For more info, see the documentation on [Events](https://legacy-docs-oss.rasa.com/docs/rasa/next/action-server/events). #### Slot Events Slot events are written under `slot_was_set` in a story. If this slot is set inside a custom action, add the `slot_was_set` event immediately following the custom action call. If your custom action resets a slot value to `None`, the corresponding event for that would look like this: ```yaml stories: - story: set slot to none steps: # ... other story steps - action: my_custom_action - slot_was_set: - my_slot: null ``` #### Form Events There are three kinds of events that need to be kept in mind while dealing with forms in stories. - A form action event (e.g. `- action: restaurant_form`) is used in the beginning when first starting a form, and also while resuming the form action when the form is already active. - A form activation event (e.g. `- active_loop: restaurant_form`) is used right after the first form action event. - A form deactivation event (e.g. `- active_loop: null`), which is used to deactivate the form. ### Checkpoints and OR statements Checkpoints and OR statements should be used with caution, if at all. There is usually a better way to achieve what you want by using [Rules](https://legacy-docs-oss.rasa.com/docs/rasa/next/rules) or the [ResponseSelector](https://legacy-docs-oss.rasa.com/docs/rasa/next/components#responseselector). ### Checkpoints You can use checkpoints to modularize and simplify your training data. Checkpoints can be useful, but do not overuse them. Using lots of checkpoints can quickly make your example stories hard to understand, and will slow down training. Here is an example of stories that contain checkpoints: ```yaml stories: - story: beginning of flow steps: - intent: greet - action: action_ask_user_question - checkpoint: check_asked_question - story: handle user affirm steps: - checkpoint: check_asked_question - intent: affirm - action: action_handle_affirmation - checkpoint: check_flow_finished - story: handle user deny steps: - checkpoint: check_asked_question - intent: deny - action: action_handle_denial - checkpoint: check_flow_finished - story: finish flow steps: - checkpoint: check_flow_finished - intent: goodbye - action: utter_goodbye ``` ### Or Statements Another way to write shorter stories, or to handle multiple intents or slot events the same way, is to use an `or` statement. For example, if you ask the user to confirm something, and you want to treat the `affirm` and `thankyou` intents in the same way. The story below will be converted into two stories at training time: ```yaml stories: - story: steps: # ... previous steps - action: utter_ask_confirm - or: - intent: affirm - intent: thankyou - action: action_handle_affirmation ``` You can also use `or` statements with slot events. The following means the story requires that the current value for the `name` slot is set and is either `joe` or `bob`: ```yaml stories: - story: steps: - intent: greet - action: utter_greet - intent: tell_name - or: - slot_was_set: - name: joe - slot_was_set: - name: bob ``` ### Test Conversation Format The test conversation format is a format that combines both NLU data and stories into a single file for evaluation. Read more about this format in [Testing Your Assistant](https://legacy-docs-oss.rasa.com/docs/rasa/next/testing-your-assistant). ### End-to-end Training End-to-end training is an experimental feature. We introduce experimental features to get feedback from our community, so we encourage you to try it out! However, the functionality might be changed or removed in the future. With end-to-end training, you do not have to deal with the specific intents of the messages that are extracted by the NLU pipeline or with separate `utter_` responses in the domain file. Instead, you can include the text of the user messages and/or bot responses directly in your stories.