# Rasa SDK

Rasa SDK provides the tools you need to write custom actions in python.

## [Installation](https://legacy-docs-v1.rasa.com/1.9.4/api/rasa-sdk/#installation)

Use `pip` to install `rasa-sdk` on your action server.

```
pip install rasa-sdk
```

Note

You do not need to install `rasa` for your action server.
E.g. if you are running Rasa in a docker container, it is recommended to
create a separate container for your action server. In this
separate container, you only need to install `rasa-sdk`.

## [Running the Action Server](https://legacy-docs-v1.rasa.com/1.9.4/api/rasa-sdk/#running-the-action-server)

If you have `rasa` installed, run this command to start your action server:

```
rasa run actions
```

Otherwise, if you do not have `rasa` installed, run this command:

```
python -m rasa_sdk --actions actions
```

You can verify that the action server is up and running with the command:

```
curl http://localhost:5055/health
```

You can get the list of registered custom actions with the command:

```
curl http://localhost:5055/actions
```

The file that contains your custom actions should be called `actions.py`.
Alternatively, you can use a package directory called `actions` or else
manually specify an actions module or package with the `--actions` flag.

The full list of options for running the action server with either command is:

```
usage: rasa run actions [-h] [-v] [-vv] [--quiet] [-p PORT]
                        [--cors [CORS [CORS ...]]] [--actions ACTIONS]
                        [--ssl-keyfile SSL_KEYFILE]
                        [--ssl-certificate SSL_CERTIFICATE]
                        [--ssl-password SSL_PASSWORD] [--auto-reload]

optional arguments:
  -h, --help            show this help message and exit
  -p PORT, --port PORT  port to run the server at (default: 5055)
  --cors [CORS [CORS ...]]
                        enable CORS for the passed origin. Use * to whitelist
                        all origins (default: None)
  --actions ACTIONS     name of action package to be loaded (default: None)
  --ssl-keyfile SSL_KEYFILE
                        Set the SSL certificate to create a TLS secured
                        server. (default: None)
  --ssl-certificate SSL_CERTIFICATE
                        Set the SSL certificate to create a TLS secured
                        server. (default: None)
  --ssl-password SSL_PASSWORD
                        If your ssl-keyfile is protected by a password, you
                        can specify it using this paramer. (default: None)
  --auto-reload         Enable auto-reloading of modules containing Action
                        subclasses. (default: False)

Python Logging Options:
  -v, --verbose         Be verbose. Sets logging level to INFO. (default:
                        None)
  -vv, --debug          Print lots of debugging statements. Sets logging level
                        to DEBUG. (default: None)
  --quiet               Be quiet! Sets logging level to WARNING. (default:
                        None)
```

## [Actions](https://legacy-docs-v1.rasa.com/1.9.4/api/rasa-sdk/#actions)

The `Action` class is the base class for any custom action. It has two methods
that both need to be overwritten, `name()` and `run()`.

In a restaurant bot, if the user says “show me a Mexican restaurant”,
your bot could execute the action `ActionCheckRestaurants`, which might look like this:

```
from rasa_sdk import Action
from rasa_sdk.events import SlotSet

class ActionCheckRestaurants(Action):
   def name(self) -> Text:
      return "action_check_restaurants"

def run(self,
           dispatcher: CollectingDispatcher,
           tracker: Tracker,
           domain: Dict[Text, Any]) -> List[Dict[Text, Any]]:

cuisine = tracker.get_slot('cuisine')
      q = "select * from restaurants where cuisine='{0}' limit 1".format(cuisine)
      result = db.query(q)

return [SlotSet("matches", result if result is not None else [])]
```

You should add the action name `action_check_restaurants` to
the actions in your domain file. The action’s `run()` method receives
three arguments. You can access the values of slots and the latest message
sent by the user using the `tracker` object, and you can send messages
back to the user with the `dispatcher` object, by calling
`dispatcher.utter_message`.

### Details of the `run()` method:

_async_`Action.``run`( _dispatcher_, _tracker_, _domain_) [¶](https://legacy-docs-v1.rasa.com/1.9.4/api/rasa-sdk/#rasa_sdk.Action.run "Permalink to this definition")

Execute the side effects of this action.

Parameters

- **dispatcher** – the dispatcher which is used to
send messages back to the user. Use
`dipatcher.utter_message()` or any other
`rasa_sdk.executor.CollectingDispatcher`
method.

- **tracker** – the state tracker for the current
user. You can access slot values using
`tracker.get_slot(slot_name)`, the most recent user message
is `tracker.latest_message.text` and any other
`rasa_sdk.Tracker` property.

- **domain** – the bot’s domain

Returns

A dictionary of `rasa_sdk.events.Event` instances that is

returned through the endpoint

Return type
`List`
`[Dict`[`str`, `Any`]
]

### Details of the `dispatcher.utter_message()` method:

`CollectingDispatcher.``utter_message`( _text=None_, _image=None_, _json_message=None_, _template=None_, _attachment=None_, _buttons=None_, _elements=None_, _**kwargs_) [¶](https://legacy-docs-v1.rasa.com/1.9.4/api/rasa-sdk/#rasa_sdk.executor.CollectingDispatcher.utter_message "Permalink to this definition")

“Send a text to the output channel
 
Return type

`None`

### [Customising the session start action](https://legacy-docs-v1.rasa.com/1.9.4/api/rasa-sdk/#customising-the-session-start-action)

The default behaviour of the session start action is to take all existing slots and to
carry them over into the next session. Let’s say you do not want to carry over all
slots, but only a user’s name and their phone number. To do that, you’d override the
`action_session_start` with a custom action that might look like this:

```
from typing import Text, List, Dict, Any

from rasa_sdk import Action, Tracker
from rasa_sdk.events import SlotSet, SessionStarted, ActionExecuted, EventType
from rasa_sdk.executor import CollectingDispatcher

class ActionSessionStart(Action):
    def name(self) -> Text:
        return "action_session_start"

@staticmethod
    def fetch_slots(tracker: Tracker) -> List[EventType]:
        """Collect slots that contain the user's name and phone number."""

slots = []

for key in ("name", "phone_number"):
            value = tracker.get_slot(key)
            if value is not None:
                slots.append(SlotSet(key=key, value=value))

return slots

async def run(
        self,
        dispatcher: CollectingDispatcher,
        tracker: Tracker,
        domain: Dict[Text, Any],
    ) -> List[EventType]:

# the session should begin with a `session_started` event
        events = [SessionStarted()]

# any slots that should be carried over should come after the
        # `session_started` event
        events.extend(self.fetch_slots(tracker))

# an `action_listen` should be added at the end as a user message follows
        events.append(ActionExecuted("action_listen"))

return events
```

Note

You need to explicitly add `action_session_start` to your domain to override this
custom action.

## [Events](https://legacy-docs-v1.rasa.com/1.9.4/api/rasa-sdk/#id6)

An action’s `run()` method returns a list of events. For more information on
the different types of events, see [Events](https://legacy-docs-v1.rasa.com/1.9.4/api/events/#events). There is an example of a `SlotSet` event
above. The action itself will automatically be added to the
tracker as an `ActionExecuted` event. If the action should not trigger any
other events, it should return an empty list.

## [Tracker](https://legacy-docs-v1.rasa.com/1.9.4/api/rasa-sdk/#id7)

The `rasa_sdk.Tracker` lets you access the bot’s memory in your custom
actions. You can get information about past events and the current state of the
conversation through `Tracker` attributes and methods.

The following are available as attributes of a `Tracker` object:

- `sender_id` - The unique ID of person talking to the bot.

- `slots` - The list of slots that can be filled as defined in the
“ref”domains.

- `latest_message` - A dictionary containing the attributes of the latest
message: `intent`, `entities` and `text`.

- `events` - A list of all previous events.

- `active_form` - The name of the currently active form.

- `latest_action_name` - The name of the last action the bot executed.

The available methods from the `Tracker` are:

`Tracker.``current_state`() [¶](https://legacy-docs-v1.rasa.com/1.9.4/api/rasa-sdk/#rasa_sdk.interfaces.Tracker.current_state "Permalink to this definition")

Return the current tracker state as an object.

Return type
`Dict`
`[str`, `Any`]

`Tracker.``is_paused`() [¶](https://legacy-docs-v1.rasa.com/1.9.4/api/rasa-sdk/#rasa_sdk.interfaces.Tracker.is_paused "Permalink to this definition")

State whether the tracker is currently paused.

Return type
`bool`

`Tracker.``get_latest_entity_values`( _entity_type_, _entity_role=None_, _entity_group=None_) [¶](https://legacy-docs-v1.rasa.com/1.9.4/api/rasa-sdk/#rasa_sdk.interfaces.Tracker.get_latest_entity_values "Permalink to this definition")

Get entity values found for the passed entity type and optional role and
group in latest message.

If you are only interested in the first entity of a given type use
next(tracker.get_latest_entity_values(“my_entity_name”), None).
If no entity is found None is the default result.

Parameters

- **entity_type** – the entity type of interest

- **entity_role** – optional entity role of interest

- **entity_group** – optional entity group of interest

Returns

List of entity values.

Return type
`Iterator`
`[str]`

`Tracker.``get_latest_input_channel`() [¶](https://legacy-docs-v1.rasa.com/1.9.4/api/rasa-sdk/#rasa_sdk.interfaces.Tracker.get_latest_input_channel "Permalink to this definition")

Get the name of the input_channel of the latest UserUttered event

Return type
`Optional`
`[str]`

`Tracker.``events_after_latest_restart`() [¶](https://legacy-docs-v1.rasa.com/1.9.4/api/rasa-sdk/#rasa_sdk.interfaces.Tracker.events_after_latest_restart "Permalink to this definition")

Return a list of events after the most recent restart.

Return type
`List`
`[dict]`

`Tracker.``get_slot`( _key_) [¶](https://legacy-docs-v1.rasa.com/1.9.4/api/rasa-sdk/#rasa_sdk.interfaces.Tracker.get_slot "Permalink to this definition")

Retrieves the value of a slot.

Return type
`Optional`
`[Any]`