Rasa is an amazingly flexible open source system for building conversational chat bots. You can quite literally have the basic out-of-the-box bot working in less than 15 minutes. There are a host of tutorials and videos online that explain how to set up, extend and train your bot.
The main reason Rasa is so flexible is that you can build out actions to extend the functionality. If you are familiar with Alexa, you can think of these as added skills. These actions can be as simple as an API call to an external system (ie weather service or joke of the day) or could be setup to walk a user through a set of questions to gather information (think "form"), or you can build actions to interact with an external ERP, other complex system, knowledge base, or really whatever you can think of.
All of these actions are built with python and by default exist as classes in the
actions.py file. You can imagine that this file can get quite large and unwieldy as your bot grows in abilities and functionality. Thankfully there is a way to split up and organize these actions to make development more streamlined. This method is not documented anywhere on the RASA site, although it is fully supported out of the box and requires only a little modification to your project's directory structure, which also helps with organization.
For this tutorial, we'll reference my main project directory
C3PO. I'm on Ubuntu, so I'll also give you the commands to run where necessary, but feel free to perform the necessary steps however you feel comfortable.
From a terminal, lets change to our project's home direcotry:
Create a new directory off of the root of your project's directory called
actions. This is where all of your new action files will live.
You'll end up with something like this:
Now we want to make that actions folder a
package in python. This sounds pretty involved, but really only requires the creating of one file with a special filename.
In the actions directory create an empty file named
__init.py__ That may be hard to tell, but that is 2 underscores before and after the
From your project's home run
That's all, you don't have to edit this file at all, it just has to exist. The actions directory is now considered a package and what that means is that when it is referenced all files in there will be loaded. Perfect.
We can now move our
actions.py file into our package directory. Be sure to not copy it, move it there or else Rasa won't check for the
mv actions.py actions
GREAT. You can consider your
actions.py file "packaged" :) That was pretty easy.
You can stop now and everything will work as it did before, but that's not the point of this article is it.
The first thing you'll want to do is open
actions.py in your code editor.
Create a new file in your
actions directory, the filename is arbitrary. Give it a filename that means something to you. Here is where the organizational part comes in, and only you can know what makes sense.
If you're like me, you have a naming convention throughout your bot, and you've split your NLU, Stories and Domain data already. If you have, you'll probably use that naming style here. For example, I've prefixed all of my actions with an
a and an index number that references internal documentation about that particular element whether that is an intent, story, entity, etc.
Here's an example action filename from one of my bots:
a004-ext-api-bmchelix-create-issue.py I can tell from the text portion that's an external api call to BMC Helix to create an issue (ticket) and I can look up item
004 on my internal documentation and read more about that particular call, if there are other references to entities, etc. Internal docs are super important, especially if you have other developers working with you on this. Even if you're a lone-wolf developer, these bots can get pretty complex, so I can't stress enough about taking your time and taking notes about what you've done.
At the top of this new file, you'll need to copy / paste the top section from your main
actions.py file. This includes all of the code down to the first
Class statement. For me it is all of the
from lines like this:
from typing import Any, Text, Dict, List, Union, Optional
from rasa_sdk import Action, Tracker
from rasa_sdk.executor import CollectingDispatcher
from rasa_sdk.forms import FormAction
from rasa_sdk.events import SlotSet, AllSlotsReset, Restarted, UserUtteranceReverted, ConversationPaused
logger = logging.getLogger(__name__)
That gives your new action file access to all of the RASA related items you'll need for an action.
Then go ahead and move (Cut / Paste) the class or classes from your main
actions.py file that relate to the new file you've created.
Repeat that process as necessary as you want.
Now you'll have an
actions package directory full of
.py action files.
Then nothing. You're done. There's nothing special to do. You can still launch your bot the same way you always have with
rasa run actions and it'll load all of your custom action files as if they were in one file like before.
You can try this to be sure you haven't made an error. Run
rasa run actions and the server should spin up. You'll see all of your action class names scroll onto the screen and it'll sit there waiting for the Rasa server to hit it.
I want this to be useful, so if you discover I've made any errors, let me know and I'll correct them asap.