Skip to content

October 16th, 2020

Introducing the Unified Rule Policy

  • portrait of Karen White

    Karen White

In Rasa Open Source 2.0, we've introduced the Rule Policy, and with it, a new approach to configuring dialogue management. With the Rule Policy, we draw a clearer distinction between policies that use predefined logic to select a fixed response and those that learn to predict the assistant's next action from data. This removes the guesswork from selecting a policy configuration and makes it easier to enforce business logic.

The Rule Policy replaces several policies you would see in a typical 1.x configuration: the Mapping Policy, the Form Policy, and the Fallback Policy. When we examine each of these policies more closely, we see that they have something in common. They all follow a deterministic pattern:

  • MappingPolicy: If a specific intent is detected, then predict the mapped action.
  • FallbackPolicy: If NLU confidence is below a set threshold, then predict the fallback response action.
  • FormPolicy: If a form is active and all form slots have not yet been filled, then predict the form action and request the next slot.

In Rasa Open Source 2.0, the Rule Policy combines the functionality of all three of these rule-based policies into a single policy.

- ... # Other policies, e.g. TEDPolicy
- name: RulePolicy

How do rules work in Rasa?

Rules define a series of actions that should happen if a certain condition is met; for example, when a specific intent is detected. They describe predictable behaviors you already know your assistant should follow. When the user says "Hello," the assistant should respond with a greeting. When the user says "Thanks, that's all," the assistant should say, "You're welcome, have a nice day." These conversation turns should always result in the same fixed response, no matter what.

These are simple examples, but rules can also be applied to more complex uses. You can create rules that only apply at a certain point in the conversation, like at the very beginning. You can also create rules that take effect when a slot is set to a specific value. Fallbacks and forms are also defined by rules, which set the confidence threshold for the fallback action and the event that should activate the form, respectively.

Useful as rules are, if you try to build an assistant entirely out of rules, you'll eventually run into problems. Conversations don't consist entirely of predictable single-turn interactions-users ask questions that reference earlier parts of the conversation or they say things you didn't expect. That's why Rasa Open Source also includes the TEDPolicy for dialogue predictions. In cases where the next best action can't be reliably determined by a rule, the TED Policy steps in to make an educated prediction based on similar conversations in the training data.

To summarize, rules are great for situations where you already know what your assistant should do, and machine learning provides an answer when you can't anticipate the user's path.

Rule snippets

The Rule Policy's behavior is defined by rule snippets. Rule snippets set the condition that triggers the rule and what should happen after the rule has been activated. Rule snippets describe a single conversation turn-one condition and the follow-up action or actions that come after.

Rule snippets are written in a section of your training data file headed by the rules: key. Note that as of the 2.0 release, the YAML training data format allows you to combine training data for nlu, stories, and rules into a single file, or you can split training data between several modular files, as long as each section is headed by the appropriate key.

- rule: Say `hello` whenever the user sends a message with intent `greet`
- intent: greet
- action: utter_greet

The steps describe what happens when a rule takes effect. Rules also come equipped with several keys you can use to finely control the rule's behavior. The condition key allows you to activate a rule based on the setting of a slot value or whether a form or loop is active (see docs for details). The conversation_start key activates a rule only at the beginning of a conversation. And you can use the wait_for_user_input: false key/value to bypass listening for a response from the user, which is the default next action after a rule is executed. This allows you to execute another action before handing the conversation back to the user.

Check out the docs for usage examples.

Upgrading to Rasa Open Source 2.0

If you have an assistant running version 1.x of Rasa Open Source, we've created several resources to help you upgrade to 2.0 and convert your existing assistant to the new rules format.

Start with the version migration guide located in the docs, which includes detailed information about making the switch. You'll find instructions and resources for converting training data to YAML, as well as best practices for restructuring your stories and policy config. We've made helper scripts available to automate the transition, but you'll also find examples showing how to update mappings, forms, and fallbacks manually.

Lastly, you can check out our 1.x to 2.0 migration blog post for more information about making the update.

Tips for using rules

As we discussed earlier, rule-based dialogue policies and machine learning-based dialogue policies complement each other by accounting for different types of interactions. Some dialogues have fixed responses that can be enforced the same way every time, and some interactions are more contextual and open-ended. We need both types of policies to get a good result, and to train these policies, we need two types of data: rule snippets for the Rule Policy, and stories to train the machine learning model for dialogue.

It's important to carefully consider which behaviors should be controlled with a rule and which would be better served by a story. As a general rule of thumb, start by looking at your existing stories and consider which can be broken out into a rule. You might find that conversation flows that used to require several stories can now be handled with just one or two rules!

We'll list a few quick tips here, and we also recommend checking out our guide to writing conversation data.

Use rules for:

  • Single-turn interactions with fixed responses
  • Chitchat
  • FAQs
  • Conversation "building blocks" like greetings, goodbyes, thank yous and transitions
  • Activating and deactivating forms
  • Triggering a fallback (or 2-stage fallback) response

Use stories for:

  • Multi-turn conversations
  • Situations where you want the model to "learn" to make predictions about conversations it hasn't seen before


The functionality behind the Rule Policy isn't new, but it does represent a big step forward in making dialogue management more approachable and easier to control. Rules existed in previous Rasa versions as separate policies, but learning how each of these policies worked and deciding on a configuration presented a learning curve for new Rasa developers. In Rasa 2.0, we've reduced complexity by consolidating policies based on how they work under the hood, and we've made it simpler for developers to enforce predictable behaviors in their assistants.

Whether you're building a new assistant or upgrading an existing one to 2.0, we'd love to know what you think about the new experience of using rules. Share your feedback in the forum, and check out these additional resources for more information on the Rasa Open Source 2.0 release: