Rasa SDK

3.16.1 · active · verified Thu Apr 16

Rasa SDK is the companion library to Rasa Open Source, enabling developers to write custom actions for their Rasa-powered chatbots. It provides the necessary interfaces and classes (like Action, Tracker, Dispatcher) to interact with the Rasa dialogue management and NLU components. Version 3.16.1 is the current stable release, with frequent updates for bug fixes and minor features, often in sync with Rasa Open Source releases.

Common errors

```
ModuleNotFoundError: No module named 'rasa_sdk.actions'
```
cause Attempting to import `Action` from an incorrect sub-module path.

fix Import `Action` directly from the `rasa_sdk` package: `from rasa_sdk import Action`.
```
rasa.core.agent.AgentException: Action 'my_custom_action' is not a registered custom action.
```
cause The Rasa Open Source server cannot find the custom action. This usually means the custom action server is not running, not configured correctly, or the action name is mismatched.

fix 1. Run the action server: `rasa run actions`. 2. Verify `endpoints.yml` points to the correct action server URL (e.g., `action_endpoint: url: "http://localhost:5055/webhook"`). 3. Ensure the `name()` method in your custom action returns the exact string 'my_custom_action'.
```
TypeError: run() missing 1 required positional argument: 'tracker'
```
cause The `run` method in your custom action has an incorrect signature, missing one of the required arguments (`dispatcher`, `tracker`, or `domain`).

fix Ensure the `run` method signature matches: `async def run(self, dispatcher: CollectingDispatcher, tracker: Tracker, domain: Dict[Text, Any]) -> List[Dict[Text, Any]]:`
```
Could not connect to the custom action server at 'http://localhost:5055/webhook'. Is the server running?
```
cause The Rasa Open Source server failed to establish a connection with the custom action server.

fix 1. Start your custom action server using `rasa run actions`. 2. Check the port and host in `endpoints.yml` and ensure it matches where your action server is listening. 3. Verify no firewall or network issue is blocking the connection. 4. Check action server logs for startup errors.

Warnings

breaking Major version 3.x introduced significant changes from 2.x, particularly for form validation. The `FormAction` class was deprecated, replaced by `FormValidationAction` for better modularity.
Fix: Migrate form validation logic from `FormAction`'s `validate` methods to dedicated `FormValidationAction` classes. Review official Rasa documentation for detailed migration guides.
gotcha The `rasa-sdk` version should ideally match the major version of your `rasa` Open Source installation (e.g., `rasa-sdk==3.x.x` with `rasa==3.x.x`). Mismatched versions can lead to unexpected behavior or `ProtocolError`.
Fix: Always install `rasa-sdk` with a version compatible with your `rasa` Open Source installation. Check the Rasa documentation for compatibility matrices. For example, `pip install 'rasa-sdk==3.*'` if your Rasa Open Source version is 3.
gotcha Custom action server must be running and accessible by the Rasa Open Source server. Common issues include the action server not running, incorrect endpoint configuration in `endpoints.yml`, or port conflicts.
Fix: Ensure `rasa run actions` is running in a separate process. Verify that `endpoints.yml` has the correct URL for your action server (default is `http://localhost:5055/webhook`). Check action server logs for errors.
gotcha The `name()` method in your `Action` class must return a string that exactly matches the action name specified in your `domain.yml` file and used in your stories/rules.
Fix: Double-check for typos or inconsistencies between the `name()` method's return value and your `domain.yml`. An unregistered action will result in an `AgentException`.

Install

pip install rasa-sdk Install latest version

Imports

Action
wrong:
```
from rasa_sdk.actions import Action
```
correct:
```
from rasa_sdk import Action
```
Action is directly exported from the top-level rasa_sdk package since 2.x.
CollectingDispatcher
wrong:
```
from rasa_sdk.dispatcher import Dispatcher
```
correct:
```
from rasa_sdk.executor import CollectingDispatcher
```
The primary dispatcher for custom actions is CollectingDispatcher, found in rasa_sdk.executor.
Tracker
wrong:
```
from rasa_sdk import Tracker
```
correct:
```
from rasa_sdk.tracker import Tracker
```
While sometimes imported from the top-level, it's safer and more explicit to import from its module.
FormValidationAction
wrong:
```
from rasa_sdk.forms import FormAction
```
correct:
```
from rasa_sdk.forms import FormValidationAction
```
FormAction was deprecated in Rasa 3.x and replaced by FormValidationAction for improved validation logic.
SlotSet
wrong:
```
from rasa_sdk.forms import SlotSet
```
correct:
```
from rasa_sdk.events import SlotSet
```
All event classes like SlotSet are found in the rasa_sdk.events module.

Quickstart

This example defines a simple custom action `ActionHelloWorld` that responds with a greeting. It demonstrates importing `Action`, `Tracker`, `CollectingDispatcher`, and `SlotSet`, along with the required `name()` and `run()` methods. The `run` method is made `async` to align with modern Rasa practices, though it's not strictly required for simple actions. To use this action, save it as `actions.py` and run it with `rasa run actions` in a separate terminal while your Rasa bot is running. The action name must be added to your `domain.yml`.

from typing import Any, Text, Dict, List

from rasa_sdk import Action, Tracker
from rasa_sdk.executor import CollectingDispatcher
from rasa_sdk.events import SlotSet

class ActionHelloWorld(Action):

    def name(self) -> Text:
        return "action_hello_world"

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

        user_name = tracker.get_slot("name")
        if not user_name:
            user_name = "there"
        
        dispatcher.utter_message(text=f"Hello {user_name}! This is a custom action.")

        return [SlotSet("name", user_name)]

# To run this, save it as actions.py and then run `rasa run actions` in your terminal.
# Ensure your Rasa project's endpoints.yml is configured to point to this action server.

view raw JSON →